PyAnnotate

1.2.0 verified Mon Apr 27 auth: no python maintenance

PyAnnotate is a tool by Dropbox that auto-generates PEP-484 type annotations for Python code based on runtime type information collected via a pytest plugin or direct calls. Version 1.2.0 is the latest. It has no active development releases since 2019, making it effectively in maintenance mode.

pip install pyannotate

Common errors

error ModuleNotFoundError: No module named 'pyannotate_tools' ↓

cause PyAnnotate is not installed, or you are importing the wrong module name.

fix

Run 'pip install pyannotate' and use the correct import: 'from pyannotate_tools.annotations import collect_types'.

error AttributeError: module 'pyannotate_tools.annotations' has no attribute 'render_annotations' ↓

cause Older versions of pyannotate did not expose render_annotations publicly.

fix

Upgrade to pyannotate >=1.2.0: 'pip install --upgrade pyannotate'.

error RuntimeError: This package requires Python 3.6 - 3.8 ↓

cause PyAnnotate does not support newer Python versions.

fix

Use Python 3.8 or older, or run collection in a separate environment and apply annotations manually.

Warnings

gotcha The correct import path is 'pyannotate_tools.annotations', not 'pyannotate'. Many outdated tutorials use the wrong module. ↓

fix Use 'from pyannotate_tools.annotations import collect_types' instead of 'from pyannotate import collect_types'.

gotcha PyAnnotate only works with Python 2.7 and 3.6-3.8. It does not support Python 3.9+ or the latest Python versions due to reliance on removed APIs. ↓

fix Use Python 3.8 or lower for collection. For analysis, you can run it on older Python and apply annotations to newer code.

breaking The annotation output format changed between versions. JSON files from older versions may not parse correctly with newer render_annotations. ↓

fix Ensure you regenerate annotation files with the same version of pyannotate used to apply them.

Imports

collect_types
wrong
```
from pyannotate import collect_types
```
correct
```
from pyannotate_tools.annotations import collect_types
```
Most online examples use the wrong import; the correct module is pyannotate_tools.annotations.
pytest_collect_types
```
from pyannotate_tools.pytest_hooks import pytest_collect_types
```
This is the pytest plugin entry point. No common wrong import.

render_annotations

wrong

from pyannotate import render_annotations

correct

from pyannotate_tools.annotations import render_annotations

Same as collect_types; the correct package is pyannotate_tools.

Quickstart

This quickstart demonstrates collecting type data via pytest and then applying annotations to a Python file using pyannotate's tools.

# 1. Collect type information during tests with pytest
# Add to conftest.py:
# from pyannotate_tools.pytest_hooks import pytest_collect_types
# def pytest_configure(config):
#     config.pluginmanager.register(pytest_collect_types())

# 2. Run tests: pytest --annotations-output annotate.json
# 3. Generate annotations in your source files:
import json
from pyannotate_tools.annotations import render_annotations

with open('annotate.json') as f:
    annotations = json.load(f)

# 'code' is the path to your Python file
code = '/path/to/your/module.py'
with open(code) as f:
    source = f.read()

try:
    annotated = render_annotations(source, annotations, path=code)
    if annotated != source:
        with open(code, 'w') as f:
            f.write(annotated)
        print("Annotations applied to", code)
    else:
        print("No annotations to apply")
except Exception as e:
    print("Error:", e)