# pyannotate

**Repository Path**: mirrors_dropbox/pyannotate

## Basic Information

- **Project Name**: pyannotate
- **Description**: Auto-generate PEP-484 annotations
- **Primary Language**: Unknown
- **License**: Apache-2.0
- **Default Branch**: master
- **Homepage**: None
- **GVP Project**: No

## Statistics

- **Stars**: 0
- **Forks**: 0
- **Created**: 2020-09-24
- **Last Updated**: 2026-02-22

## Categories & Tags

**Categories**: Uncategorized

**Tags**: None

## README

PyAnnotate: Auto-generate PEP-484 annotations
=============================================

Insert annotations into your source code based on call arguments and
return types observed at runtime.

For license and copyright see the end of this file.

Blog post: http://mypy-lang.blogspot.com/2017/11/dropbox-releases-pyannotate-auto.html

How to use
==========

See also the example directory.

Phase 1: Collecting types at runtime
------------------------------------

- Install the usual way (see "red tape" section below)
- Add `from pyannotate_runtime import collect_types` to your test
- Early in your test setup, call `collect_types.init_types_collection()`
- Bracket your test execution between calls to `collect_types.start()` and
  `collect_types.stop()` (or use the context manager below)
- When done, call `collect_types.dump_stats(filename)`

All calls between the `start()` and `stop()` calls will be analyzed
and the observed types will be written (in JSON form) to the filename
you pass to `dump_stats()`.  You can have multiple start/stop pairs
per dump call.

If you'd like to automatically collect types when you run `pytest`,
see `example/example_conftest.py` and `example/README.md`.

Instead of using `start()` and `stop()` you can also use a context
manager:
```
collect_types.init_types_collection()
with collect_types.collect():
    <your code here>
collect_types.dump_stats(<filename>)
```

Phase 2: Inserting types into your source code
----------------------------------------------

The command-line tool `pyannotate` can add annotations into your
source code based on the annotations collected in phase 1.  The key
arguments are:

- Use `--type-info FILE` to tell it the file you passed to `dump_stats()`
- Positional arguments are source files you want to annotate
- With no other flags the tool will print a diff indicating what it
  proposes to do but won't do anything.  Review the output.
- Add `-w` to make the tool actually update your files.
  (Use git or some other way to keep a backup.)

At this point you should probably run mypy and iterate.  You probably
will have to tweak the changes to make mypy completely happy.

Notes and tips
--------------

- It's best to do one file at a time, at least until you're
  comfortable with the tool.
- The tool doesn't touch functions that already have an annotation.
- The tool can generate either of:
  - type comments, i.e. Python 2 style annotations
  - inline type annotations, i.e. Python 3 style annotations, using `--py3` in v1.0.7+

Red tape
========

Installation
------------

This should work for Python 2.7 as well as for Python 3.4 and higher.

```
pip install pyannotate
```

This installs several items:

- A runtime module, pyannotate_runtime/collect_types.py, which collects
  and dumps types observed at runtime using a profiling hook.

- A library package, pyannotate_tools, containing code that can read the
  data dumped by the runtime module and insert annotations into your
  source code.

- An entry point, pyannotate, which runs the library package on your files.

For dependencies, see setup.py and requirements.txt.

Testing etc.
------------

To run the unit tests, use pytest:

```
pytest
```

TO DO
-----

We'd love your help with some of these issues:

- Better documentation.
- Python 3 code generation.
- Refactor the tool modules (currently its legacy architecture shines through).

Acknowledgments
---------------

The following people contributed significantly to this tool:

- Tony Grue
- Sergei Vorobev
- Jukka Lehtosalo
- Guido van Rossum

Licence etc.
------------

1. License: Apache 2.0.
2. Copyright attribution: Copyright (c) 2017 Dropbox, Inc.
3. External contributions to the project should be subject to
   Dropbox's Contributor License Agreement (CLA):
   https://opensource.dropbox.com/cla/