Overload read and blocks functions and methods

[hunterhogan]

1. NDArray type for compact typing of indeterminate axes.
2. _2d_float64 TypeAlias, and three more, for compact typing of 2-axis ndarray.
3. T_ndarray TypeVar for out parameter because the ndarray assigned to out is the return type.
4. kwargs_read TypedDict for parameters after out: see notes below.
5. Use keyword names in calls to methods to help the static type checkers.
6. In Generator type, remove the optional None values.
7. In read and blocks methods, add identifer, sound, to help the static type checkers.
8. In each overload definition, the placement of the line breaks might make it easier to see the patterns.
9. out overload is first because it's different, but maybe it should be last.
10. Then overload definitions sorted by the order of the parameters, dtype and always_2d, alphabetical in dtype.

Unpack

If **kwargs: Unpack... were in the primary definition, the parameters in the typed dict would be keyword-only, of course. In the overload definitions, if a user wants to ensure they have the benefit of a static type checker, then they will need to treat some of the parameters in most of the overload definitions are keyword-only, including those in Unpack.

I didn't add Unpack to the overload definition that contains the default values for dtype, always_2d, and out. Therefore, for the default case, for the static type checkers, all parameters are positional-or-keyword. After explaining my "reason", the idea sounds pretty stupid.

[bastibe]

I'm still thinking about this issue, and am still very torn about it.

Could you demonstrate how this changes your IDE behavior, or point me to a video where some other project shows similar behavior?

[hunterhogan]

Could you demonstrate how this changes your IDE behavior

Yes, I happen to be refactoring my universal readAudioFile function right now. The following demonstrates there is a difference, but the type annotations in this function (and the ecosystem it supports) are currently kicking my butt. Therefore, I don't have the confidence to claim that my PR is perfect. (omg, my response is so annoying that I am annoying myself. 🤦)

In case these are helpful, the screenshots show files in these exact commits:

• the readAudioFile function
• the custom soundfile stub file

Current overloads

Giga overloads

[hunterhogan]

Wait, wait, a clearer demonstration!

The above screenshots are absurdly complex.

But in this example, I set a static value for the dtype parameter, SoundFile.read(dtype='float32', always_2d=True), and because of that, the exact shape AND exact dtype can propagate through the different functions.

Because the type checker's inferred return is truncated, ^^^ I put the full inference in the comment.