ci: run mypy --strict in CI and pin the typing toolchain

.github/workflows/pr.yaml

@@ -39,6 +39,21 @@ jobs:
       - name: Run ruff check
         run: uv run ruff check
 
+  typecheck:
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v4
+      - name: Set up Python
+        uses: actions/setup-python@v4
+        with:
+          python-version: '3.10'
+      - name: Install uv
+        uses: astral-sh/setup-uv@v3
+      - name: Install dev dependencies
+        run: uv sync --extra dev
+      - name: Run mypy
+        run: uv run mypy
+
   tests:
     runs-on: ubuntu-latest
     steps:

Makefile

@@ -5,6 +5,7 @@ help:
 	@echo "Targets:"
 	@echo "  help   Show this help message"
 	@echo "  lint   Run linter and format checker (ruff check + ruff format --check)"
+	@echo "  typecheck   Run mypy in strict mode"
 	@echo "  fix    Auto-fix lint issues and format code (ruff check --fix + ruff format)"
 	@echo "  lock   Update uv.lock lockfile"
 	@echo "  build       Install the project with dev and docs dependencies"
@@ -17,6 +18,10 @@ lint: lock
 	uv run ruff check
 	uv run ruff format --check .
 
+.PHONY: typecheck
+typecheck: lock
+	uv run mypy
+
 .PHONY: fix
 fix: lock
 	uv run ruff check --fix --unsafe-fixes
@@ -40,6 +45,7 @@ clean:
 	find . -type d -name __pycache__ -exec rm -rf {} +
 	find . -type d -name .pytest_cache -exec rm -rf {} +
 	find . -type d -name .ruff_cache -exec rm -rf {} +
+	find . -type d -name .mypy_cache -exec rm -rf {} +
 	rm -f .coverage .coverage.* coverage.xml
 	find . -type d -name htmlcov -exec rm -rf {} +
 

pyproject.toml

@@ -34,6 +34,11 @@ dependencies = [
 [project.optional-dependencies]
 dev = [
     "geoarrow-rust-core",
+    "mypy>=2.3.0",
+    "pandas-stubs",
+    # 20260819 is the first release that models ``pc.cast``/``pc.shift_right``
+    # and ``pa.compute.take``; older stubs need per-call ignores.
+    "pyarrow-stubs>=20.0.0.20260819",
     "pytest>=8.4.0",
     "pytest-asyncio>=1.0.0",
     "pytest-cov>=5.0.0",
@@ -67,6 +72,38 @@ ignore = ["E501", "UP045"]
 quote-style = "double"
 
 
+[tool.mypy]
+# ``python_version`` is deliberately unset: it follows the interpreter mypy runs
+# under, so the CI matrix decides which supported Python version is analysed.
+strict = true
+files = ["lance_ray", "tests", "ci"]
+# ``ci`` has no ``__init__.py`` but is imported as ``ci.<module>`` by the tests.
+explicit_package_bases = true
+mypy_path = "."
+enable_error_code = ["ignore-without-code"]
+# ``ray`` and ``lance`` ship a py.typed marker but still expose a number of
+# unannotated public functions. Calling them is unavoidable, so exempt them
+# from ``disallow_untyped_calls`` instead of sprinkling per-call ignores.
+untyped_calls_exclude = ["ray", "lance"]
+
+[[tool.mypy.overrides]]
+module = ["PIL.*", "geoarrow.*", "more_itertools.*"]
+ignore_missing_imports = true
+
+# ``ray`` and ``lance`` ship a py.typed marker but re-export names between
+# their modules without ``__all__`` / ``as`` aliases, which ``strict`` rejects.
+[[tool.mypy.overrides]]
+module = ["lance.*", "ray.*"]
+implicit_reexport = true
+
+# ``tests/_utils.py`` and ``tests/_ray_test_support.py`` are checked as part of
+# the ``tests`` package, but are imported as top-level modules because Ray
+# workers get ``tests/`` prepended to ``sys.path`` instead of the repo root.
+[[tool.mypy.overrides]]
+module = ["_utils", "_ray_test_support"]
+ignore_missing_imports = true
+
+
 [tool.pytest.ini_options]
 testpaths = ["tests"]
 addopts = ["--cov=lance_ray", "--cov-report=term-missing"]