typing (#74)

Author: flying-sheep

.github/workflows/publish.yml

@@ -11,11 +11,9 @@ jobs:
     permissions:
       id-token: write # to authenticate as Trusted Publisher to pypi.org
     steps:
-      - uses: actions/checkout@v5
-      - uses: actions/setup-python@v6
+      - uses: actions/checkout@v7
+      - uses: astral-sh/setup-uv@v9.0.0
         with:
-          python-version: "3.x"
-          cache: pip
-      - run: pip install build
-      - run: python -m build
+          enable-cache: false
+      - run: uv build
       - uses: pypa/gh-action-pypi-publish@release/v1

.github/workflows/pytest.yml

@@ -10,51 +10,56 @@ jobs:
   test:
     strategy:
       matrix:
-        python-version: ["3.9", "3.13"]
+        python-version: ["3.10", "3.14"]
     runs-on: ubuntu-latest
     timeout-minutes: 60
+    env:
+      UV_PYTHON: ${{ matrix.python-version }}
     steps:
-      - name: Checkout
-        uses: actions/checkout@v5
+      - &clone
+        uses: actions/checkout@v7
         with:
           filter: blob:none
           fetch-depth: 0
 
-      - name: Setup Python
-        uses: actions/setup-python@v6
+      - &uv
+        uses: astral-sh/setup-uv@v9.0.0
         with:
-          python-version: ${{ matrix.python-version }}
-          cache: pip
+          enable-cache: true
 
-      - name: Install project and dependencies
-        run: pip install .[annlibs,tests]
+      - &hatch
+        name: Install Hatch
+        # https://github.com/pypa/hatch/pull/2351
+        run: uv tool install git+https://github.com/pypa/hatch.git@af5339a1a5bb8e6d4b659c4c1bfff8e7e37cdaff
 
       - name: Run test suite
-        run: pytest -v --color=yes
+        run: hatch test -py ${{ matrix.python-version }} -v --color=yes
+
+  types:
+    runs-on: ubuntu-latest
+    steps:
+      - *clone
+      - *uv
+      - *hatch
+      - name: Type check
+        run: hatch check types
 
   build:
     runs-on: ubuntu-latest
     steps:
-      - uses: actions/checkout@v5
-        with:
-          filter: blob:none
-          fetch-depth: 0
-      - uses: actions/setup-python@v6
-        with:
-          python-version: "3.x"
-          cache: pip
-      - name: Install tools
-        run: pip install twine build
+      - *clone
+      - *uv
       - name: Build and check
         run: |
-          python -m build
-          twine check dist/*.whl
+          uv build
+          uvx twine check dist/*.whl
 
   check:
     if: always()
     needs:
       - build
       - test
+      - types
     runs-on: ubuntu-latest
     steps:
       # https://github.com/marketplace/actions/alls-green#why

.pre-commit-config.yaml

@@ -1,3 +1,5 @@
+ci:
+  skip: [mypy] # needs hatch to build an env with the ANN libs
 repos:
   - repo: https://github.com/pre-commit/pre-commit-hooks
     rev: v6.0.0
@@ -15,9 +17,19 @@ repos:
   - repo: https://github.com/astral-sh/ruff-pre-commit
     rev: v0.16.1
     hooks:
-      - id: ruff
+      - id: ruff-check
         args: ["--fix"]
       - id: ruff-format
+  - repo: local
+    hooks:
+      - id: mypy
+        name: mypy
+        entry: hatch check types
+        language: system
+        types: [python]
+        files: ^(src|tests)/
+        require_serial: true
+        pass_filenames: false
   - repo: https://github.com/pre-commit/mirrors-prettier
     rev: v4.0.0-alpha.8
     hooks:

.readthedocs.yaml

@@ -0,0 +1,20 @@
+# https://docs.readthedocs.io/en/stable/config-file/v2.html
+version: 2
+build:
+  os: ubuntu-26.04
+  tools:
+    python: "3.14"
+  jobs:
+    post_checkout:
+      # unshallow so version can be derived from tag
+      - git fetch --unshallow || true
+    create_environment:
+      - asdf plugin add uv
+      - asdf install uv latest
+      - asdf global uv latest
+      # https://github.com/pypa/hatch/pull/2351
+      - UV_TOOL_BIN_DIR=$HOME/.asdf/bin uv tool install git+https://github.com/pypa/hatch.git@af5339a1a5bb8e6d4b659c4c1bfff8e7e37cdaff
+    build:
+      html:
+        - hatch run docs:build
+        - mv docs/_build $READTHEDOCS_OUTPUT

.readthedocs.yml

@@ -3,6 +3,7 @@
 # This file only contains a selection of the most common options. For a full
 # list see the documentation:
 # https://www.sphinx-doc.org/en/master/usage/configuration.html
+from __future__ import annotations
 
 import os
 

docs/conf.py

@@ -7,28 +7,38 @@
 
 """
 
+from __future__ import annotations
+
+from typing import TYPE_CHECKING
+
 import numpy as np
 from joblib import Memory
 from sklearn import metrics
 from sklearn.datasets import fetch_openml
 
 from sklearn_ann.cluster.rnn_dbscan import simple_rnn_dbscan_pipeline
 
+if TYPE_CHECKING:
+    from collections.abc import Callable
+    from typing import Any
+
 
 # #############################################################################
 # Generate sample data
-def fetch_mnist():
+def fetch_mnist() -> tuple[Any, Any]:
     print("Downloading mnist_784")
-    mnist = fetch_openml("mnist_784")
-    return mnist.data / 255, mnist.target
+    data, target = fetch_openml("mnist_784", return_X_y=True)
+    return data / 255, target
 
 
 memory = Memory("./mnist")
 
 X, y = memory.cache(fetch_mnist)()
 
 
-def run_rnn_dbscan(neighbor_transformer, n_neighbors, **kwargs):
+def run_rnn_dbscan(
+    neighbor_transformer: Callable[..., Any], n_neighbors: int, **kwargs: Any
+) -> None:
     # #############################################################################
     # Compute RnnDBSCAN
 

examples/rnn_dbscan_big.py

@@ -9,6 +9,8 @@
 
 """
 
+from __future__ import annotations
+
 import numpy as np
 from sklearn import metrics
 from sklearn.datasets import make_blobs
@@ -34,7 +36,7 @@
 
 # Number of clusters in labels, ignoring noise if present.
 n_clusters_ = len(set(labels)) - (1 if -1 in labels else 0)
-n_noise_ = list(labels).count(-1)
+n_noise_ = int((labels == -1).sum())
 
 print(f"""\
 Estimated number of clusters: {n_clusters_}

examples/rnn_dbscan_simple.py

@@ -9,26 +9,13 @@ license = "BSD-3-Clause"
 urls.Source = "https://github.com/scikit-learn-contrib/sklearn-ann"
 urls.Documentation = "https://sklearn-ann.readthedocs.io/"
 dynamic = ["version", "readme"]
-requires-python = ">=3.9"
+requires-python = ">=3.10"
 dependencies = [
     "scikit-learn>=1.6.0",
     "scipy>=1.11.1,<2.0.0",
 ]
 
 [project.optional-dependencies]
-tests = [
-    "pytest>=6.2.1",
-    "pytest-cov>=2.10.1",
-]
-docs = [
-    "sphinx>=7",
-    "sphinx-gallery>=0.8.2",
-    "sphinx-book-theme>=1.1.0",
-    "sphinx-issues>=1.2.0",
-    "numpydoc>=1.1.0",
-    "matplotlib>=3.3.3",
-    "scanpydoc",
-]
 annoy = [
     "annoy>=1.17.0,<2.0.0",
 ]
@@ -46,6 +33,26 @@ annlibs = [
     "sklearn-ann[annoy,faiss,pynndescent,nmslib]",
 ]
 
+[dependency-groups]
+docs = [
+    "sphinx>=7",
+    "sphinx-gallery>=0.8.2",
+    "sphinx-book-theme>=1.1.0",
+    "sphinx-issues>=1.2.0",
+    "numpydoc>=1.1.0",
+    "matplotlib>=3.3.3",
+    "scanpydoc",
+]
+tests = [
+    "pytest>=6.2.1",
+    "pytest-cov>=2.10.1",
+]
+typing = [
+    "mypy",
+    "matplotlib",  # examples are type checked, too
+    "scipy-stubs",
+]
+
 [tool.hatch.version]
 source = "vcs"
 
@@ -74,6 +81,7 @@ select = [
     "PTH", # Pathlib
     "RUF", # Ruff’s own rules
     "T20", # print statements
+    "TC",  # type checking
 ]
 ignore = [
     # Don’t complain about “confusables”
@@ -84,19 +92,51 @@ ignore = [
 "tests/*.py" = ["T20"]
 [tool.ruff.lint.isort]
 known-first-party = ["sklearn_ann"]
+required-imports = ["from __future__ import annotations"]
+[tool.ruff.lint.flake8-type-checking]
+exempt-modules = []
+strict = true
 
 [tool.hatch.envs.docs]
 installer = "uv"
-features = ["docs", "annlibs"]
+features = ["annlibs"]
+dependency-groups = ["docs"]
 scripts.build = "sphinx-build -M html docs docs/_build"
 
+[tool.hatch.envs.hatch-check-types]
+features = ["annlibs"]
+dependency-groups = ["tests", "typing"]
+scripts.check = "mypy {args:.}"
+
 [tool.hatch.envs.hatch-test]
 default-args = []
-features = ["tests", "annlibs"]
+features = ["annlibs"]
+dependency-groups = ["tests"]
 
 [tool.hatch.build.targets.wheel]
 packages = ["src/sklearn_ann"]
 
+[tool.mypy]
+python_version = "3.12"
+mypy_path = ["src", "tests"]
+strict = true
+explicit_package_bases = true # pytest doesn’t do __init__.py
+no_implicit_optional = true
+disallow_untyped_decorators = false # e.g. pytest.mark.parametrize
+follow_untyped_imports = true
+# follow_untyped_imports makes these readable, but not annotated
+untyped_calls_exclude = ["sklearn", "joblib", "pynndescent"]
+
+[[tool.mypy.overrides]]
+# pynndescent has no __all__, so its re-exports are implicit
+module = ["pynndescent"]
+no_implicit_reexport = false
+
+[[tool.mypy.overrides]]
+# nmslib is a compiled extension module without stubs
+module = ["nmslib"]
+ignore_missing_imports = true
+
 [build-system]
 requires = ["hatchling", "hatch-vcs", "hatch-fancy-pypi-readme"]
 build-backend = "hatchling.build"