feat: add .pyi stub validation with stubtest and pyright

.github/workflows/test.yml

@@ -33,10 +33,11 @@ jobs:
           python-version: ${{ matrix.python-version }}
 
       - name: Install dependencies
-        run: python -m pip install -U pip 'setuptools>=45' pytest
+        run: python -m pip install -U pip 'setuptools>=45' pytest pyright
 
       - name: Run tests
         run: |
           python setup.py build_ext --inplace
           python -m unittest discover -vv tests
           ./bench.sh
+

pyproject.toml

@@ -12,3 +12,21 @@ build-frontend = "build"
 [[tool.cibuildwheel.overrides]]
 select = "*-ios*"
 build-frontend = "build"
+
+[tool.mypy]
+warn_unused_configs = true
+disallow_any_generics = true
+disallow_subclassing_any = true
+disallow_untyped_calls = true
+# disallow_untyped_defs = true
+disallow_incomplete_defs = true
+check_untyped_defs = true
+disallow_untyped_decorators = true
+no_implicit_optional = true
+warn_redundant_casts = true
+warn_unused_ignores = true
+warn_return_any = true
+implicit_reexport = false
+strict_equality = true
+pretty = true
+error_summary = false

tests/test_stubs_pyright.py

@@ -0,0 +1,81 @@
+"""Validate the .pyi type stubs using pyright."""
+
+import subprocess
+import tempfile
+import unittest
+from pathlib import Path
+
+
+class TestStubsPyright(unittest.TestCase):
+    def _run_pyright(self, source: str) -> subprocess.CompletedProcess:
+        """Run pyright on a temporary file with the given source.
+
+        The file is placed under the repo root so pyright can discover the
+        xxhash package and its .pyi stubs via pyproject.toml.
+        """
+        repo_root = Path(__file__).resolve().parent.parent
+        with tempfile.NamedTemporaryFile(
+            mode="w",
+            suffix=".py",
+            prefix="__pyright_check_",
+            dir=repo_root,
+            delete=False,
+        ) as f:
+            f.write(source)
+            tmp_path = f.name
+
+        try:
+            return subprocess.run(
+                ["pyright", "--project", str(repo_root), tmp_path],
+                capture_output=True,
+                text=True,
+                cwd=repo_root,
+                timeout=30,
+            )
+        finally:
+            Path(tmp_path).unlink(missing_ok=True)
+
+    def test_valid_buffer_types(self):
+        """Valid buffer types should type-check without errors."""
+        code = """\
+import xxhash
+
+h1 = xxhash.xxh32(b"hello")
+h1.update(b"world")
+xxhash.xxh32_digest(b"hello")
+
+h2 = xxhash.xxh32(bytearray(b"hello"))
+h2.update(bytearray(b"world"))
+
+h3 = xxhash.xxh32(memoryview(b"hello"))
+h3.update(memoryview(b"world"))
+
+h4 = xxhash.xxh32()
+h4.update(b"test")
+"""
+        result = self._run_pyright(code)
+        if result.returncode != 0:
+            self.fail(
+                f"pyright reported errors for valid buffer types:\n"
+                f"{result.stdout}\n{result.stderr}"
+            )
+
+    def test_str_is_rejected(self):
+        """str should be rejected (not a buffer type)."""
+        code = """\
+import xxhash
+xxhash.xxh32("hello")
+"""
+        result = self._run_pyright(code)
+        if result.returncode == 0:
+            self.fail("pyright did not reject str argument")
+
+    def test_int_is_rejected(self):
+        """int should be rejected (not a buffer type)."""
+        code = """\
+import xxhash
+xxhash.xxh32(42)
+"""
+        result = self._run_pyright(code)
+        if result.returncode == 0:
+            self.fail("pyright did not reject int argument")

xxhash/__init__.pyi

@@ -1,21 +1,50 @@
-import array
-from typing import Union
-from typing_extensions import final, Buffer
+from typing import Protocol, final
 
-# __buffer__ protocol makes this redundant on python 3.12+
-Buffer.register(array.ArrayType)
-_InputType = Union[str, Buffer]
+class _Buffer(Protocol):
+    """Objects that support the buffer protocol (PEP 688)."""
+    def __buffer__(self, flags: int, /) -> memoryview: ...
+
+_DataType = _Buffer
 
 VERSION: str
 XXHASH_VERSION: str
 #: Deprecated, will be removed in the next major release
 VERSION_TUPLE: tuple[int, ...]
 
 algorithms_available: set[str]
+algorithms_guaranteed: set[str]
+
+__all__: list[str] = [
+    "xxh32",
+    "xxh32_digest",
+    "xxh32_intdigest",
+    "xxh32_hexdigest",
+    "xxh64",
+    "xxh64_digest",
+    "xxh64_intdigest",
+    "xxh64_hexdigest",
+    "xxh3_64",
+    "xxh3_64_digest",
+    "xxh3_64_intdigest",
+    "xxh3_64_hexdigest",
+    "xxh3_128",
+    "xxh3_128_digest",
+    "xxh3_128_intdigest",
+    "xxh3_128_hexdigest",
+    "xxh128",
+    "xxh128_digest",
+    "xxh128_intdigest",
+    "xxh128_hexdigest",
+    "VERSION",
+    "VERSION_TUPLE",
+    "XXHASH_VERSION",
+    "algorithms_available",
+    "algorithms_guaranteed",
+]
 
 class _Hasher:
-    def __init__(self, input: _InputType = ..., seed: int = ...) -> None: ...
-    def update(self, input: _InputType) -> None: ...
+    def __init__(self, data: _DataType = ..., seed: int = ...) -> None: ...
+    def update(self, data: _DataType) -> None: ...
     def digest(self) -> bytes: ...
     def hexdigest(self) -> str: ...
     def intdigest(self) -> int: ...
@@ -44,17 +73,17 @@ class xxh3_128(_Hasher): ...
 xxh64 = xxh3_64
 xxh128 = xxh3_128
 
-def xxh32_digest(args: _InputType, seed: int = ...) -> bytes: ...
-def xxh32_hexdigest(args: _InputType, seed: int = ...) -> str: ...
-def xxh32_intdigest(args: _InputType, seed: int = ...) -> int: ...
+def xxh32_digest(data: _DataType, seed: int = ...) -> bytes: ...
+def xxh32_hexdigest(data: _DataType, seed: int = ...) -> str: ...
+def xxh32_intdigest(data: _DataType, seed: int = ...) -> int: ...
 
-def xxh3_64_digest(args: _InputType, seed: int = ...) -> bytes: ...
-def xxh3_64_hexdigest(args: _InputType, seed: int = ...) -> str: ...
-def xxh3_64_intdigest(args: _InputType, seed: int = ...) -> int: ...
+def xxh3_64_digest(data: _DataType, seed: int = ...) -> bytes: ...
+def xxh3_64_hexdigest(data: _DataType, seed: int = ...) -> str: ...
+def xxh3_64_intdigest(data: _DataType, seed: int = ...) -> int: ...
 
-def xxh3_128_digest(args: _InputType, seed: int = ...) -> bytes: ...
-def xxh3_128_hexdigest(args: _InputType, seed: int = ...) -> str: ...
-def xxh3_128_intdigest(args: _InputType, seed: int = ...) -> int: ...
+def xxh3_128_digest(data: _DataType, seed: int = ...) -> bytes: ...
+def xxh3_128_hexdigest(data: _DataType, seed: int = ...) -> str: ...
+def xxh3_128_intdigest(data: _DataType, seed: int = ...) -> int: ...
 
 xxh64_digest = xxh3_64_digest
 xxh64_hexdigest = xxh3_64_hexdigest

xxhash/version.py

@@ -1,3 +1,3 @@
-VERSION = "3.8.0.dev6"
+VERSION = "3.8.0.dev7"
 #: Deprecated, will be removed in the next major release
 VERSION_TUPLE = (3, 8, 0)