Ecosyste.ms: Awesome

An open API service indexing awesome lists of open source software.

Awesome Lists | Featured Topics | Projects

https://github.com/dropbox/pyannotate

Auto-generate PEP-484 annotations
https://github.com/dropbox/pyannotate

Last synced: 4 days ago
JSON representation

Auto-generate PEP-484 annotations

Awesome Lists containing this project

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():

    

collect_types.dump_stats()

```



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/