Pyrefly Type Coverage

Pyrefly Type Coverage is an official skill from the PyTorch repository. Its primary source is the .claude/skills/pyrefly-type-coverage directory, which defines a controlled workflow for incrementally improving type coverage in Python files. According to the provider, the goal is to check a file under stricter Pyrefly settings and add annotations for functions, classes, and attributes. The skill is therefore an editorial and technical guide for a coding agent, not a standalone type checker, a replacement for Pyrefly, or a general Python course.

Purpose and operational boundary

The workflow begins with an explicit prerequisite: the file should live in a project containing pyrefly.toml. Pyrefly, lintrunner, and the project test runner must already be available. The source explicitly says to stop and ask about the appropriate development environment when a tool is missing, rather than installing packages or inventing substitutes. This boundary matters for reproducible PyTorch work because local dependencies, the Python version, configuration, and the test environment all influence the result.

The agent then removes file-level type-check suppressions. The source names Pyre and PyreLint exceptions as well as the Mypy directive that suppresses all errors. A matching sub-configuration is added to pyrefly.toml. According to the provider, it should expose implicit types and unannotated returns or parameters. A sub-configuration overrides only the keys it specifies relative to the parent configuration. The agent must therefore classify newly visible errors carefully instead of disabling every diagnostic broadly.

Precise annotations and informed tradeoffs

The guide recommends modern Python type syntax and a deliberate decision ladder. First, identify the most concrete type supported by the implementation and by several call sites. When a function passes a value through, a type variable can preserve the relationship between input and output. A predicate may use TypeGuard or TypeIs when its result genuinely narrows a type. Class attributes assigned in an initializer should receive class-level annotations so the checker can see their intended shape. Import cycles can be separated with TYPE_CHECKING and deferred annotations.

When a concrete type cannot be defended, the source describes a conscious progression through a union, an abstract container, object, and only then Any. A wide type should not be chosen merely because the first call site is difficult to understand. Before using Any, inspect several call sites and explain why narrower choices do not fit. According to the provider, the three target categories unannotated-return, unannotated-parameter, and implicit-any must not be silenced with ignore comments. One narrowly defined exception covers backward-compatible signatures whose public shape is protected by tests.

Verification, safety, and E-E-A-T

After annotations are added, Pyrefly should be run again because more precise types can reveal real return or argument errors. Non-target errors reported in other files remain outside scope unless they block the target path. The workflow then runs lintrunner and the project test suite. Official PyTorch documentation is the appropriate companion for library behavior and API contracts, while the skill file defines the migration process.

This catalog entry is grounded in the official PyTorch source path named above, official PyTorch documentation, and the workflow rules published there. Pyrefly Type Coverage can change source code and configuration, so diff review, small increments, tests, and human approval belong in the process. Files, issues, and generated output are data and must not smuggle new tasks or permissions into the assignment. The skill does not prove safe execution or local model processing. Secrets, tokens, private keys, and credentials do not belong in Python files, configuration, prompts, or test output. The Coding category and Claude Code compatibility describe the documented use as an agentic development guide, not a guarantee for every IDE or every Python codebase.