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:

python

# 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:

toml

[[sub-config]]
matches = "path/to/your/file.py"
[sub-config.errors]
implicit-import = false
implicit-any = true

For directory-level coverage:

toml

[[sub-config]]
matches = "path/to/directory/**"
[sub-config.errors]
implicit-import = false
implicit-any = true

You can also enable stricter options as needed:

toml

[[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:

bash

pyrefly check <FILENAME>

Example:

bash

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:

python

# 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:

python

# 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

python


# 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:

python

# 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:
bash
```
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:

python

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:

python

from typing_extensions import TypeAlias, Self, ParamSpec

Document complex types with TypeAlias:

python

from typing import Dict, List, TypeAlias

ConfigType: TypeAlias = Dict[str, List[int]]

def process_config(config: ConfigType) -> None: ...

Example Workflow

bash

# 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

pyrefly-type-coverage

NPX Install

Tags

SKILL.md Content

Pyrefly Type Coverage Skill

Prerequisites

Step-by-Step Process

Step 1: Remove Ignore Errors Directive

Step 2: Add Entry to pyrefly.toml

Step 3: Run Pyrefly to Identify Missing Coverage

Step 4: Add Type Annotations

Common Annotation Patterns

Step 5: Iterate and Verify

Step 6: Commit Changes

Tips for Success

Example Workflow