Type Checker Setup

Configuring mypy and pyright, running them in CI, and fixing the errors they report. Short notes on pyrefly and ty at the end.

#Contents

• Which checker
• mypy configuration
• pyright configuration
• Strictness flags explained
• Running in CI and pre-commit
• Suppressing errors correctly
• Debugging types
• Error catalogue with fixes
• pyrefly and ty

#Which checker

Many teams run pyright (or Pylance) in the editor and mypy (or pyright) in CI. Pick one checker as the CI source of truth; running both doubles the suppression work because they disagree on edge cases.

#mypy configuration

pyproject.toml:

[tool.mypy]
python_version = "3.11"
files = ["src", "tests"]
strict = true                       # see the flag list below
warn_unreachable = true
enable_error_code = ["ignore-without-code", "redundant-expr", "truthy-bool", "possibly-undefined"]
plugins = ["pydantic.mypy"]
mypy_path = "stubs"
exclude = ["^build/", "^notebooks/"]

[tool.pydantic-mypy]
init_forbid_extra = true
init_typed = true
warn_required_dynamic_aliases = true

# untyped third-party libraries
[[tool.mypy.overrides]]
module = ["faiss.*", "sentence_transformers.*", "legacy_rerank.*"]
ignore_missing_imports = true

# legacy code being migrated: checked, but not strict yet
[[tool.mypy.overrides]]
module = ["app.legacy.*"]
disallow_untyped_defs = false
disallow_incomplete_defs = false
check_untyped_defs = true

# tests: allow unannotated test functions
[[tool.mypy.overrides]]
module = ["tests.*"]
disallow_untyped_defs = false

Run: mypy (uses files), mypy src/app/llm.py, mypy -p app. Useful CLI flags: --strict, --python-version 3.10, --show-error-codes (default on), --pretty, --install-types --non-interactive (fetch missing types-* stubs), --cache-dir, --html-report out/ / --txt-report (needs lxml for HTML) for coverage of typed lines.

#pyright configuration

pyproject.toml (or pyrightconfig.json with the same keys):

[tool.pyright]
include = ["src", "tests"]
exclude = ["**/__pycache__", "build", "notebooks"]
pythonVersion = "3.11"
typeCheckingMode = "strict"          # "off" | "basic" | "standard" (default) | "strict"
stubPath = "stubs"
venvPath = "."
venv = ".venv"
reportMissingTypeStubs = false       # noisy for libraries without stubs
reportUnknownMemberType = false      # relax individual strict rules while migrating
reportUnnecessaryTypeIgnoreComment = "warning"
reportImplicitOverride = "warning"   # require @override (opt-in)
strict = ["src/app/core"]            # strict for these paths even if the default mode is lower

Per-file: # pyright: strict or # pyright: basic at the top of a file; per-rule: # pyright: reportUnknownMemberType=false.

Run: pyright / npx pyright / pip install pyright (wraps the Node package), pyright --verifytypes mypkg (reports the completeness of a library's public API types; great before adding py.typed), pyright --outputjson. basedpyright is a community fork with extra rules and a baseline file feature.

#Strictness flags explained

mypy strict = true enables:

Not in strict, worth enabling: warn_unreachable, disallow_any_unimported, disallow_any_explicit (very strict), enable_error_code = ["ignore-without-code", "explicit-override", "possibly-undefined", "truthy-bool"].

pyright modes:

#Running in CI and pre-commit

GitHub Actions:

name: types
on: [push, pull_request]
jobs:
  typecheck:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4
      - uses: actions/setup-python@v5
        with:
          python-version: "3.12"
          cache: pip
      - run: pip install -e ".[dev]"             # includes mypy/pyright, stubs, plugins
      - run: mypy
      - run: python tools/annotation_audit.py src --min-coverage 85   # vendored copy of this skill's script

pre-commit (mypy runs in an isolated env, so list the stubs and typed deps it needs):

repos:
  - repo: https://github.com/pre-commit/mirrors-mypy
    rev: v1.13.0
    hooks:
      - id: mypy
        additional_dependencies: [pydantic, types-requests, types-PyYAML, numpy]
        args: [--config-file=pyproject.toml]
  - repo: https://github.com/RobertCraigie/pyright-python
    rev: v1.1.389
    hooks:
      - id: pyright

Pin the checker version (mypy==1.x.y, pyright==1.1.xyz); new releases add checks and will break CI unannounced otherwise. Use ruff's UP (pyupgrade) rules (UP006, UP007, UP035, UP040, UP045, UP046, UP047) to autofix legacy typing syntax, and ANN rules to require annotations, and set ruff's target-version to the same minimum Python.

#Suppressing errors correctly

result = legacy.score(q)  # type: ignore[no-untyped-call]  # vendored lib, no stubs (TICKET-123)
value = data["k"]         # pyright: ignore[reportTypedDictNotRequiredAccess]

assert isinstance(x, T) also narrows, and documents an invariant (but is stripped with python -O; raise explicitly for real validation).

#Debugging types

from typing import reveal_type, assert_type        # 3.11 (typing_extensions before)

reveal_type(store.search(q))                        # checker prints the inferred type
assert_type(first(["a"]), str)                      # checker error if the type differs

reveal_type without an import also works in mypy and pyright (they treat it as a builtin), but at runtime it is a NameError before 3.11 unless imported. reveal_locals() (mypy only) prints all local types. In VS Code, hover shows pyright's inferred type.

#Error catalogue with fixes

#None-related

#Annotations missing or incomplete

#Container variance and generics

#Classes and inheritance

#Calls

#Imports and modules

#TypedDict, Literal, Protocol

#Any leaks

#pyrefly and ty

Two newer checkers written in Rust focus on speed (whole-repo checks in seconds) and IDE integration:

Both aim at compatibility with the typing spec, but their error codes and inference differ from mypy and pyright. Treat them as fast extra feedback (or evaluate them for the editor) and keep a mature checker as the CI gate until your codebase is clean under the new tool. Annotations written per the typing spec work unchanged in all four checkers.