How to integrate PyAnnotate with pytest for automatic type collection?

Add a conftest.py file that uses collect_types to bracket test execution, as shown in the example directory; this allows types to be collected during pytest runs without modifying test code directly.

PyAnnotate vs manual annotation for legacy Python code: which is better?

PyAnnotate is faster for bulk annotation by inferring types from runtime, but manual annotation offers more precision for complex cases; use PyAnnotate for an initial pass and refine manually based on mypy feedback.

Can PyAnnotate generate type hints for async functions or generics?

It infers types from runtime calls, so if async functions are exercised in tests, it may capture them, but advanced features like generics might require manual adjustment due to limitations in inference.

How to make PyAnnotate output inline annotations for Python 3?

Use the --py3 flag when running the pyannotate command-line tool in version 1.0.7 or higher to generate inline type annotations instead of type comments.

What to do if PyAnnotate annotations cause mypy errors?

Manually tweak the generated annotations, as recommended in the README, to fix type mismatches or add missing types like unions or optional values that weren't fully captured.

Is PyAnnotate suitable for annotating Django or Flask web projects?

Yes, but ensure test suites adequately exercise web framework code to capture dynamic behaviors, and be prepared for manual refinement due to complex request/response types.

Open-Awesome

pyannotate

Apache-2.0Python

Automatically generates PEP-484 type annotations for Python code by analyzing runtime behavior.

GitHub

1.4k stars60 forks0 contributors

What is pyannotate?

PyAnnotate is a Python tool that automatically generates PEP-484 type annotations by analyzing function calls and return types observed during runtime execution. It solves the problem of manually adding type hints to large existing codebases by inferring types from actual program behavior and inserting appropriate annotations into source code.

Target Audience

Python developers working with large legacy codebases who want to add type annotations efficiently, and teams adopting static type checking with mypy who need to annotate existing functions.

Value Proposition

Developers choose PyAnnotate because it dramatically reduces the manual effort required to add type annotations by automatically inferring types from runtime behavior, supports both Python 2 and 3 annotation styles, and integrates seamlessly with existing test suites.

Overview

Auto-generate PEP-484 annotations

Use Cases

Best For

Adding type annotations to large legacy Python codebases
Accelerating adoption of mypy static type checking in existing projects
Generating initial type hints for unannotated Python libraries
Reducing manual annotation work during Python 2 to Python 3 migrations
Inferring complex type relationships from actual runtime behavior
Integrating type annotation generation into existing pytest test suites

Not Ideal For

Projects that cannot execute code for type collection due to security or environment constraints
Codebases with highly dynamic or polymorphic types not fully exercised in test suites
Teams expecting fully accurate annotations without any post-generation manual adjustment

Pros & Cons

Pros

Runtime Type Inference

Infers types from actual runtime behavior during test execution, as implemented in the collect_types module for observing function calls.

Automatic Annotation Insertion

Generates and inserts PEP-484 annotations directly into source files based on collected JSON data, reducing manual effort.

Flexible Output Formats

Supports both Python 2-style type comments and Python 3-style inline annotations with the --py3 flag, aiding migration.

Test Integration

Easily integrates with pytest through configuration files like example_conftest.py, allowing seamless type collection during test runs.

Cons

Dependence on Test Coverage

Type inference relies on runtime data from tests; incomplete test suites can lead to missing or inaccurate annotations.

Manual Refinement Needed

The README admits that generated annotations often require tweaking to satisfy mypy, adding overhead after automation.

Legacy Architecture and Docs

The TO DO section highlights needs for better documentation and refactoring, which can hinder usability and maintenance.

Frequently Asked Questions

Related Projects

pyre-check

Performant type-checking for python.

Stars7,171

Forks452

Last commit29 days ago

monkeytype

A Python library that generates static type annotations by collecting runtime types

Stars5,002

Forks209

Last commit5 months ago

RightTyper

A fast and efficient type assistant for Python, including tensor shape inference

Stars359

Forks7

Last commit2 months ago

autotyping

Automatically add simple type annotations to your code

Stars287

Forks23

Last commit10 months ago

Community-curated · Updated weekly · 100% open source

Found a gem we're missing?

Open-Awesome is built by the community, for the community. Submit a project, suggest an awesome list, or help improve the catalog on GitHub.

Submit a project Star on GitHub