Merge pull request #462 from Geson-anko/master

Add type hints to all public methods, functions and classes

Author: bastibe

.github/workflows/python-package.yml

@@ -54,3 +54,23 @@ jobs:
         run: pip install --editable . --verbose
       - name: Run tests
         run: python -m pytest
+
+  type-check:
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v4
+        with:
+          submodules: true
+      - uses: actions/setup-python@v5
+        with:
+          python-version: "3.9"
+      - name: Install requirements
+        run: pip install numpy pytest pyright
+      - name: "Workaround: Generate _soundfile.py explicitly"
+        run: |
+          pip install cffi>=1.0
+          python soundfile_build.py
+      - name: Install editable package
+        run: pip install --editable . --verbose
+      - name: Run type check
+        run: python -m pyright soundfile.py

CONTRIBUTING.rst

@@ -14,7 +14,7 @@ regressions), if you add a feature, you should add tests for it as well.
 
 Set up local environment with the following commands::
 
-   pip install numpy pytest "cffi>=1.0"
+   pip install numpy pytest "cffi>=1.0" typing-extensions
    python soundfile_build.py
 
 To run the tests, use::
@@ -35,6 +35,30 @@ This uses pytest_;
 
    .. _known problem: http://www.mega-nerd.com/libsndfile/api.html#open_fd
 
+Type Checking
+^^^^^^^^^^^^^
+
+Type hints have been added to the codebase to support static type checking. 
+You can use pyright to check the types:
+
+.. code-block:: bash
+
+   pip install pyright
+   pyright soundfile.py
+
+Or you can use the VS Code extension for inline type checking.
+
+When contributing, please maintain type hints for all public functions, methods, and classes.
+Make sure to use appropriate types from the typing and typing-extensions modules.
+
+The following conventions are used:
+
+- Use Literal types for enumerated string values
+- Use TypeAlias for complex type definitions
+- Use overloads to provide precise return type information
+- Use Optional for parameters that can be None
+- Use Union for values that can be different types
+
 Coverage
 ^^^^^^^^
 

pyrightconfig.json

@@ -0,0 +1,9 @@
+{
+    "pythonVersion": "3.9",
+    "exclude": [
+      "**/node_modules",
+      "**/__pycache__",
+      "**/.venv",
+      "tests/"
+    ]
+}

setup.py

@@ -96,7 +96,7 @@ def get_tag(self):
     zip_safe=zip_safe,
     license='BSD 3-Clause License',
     setup_requires=["cffi>=1.0"],
-    install_requires=['cffi>=1.0', 'numpy'],
+    install_requires=['cffi>=1.0', 'numpy', 'typing-extensions'],
     cffi_modules=["soundfile_build.py:ffibuilder"],
     extras_require={'numpy': []}, # This option is no longer relevant, but the empty entry must be left in to avoid breaking old build scripts.
     platforms='any',