Set up Pyrefly Type Coverage

This guide complements PyTorch’s official Pyrefly Type Coverage source. It describes a controlled development workflow and does not replace project-specific checks for Python versions, dependencies, or CI rules.

Check prerequisites

Start in an existing development environment containing pyrefly.toml. Confirm that Pyrefly, lintrunner, and the project test runner are already available. If a tool is missing, stop and clarify the environment with the project team. Do not install substitute tools independently and do not place credentials in configuration files.

Remove suppressions deliberately

Inspect the top of the file for global Pyre, PyreLint, and Mypy suppressions. Remove only the rules named by the official source, then inspect the diff. A global suppression can hide previously unseen errors; removing it should improve analysis and does not justify a large unreviewed change.

Add a sub-configuration

Add a sub-configuration for the target path in pyrefly.toml. Enable the provider’s named checks for unannotated returns, unannotated parameters, and implicit Any types. Mirror parent configuration settings where the project needs them. Record the scope so that the change does not accidentally affect unrelated directories.

Develop annotations

Work on one manageable section at a time. Read several call sites before choosing a broad type. Prefer concrete types, useful unions, abstract containers, or object. Use Any only when the dynamic boundary is real and the decision can be explained. Predicates may use TypeGuard or TypeIs when they genuinely guarantee narrowing. Signatures with explicit backward-compatibility protection require the special treatment described by the primary source.

Verify and approve

Run Pyrefly again after each meaningful change. Fix real errors in the target file and leave out-of-scope diagnostics alone unless they block the target. Then run lintrunner and the relevant tests. Review the complete diff for unintended configuration changes, new dependencies, and instructions copied from files. Only after this technical review should the change enter the team branch.