Python typing: mypy, pyright, ty

A typing fix is done when every target checker sees the precise type at the call sites users write, proven with assert_type probes. "The errors are gone" is not done: mypy and ty silently turn unfinished fixes into Any / Unknown.

Do not report done until all four hold:

1. Every public function and method you edited that callers reach through the requested API has a precise return annotation (unannotated is Any in mypy, Unknown in ty; only pyright infers). Leave private helpers and closures alone; Any added to satisfy coverage is not a fix.
2. A probe asserts the result type of each API the request names, plus one line that must error, and is clean under every target checker.
3. Each suppression you added was reported as needed by a checker, and none is unused.
4. The project's own checker invocations and tests pass.

Verified with mypy 2.4.0, pyright 1.1.414, basedpyright 1.40.2, ty 0.0.86, Python 3.14.

Workflow

1. Detect and baseline

Use the checkers, config and exact commands that pre-commit and CI run, with the project's venv (mypy --python-executable .venv/bin/python, pyright --pythonpath .venv/bin/python, ty check --python .venv). Record error counts by rule before editing.

• pyrightconfig.json replaces [tool.pyright]; ty.toml replaces [tool.ty]; an unknown [tool.ty] key makes ty exit 2.
• mypy and pyright target python_version / pythonVersion, else the interpreter; ty targets the lower bound of requires-python.

2. Fix with the first rung that works

1. The code or the annotation. Real bugs get fixed; config errors get fixed in config.
2. A precise construct: @overload, Protocol, TypeVar / ParamSpec, Self, TypeIs, generic defaults, descriptor __get__ overloads (recipes: references/patterns.md).
3. Declarations under if TYPE_CHECKING: for members created at runtime. Runtime unchanged.
4. A .pyi stub next to the module, or a stub package for a third-party gap.
5. One cast inside one helper, never at call sites.
6. A narrow, coded suppression on the exact line (see Suppressions).

When checkers disagree on correct code, see references/cross-checker.md. Keep the change typing-only: no runtime validation, no behavior changes, nothing on code paths the request does not reach. Fix no-any-return from json.loads with an annotated local (data: dict[str, str] = json.loads(raw)). Prefer object, type[C], Callable[..., R] or a TypeVar to Any.

3. Prove it with a probe

Write a throwaway _probe.py inside the project root and check it with every target checker:

from __future__ import annotations
from typing_extensions import assert_type   # typing.assert_type needs 3.11+ in pyright and ty

from pkg import Widget, make_widget


def probe() -> None:                         # annotated: mypy skips unannotated bodies
    w = make_widget("a")
    assert_type(w, Widget)                   # assert results, not callables or coroutines
    assert_type(w.size(), int)
    w.missing_attribute                      # must error: proves w is not Any

• assert_type is exact (assert_type(1, int) fails on Literal[1]): assert on calls to annotated functions and on await coro() results.
• Runtime tests do not prove static types. Delete the probe unless the project keeps type tests (references/library-authoring.md).

4. Finish

Run the project's checker commands and tests, then walk the four "done" conditions. Prove each added suppression with unused-ignore checks on (mypy --warn-unused-ignores, pyright reportUnnecessaryTypeIgnoreComment, ty by default) and delete what they flag; list them with git diff -U0 | grep -E '^\+.*#\s*(type|pyright|ty):\s*ignore'. Edit with the editor tool: BSD sed -i (macOS) needs ''.

Suppressions

Copy the code from the output: mypy [code], pyright trailing (reportRule), ty error[rule]. Never guess names (reportPossiblyUnbound is wrong; it is reportPossiblyUnboundVariable, and pyright reports the wrong name as unnecessary).

• mypy reads # type: ignore only as the first comment on the line.
• Never write the combined # type: ignore[code, ty:rule]: mypy reports the ty: part unused. Write separate comments: # type: ignore[code] # ty: ignore[rule].
• With default pyright, a # type: ignore[code] for a mypy-only error is reported unnecessary by pyright; the per-checker recipe is in references/cross-checker.md.
• Never add a suppression before running the checker that needs it.

Facts that differ from intuition

Pattern index (references/patterns.md)

References