Add type hints to all public methods, functions and classes

[Geson-anko]

I've added Python type hints to the soundfile.py ! All public methods, functions, and classes now have type annotations to support static type checking with pyright.

Key improvements:

• Added precise type definitions (Literals, Unions, Optional, etc.)
• Created specialized types (FileDescriptorOrPath, AudioData, etc.)
• Utilized typing and typing-extensions packages
• Implemented overloads for accurate return type definitions
• Added type hints without modifying existing functionality

This implements the type hints requested in Issue #461. The changes enable better IDE autocompletion and error detection through static type checkers like pyright.

Looking forward to your review!

[bastibe]

To be honest, I am very conflicted about this PR. Type hints add so much noise and complexity to the code base, without providing too much benefit to the way I like to code. However, much though I'm not a fan, I recognize that type hints are a modern feature of Python that some programmers rely on. But I'd ask you to find a bit of a compromise between verbosity and completeness.

In particular, the very fine grained literals and overloads are too much. They add dozens of lines of code, and duplication, which is a maintenance burden I am not willing to carry.

I also don't like the casting and reformatting, which seem unnecessary, and do not make the code clearer.

If you see these things differently, I'm open to discuss them. But please offer concrete examples of how these features improve particular workflows if you deem them necessary.

[Geson-anko]

First of all, thank you very much for reviewing my PR. As shown in the PR, I frequently use type hints in Python and have built many systems this way. In this PR, I tried to make the typing as complete as possible.

However, as you pointed out, detailed literals and overloads can make the program excessively complex. I'm happy to follow the maintainer's wishes, and I can certainly implement simpler type hints with fewer changes by avoiding detailed literals and overloads. Specifically, I could change literals to just str and remove all overloads in favor of Unions. (Though this would mean the dtype of NumPy NDArray return values in read and blocks functions would become Any).

For reference, the benefit of using literals is that they allow validation of possible string patterns before executing the code. Overloads also enable more precise inference by type checkers, making this library easier to use in more robust systems.

However, I also recognize this might be overengineering for what is essentially a simple Python wrapper for libsndfile.

What format would you prefer for the final version? I'm very happy to be able to contribute to soundfile.

[bastibe]

Let's try to make the type hints as minimal as possible. Perhaps you can generate the literals from the existing dictionaries? I definitely don't want the list of keys duplicated in the dicts and the literals.

[Geson-anko]

Thank you for providing direction. I'll work to minimize duplication as much as possible.

However, Literals need to explicitly enumerate all possible values when they are defined. Therefore, generating them dynamically from dictionaries is difficult from a type system perspective.

[Geson-anko]

@bastibe Work done!

[bastibe]

Thank you very much. I'm much happier with the current state of the code.

I read up on the spaces around default argument assignments with type hints, and found your initial commit to be correct. My apologies for that. You can revert to putting spaces around default argument assignments if you want.

Regarding your comments on a formatter, I have found them too restrictive in the past. This may have changed in the meantime, however, and I would love to hear your perspective on the matter.

I would also be interested in your opinion on the current state of this pull request. Does it still help your coding, or have we removed too much?

Regardless, this now looks good to me, and can be merged if you deem it ready.

[Geson-anko]

Thank you for checking. I will revert the spacing issue.

Regarding formatters, I consider them very important for maintaining clean code when multiple people are developing a codebase. Using ruff would be a good choice nowadays.
However, I've never felt restricted by formatters. It's generally good practice to write a config and register it in a GitHub workflow to automatically maintain a readable codebase. I often use pre-commit hooks, which could also be an option.
Either way, I won't apply a formatter for this PR, but I recommend implementing one in the future.
See my configurations:

• pre-commit config
• ruff settings
• github workflow

As for the current state of the PR, I think it's fine. I've confirmed that functions like check_format handle exceptions appropriately. Strict typing simply allows you to check such things statically without writing explicit handling code.
At the very least, I'm very happy that we can avoid type checkers producing errors due to missing stub files, which eliminates the need to write stub files for individual projects.

[Geson-anko]

@bastibe Ready!

[bastibe]

Thank you very much for your contribution!

[Gautzilla]

Hi @bastibe,

Do you plan on publishing a new release of soundfile that includes these changes? I just added mypy to a project that uses soundfile and the type hints would help lightening it.

Thanks a lot!

[bastibe]

A new release of soundfile is in the works, but my spare time for this is limited at the moment.