signal: Add type stubs to _waveforms.pyi.

[pavyamsiri]

Contributes to closing #99.

Adds type stubs to the file _waveforms.pyi and corresponding type tests to test overload coverage for the function gausspulse.

Notes

I am not used to the new optype.numpy types so tell me if I did anything suboptimally or wrong.

Also for chirp I found that for the float dtypes, float16 and float32 that the output dtype is same as the input dtype but for everything else that is float64. I wanted to make an overload to cover this behaviour but I don't know how to do it without the overloads overlapping.

Technically for some of functions you can pass in complex dtypes and it will work fine, but the functions want times and I don't think they were expecting imaginary times i.e. some functions return just the real part but the array would be complex dtype if the input is complex. For this reason I didn't allow complex arrays.

Funny Bug

Also I discovered a 19 year old bug in scipy. The intention of sawtooth and square is that the output dtype is the same as the input t's dtype if the dtype is float32 or float64 otherwise it is always float64. But the check for float32 can never pass because

if t.dtype.char in ['fFdD']:
    ytype = t.dtype.char
else:
    ytype = 'd'

is checking if a single character string is an element of a list of a single string instead of checking if the character is part of the string like t.dtype.char in 'fFdD'.

This makes the type checking easier because the return type is only a single possible type, but I find it a bit funny that this has been here for so long.

[jorenham]

I am not used to the new optype.numpy types so tell me if I did anything suboptimally or wrong.

That's of course no problem. I'm actually didn't expect you to notice the new optype at all haha.

You're already using the ToFloat and ToInt correctly 👌🏻.
For the ToInt{1,2,N}D array-like aliases, there's only one (subtle) difference with the np._typing._ArrayLike{}_co analogues which you might have missed, namely that they don't accept "bare" scalars like float or np.float16. That way, the e.g. ToFloat and ToFloatND types don't overload, which can help a lot when writing overloads. It does so by additionally requiring a __len__ method to be implemented in the new onp.CanArrayND protocol, instead of just __array__ like with np._typing._SupportsArray.

Also for chirp I found that for the float dtypes, float16 and float32 that the output dtype is same as the input dtype but for everything else that is float64. I wanted to make an overload to cover this behaviour but I don't know how to do it without the overloads overlapping.

I left a suggestion on a possible way to deal with that. But it's also fine by me without any overloads. Because usually functions that accept e.g. float64 arrays, also accept float16 arrays (although there are a couple of exceptions to this as you know).

Technically for some of functions you can pass in complex dtypes and it will work fine, but the functions want times and I don't think they were expecting imaginary times i.e. some functions return just the real part but the array would be complex dtype if the input is complex. For this reason I didn't allow complex arrays.

Ah yes I commented on one such case before I read this. As I also said there; I have no idea what "complex time" is used for, and have never seen it used in statistical and econometric literature. But if you decide to allow it, be sure to use a separate overload, so that real input results in real output.
Anyway, I'll leave this decision up to you.

[pavyamsiri]

The gausspulse function has such a weird API. I did all the overloads I believe but this does bloat the stubs quite a bit.

[pavyamsiri]

It seems for some reason, the literal "cutoff" overlaps with onp.ToFloatND? Only for mypy it seems, pyright doesn't see an overlap.

[pavyamsiri]

I think mypy gets confused because of the definition of ToFloatND

ToFloatND: TypeAlias = _To1D[_f_co, float] | Sequence["ToFloatND"]

The self-referential type is ignored by mypy and it substitutes "ToFloatND" with ... meaning str fits because it is a Sequence[str] which leads to overload overlaps.

[jorenham]

I think mypy gets confused because of the definition of ToFloatND

ToFloatND: TypeAlias = _To1D[_f_co, float] | Sequence["ToFloatND"]

The self-referential type is ignored by mypy and it substitutes "ToFloatND" with ... meaning str fits because it is a Sequence[str] which leads to overload overlaps.

Yea you're right:
https://mypy-play.net/?mypy=latest&python=3.12&flags=strict&gist=18fea0a692fc85f5da18d00bc578b2fa

from collections.abc import Sequence
from typing import TypeAlias

FloatVector: TypeAlias = Sequence[float]
FloatTensor: TypeAlias = FloatVector | Sequence["FloatTensor"]

rejected_float_vector: FloatVector = "ok"       # OK: rejected

accepted_float_tensor: FloatTensor = [[[3.14]]] # OK: accepted
rejected_float_vector1: FloatTensor = object()  # OK: rejected
rejected_float_vector2: FloatTensor = "fail"    # FAIL: accepted

So even though recursive types should be supported since mypy 1.7 (python/mypy#731), in this case, it results in a false negative

[jorenham]

As it turns out, this isn't limited to float sequences.

I raised it at python/mypy#18184

In the meantime, I'll try to figure out a workaround for this and publish a new optype release.

[jorenham]

@pavyamsiri I released a new optype version that includes the workaround. So if you rebase your branch, then the overlapping overload errors should disappear.

[pavyamsiri]

@pavyamsiri I released a new optype version that includes the workaround. So if you rebase your branch, then the overlapping overload errors should disappear.

Thanks for the help with the mypy bug. There's an issue remaining with the overloads for chirp however. I guess the new change has caused pyright to think onp.ToFloatND to overlap with numpy._typing._ArrayLike and so we get conflicting overlaps.

[pavyamsiri]

The simplest fix would be to just leave one of the overloads out, unless you know of a way to avoid this.

[jorenham]

I guess the new change has caused pyright to think onp.ToFloatND to overlap with numpy._typing._ArrayLike and so we get conflicting overlaps.

Well, I suppose that'd be correct; they actually overlap. I'm not sure why before this it wasn't detected though 🤷🏻. I had to change quite a lot of overloads because of this as well in #197. So maybe you a similar approach I used there to solve it in this case.

[pavyamsiri]

I managed to avoid the overlap but I am not convinced the overloads work as intended. I tried making some type tests like passing np.zeros(4, dtype=np.float16) as t and there was no suitable overload for chirp.

[jorenham]

I managed to avoid the overlap but I am not convinced the overloads work as intended. I tried making some type tests like passing np.zeros(4, dtype=np.float16) as t and there was no suitable overload for chirp.

hmmm 🤔
Well in this case you could also brute force it by overloading each of the float{16,32,64} cases.
But I also don't mind if you just return an np.floating[Any] there, or keep it as it currently is. I'd be happy to merge either way. So let me know if I should

[pavyamsiri]

Yeah I think I will go with the Any approach because I fear the brute force approach will be combinatorially explosive due to the other parameters.

I added an overload to differentiate between scalar and non scalar array likes. Should be able to be merged now.

[jorenham]

Thanks Pavadol!