pyrefly-type-coverage

A guided procedure for migrating a single Python file to stricter Pyrefly type checking, where annotations are required for all functions, parameters, classes, and attributes. It is written for the PyTorch codebase and assumes the file lives in a project with a pyrefly.toml and that pyrefly, lintrunner, and the test runner are on PATH — if any are missing, it says to stop and ask about activating a conda environment rather than installing substitutes.

The workflow has four steps. First, remove file-level suppressions such as # pyre-ignore-all-errors, its bracketed variants, # @lint-ignore-every PYRELINT, and # mypy: ignore-errors. Second, add a [[sub-config]] entry to pyrefly.toml matching the directory and enabling the strict error keys (unannotated-return, unannotated-parameter, implicit-any), with a caution that turning these on resurfaces previously hidden errors and that unrelated categories can be mirrored from the parent config to silence them. Third, run pyrefly check on the file. Fourth, add annotations to resolve the three target categories, which must never be suppressed except for a single @compatibility(is_backward_compatible=True) carve-out.

Much of the value is in the detailed annotation conventions: PEP 604 / PEP 585 syntax, preferring collections.abc over typing, always parameterizing Callable (favoring Callable[..., object]), using TypeVar and ParamSpec when a return type derives from a parameter, TypeGuard or TypeIs for boolean predicates, class-level annotations for attributes set in __init__, and breaking import cycles with TYPE_CHECKING plus from __future__ import annotations. It also encodes a torch naming convention (leading underscores for introduced module-local globals) and a widening ladder — most specific type, then a union or bound TypeVar, then object, and only as a last rung Any — so annotations widen deliberately instead of reaching for an ignore. Errors originating outside the target file are left alone or suppressed at the report site with a TODO comment.