IMPR: Type annotations

[d-v-b]

The codebase currently lacks type hints. Adding type hints would greatly increase the ability for static type checkers like mypy to enforce type-safety and catch bugs at type-checking time.

Adding mypy or an equivalent type checker to pre-commit would help maintain type-safety during the development process.

Operationally, I would suggest adding a type checker like mypy to the pre-commit configuration, but exempting all modules from type checking (because they would all fail).

One by one, modules would be added to mypy's scope, and that module would receive complete type annotations. This should be a safe way to gradually type the entire codebase.

[github-actions]

This issue is stale because it has been open for 45 days with no activity.

[dimitri-yatsenko]

Implemented in DataJoint 2.0

Added mypy type checking with gradual adoption strategy as suggested.

Changes (commit 27391c7)

pyproject.toml - mypy configuration:

[tool.mypy]
python_version = "3.10"
ignore_missing_imports = true
check_untyped_defs = true

# Modules with complete type coverage - strict checking enabled
[[tool.mypy.overrides]]
module = ["datajoint.content_registry"]
disallow_untyped_defs = true
disallow_incomplete_defs = true
warn_return_any = true

# Modules excluded from type checking until fully typed
[[tool.mypy.overrides]]
module = ["datajoint.admin", "datajoint.autopopulate", ...]  # 28 modules
ignore_errors = true

.pre-commit-config.yaml - mypy hook:

- repo: https://github.com/pre-commit/mirrors-mypy
  rev: v1.14.1
  hooks:
    - id: mypy
      files: ^src/datajoint/
      additional_dependencies:
        - pydantic
        - pydantic-settings
        - types-PyMySQL
        - types-tqdm
        - pandas-stubs
        - numpy

Gradual Adoption Strategy

1. Now: content_registry.py has strict type checking (100% typed)
2. Next: Move modules from ignore_errors = true to strict as they're fully typed
3. Goal: Eventually enable strict checking for all modules

Current Type Coverage

Metric	Status
Functions with return annotations	244 / 527 (46%)
Files with from __future__ import annotations	18 / 33 (55%)
Modules with strict mypy	1 / 33
mypy in pre-commit	✅

Developers can now gradually type modules and move them to strict checking.

[dimitri-yatsenko]

@d-v-b Take a look and I will close as completed (as a gradual policy)