Pyrefly 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