signal: Add type stubs to _spectral_py.pyi.

[pavyamsiri]

Contributes to completing #99.

I added type stubs to the stub file signal/_spectral_py.pyi and tests for the function overloads I added.

Caveats

I discovered that the function lombscargle was recently updated to include new parameters which also expands the possible return types (see PR scipy/scipy#21277). It also adds inline type stubs which might be an issue.

I did not type stub against this new version though because I think it is still in the dev branch and is not part of a release.

Also I saw that the function periodogram's docs don't specify that None is allowed for the argument window but the body explicitly checks for None. Therefore I allowed None to be passed in as well. This is a bit annoying because the type annotation is no longer consistent with other window arguments in other functions.

I could have perhaps used more shaped typing but its a bit hard to verify because the functions are a bit complex, so I just left things as any shape.

[jorenham]

I did not type stub against this new version though because I think it is still in the dev branch and is not part of a release.

Yea, that'll be in the scipy 1.15.0 release (see https://discuss.scientific-python.org/t/proposed-release-schedule-for-scipy-1-15-0/1502 for the release schedule).

---

Also I saw that the function periodogram's docs don't specify that None is allowed for the argument window but the body explicitly checks for None. Therefore I allowed None to be passed in as well. This is a bit annoying because the type annotation is no longer consistent with other window arguments in other functions.

Yea good catch. This is not the first time that the docs are incorrect unfortunately. And I agree with you judgement call here, because as stated in our code of conduct:

Practicality beats purity
Consistency beats practicality
Validity beats consistency

---

I could have perhaps used more shaped typing but its a bit hard to verify because the functions are a bit complex, so I just left things as any shape.

Yea it's usually better to avoid guessing the return type, and go with the "safe" option. Plus, shape-typing is somewhere at the bottom of the (hypothetical) priority list, so no worries.

[jorenham]

Nice job on the type-tests! I should probably do that more often as well haha.

I left a couple of small suggestions, but in general this looks very good to me 👌🏻.

[pavyamsiri]

I think all the issues should be addressed now.

[jorenham]

Apart from an issue with float128 and complex256 (which is actually more of an issue with numpy), I'm be happy to merge this; the other comments I leave up to your judgement.

[pavyamsiri]

Good now?

[jorenham]

Thanks again, @pavyamsiri 😄

[jorenham]

@pavyamsiri Do you think that the "phase" of scipy.signal in the README.md could be updated from 🌒 to 🌓?