pyrefly-type-coverage

name	pyrefly-type-coverage
description	Migrate a file to use stricter Pyrefly type checking with annotations required for all functions, classes, and attributes.

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:

1. Read the function/code carefully - Understand what the function does
2. Examine usage patterns - Look at how the function is called to understand expected types
3. 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:

1. Re-run pyrefly check to verify errors are resolved:

   pyrefly check <FILENAME>
   

2. Fix any new errors that may appear from the annotations you added

3. 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

1. Start with function signatures - Return types and parameter types are usually the highest priority

2. Use from __future__ import annotations - Add this at the top of the file for forward references:

   from __future__ import annotations
   

3. Leverage type inference - Pyrefly can infer many types; focus on function boundaries

4. Check existing type stubs - For external libraries, check if type stubs exist

5. Use typing_extensions for newer features - For compatibility:

   from typing_extensions import TypeAlias, Self, ParamSpec
   

6. 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

# 6. Repeat until clean