Pyrefly Type Coverage Skill
This skill guides you through improving type coverage in Python files using Pyrefly, Meta's type checker. Follow this systematic process to add proper type annotations to files.
Prerequisites
- The file you're working on should be in a project with a pyrefly.toml configuration
Step-by-Step Process
Step 1: Remove Ignore Errors Directive
First, locate and remove any pyre-ignore-all-errors comments at the top of the file:
REMOVE lines like these:
pyre-ignore-all-errors
pyre-ignore-all-errors[16,21,53,56]
@lint-ignore-every PYRELINT
These directives suppress type checking for the entire file and must be removed to enable proper type coverage.
Step 2: Add Entry to pyrefly.toml
Add a sub-config entry for stricter type checking. Open pyrefly.toml and add an entry following this pattern:
[[sub-config]] matches = "path/to/your/file.py" [sub-config.errors] implicit-import = false implicit-any = true
For directory-level coverage:
[[sub-config]] matches = "path/to/directory/**" [sub-config.errors] implicit-import = false implicit-any = true
You can also enable stricter options as needed:
[[sub-config]] matches = "path/to/your/file.py" [sub-config.errors] implicit-import = false implicit-any = true
Uncomment these for stricter checking:
unannotated-attribute = true
unannotated-parameter = true
unannotated-return = true
Step 3: Run Pyrefly to Identify Missing Coverage
Execute the type checker to see all type errors:
pyrefly check <FILENAME>
Example:
pyrefly check torch/_dynamo/utils.py
This will output a list of type errors with line numbers and descriptions. Common error types include:
-
Missing return type annotations
-
Missing parameter type annotations
-
Incompatible types
-
Missing attribute definitions
-
Implicit Any usage
CRITICAL: Your goal is to resolve all errors. If you cannot resolve an error, you can use # pyrefly: ignore[...] to suppress but you should try to resolve the error first
Step 4: Add Type Annotations
Work through each error systematically:
-
Read the function/code carefully - Understand what the function does
-
Examine usage patterns - Look at how the function is called to understand expected types
-
Add appropriate annotations - Add type hints based on your analysis
Common Annotation Patterns
Function signatures:
Before
def process_data(items, callback): ...
After
from collections.abc import Callable def process_data(items: list[str], callback: Callable[[str], bool]) -> None: ...
Class attributes:
Before
class MyClass: def init(self): self.value = None self.items = []
After
class MyClass: value: int | None items: list[str]
def __init__(self) -> None:
self.value = None
self.items = []
Complex types: CRITICAL: use syntax for Python >3.10 and prefer collections.abc as opposed to typing for better code standards.
Critical: For more advanced/generic types such as TypeAlias , TypeVar , Generic , Protocol , etc. use typing_extensions
Optional values
def get_value(key: str) -> int | None: ...
Union types
def process(value: str | int) -> str: ...
Dict and List
def transform(data: dict[str, list[int]]) -> list[str]: ...
Callable
from collections.abc import Callable def apply(func: Callable[[int, int], int], a: int, b: int) -> int: ...
TypeVar for generics
from typing_extensions import TypeVar T = TypeVar('T') def first(items: list[T]) -> T: ...
Using # pyre-ignore for specific lines:
If a specific line is difficult to type correctly (e.g., dynamic metaprogramming), you can ignore just that line:
pyrefly: ignore[attr-defined]
result = getattr(obj, dynamic_name)()
CRITICAL: Avoid using # pyre-ignore unless it is necessary. When possible, we can implement stubs, or refactor code to make it more type-safe.
Step 5: Iterate and Verify
After adding annotations:
Re-run pyrefly check to verify errors are resolved:
pyrefly check <FILENAME>
Fix any new errors that may appear from the annotations you added
Repeat until clean - Continue until pyrefly reports no errors
Step 6: Commit Changes
To keep type coverage PRs manageable, you should commit your change once finished with a file.
Tips for Success
Start with function signatures - Return types and parameter types are usually the highest priority
Use from future import annotations
- Add this at the top of the file for forward references:
from future import annotations
Leverage type inference - Pyrefly can infer many types; focus on function boundaries
Check existing type stubs - For external libraries, check if type stubs exist
Use typing_extensions for newer features - For compatibility:
from typing_extensions import TypeAlias, Self, ParamSpec
Document complex types with TypeAlias:
from typing import Dict, List, TypeAlias
ConfigType: TypeAlias = Dict[str, List[int]]
def process_config(config: ConfigType) -> None: ...
Example Workflow
1. Open the file and remove pyre-ignore-all-errors
2. Add entry to pyrefly.toml
3. Check initial errors
pyrefly check torch/my_module.py
4. Add annotations iteratively
5. Re-check after changes
pyrefly check torch/my_module.py