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/
Raw data
{
"_id": null,
"home_page": "https://github.com/dropbox/pyannotate",
"name": "pyannotate",
"maintainer": "",
"docs_url": null,
"requires_python": "",
"maintainer_email": "",
"keywords": "",
"author": "Dropbox",
"author_email": "guido@dropbox.com",
"download_url": "https://files.pythonhosted.org/packages/0d/26/2f68c02fae0b88d9cefdbc632edad190d61621b5660c72c920be1e52631e/pyannotate-1.2.0.tar.gz",
"platform": "POSIX",
"description": "PyAnnotate: Auto-generate PEP-484 annotations\n=============================================\n\nInsert annotations into your source code based on call arguments and\nreturn types observed at runtime.\n\nFor license and copyright see the end of this file.\n\nBlog post: http://mypy-lang.blogspot.com/2017/11/dropbox-releases-pyannotate-auto.html\n\nHow to use\n==========\n\nSee also the example directory.\n\nPhase 1: Collecting types at runtime\n------------------------------------\n\n- Install the usual way (see \"red tape\" section below)\n- Add `from pyannotate_runtime import collect_types` to your test\n- Early in your test setup, call `collect_types.init_types_collection()`\n- Bracket your test execution between calls to `collect_types.start()` and\n `collect_types.stop()` (or use the context manager below)\n- When done, call `collect_types.dump_stats(filename)`\n\nAll calls between the `start()` and `stop()` calls will be analyzed\nand the observed types will be written (in JSON form) to the filename\nyou pass to `dump_stats()`. You can have multiple start/stop pairs\nper dump call.\n\nIf you'd like to automatically collect types when you run `pytest`,\nsee `example/example_conftest.py` and `example/README.md`.\n\nInstead of using `start()` and `stop()` you can also use a context\nmanager:\n```\ncollect_types.init_types_collection()\nwith collect_types.collect():\n <your code here>\ncollect_types.dump_stats(<filename>)\n```\n\nPhase 2: Inserting types into your source code\n----------------------------------------------\n\nThe command-line tool `pyannotate` can add annotations into your\nsource code based on the annotations collected in phase 1. The key\narguments are:\n\n- Use `--type-info FILE` to tell it the file you passed to `dump_stats()`\n- Positional arguments are source files you want to annotate\n- With no other flags the tool will print a diff indicating what it\n proposes to do but won't do anything. Review the output.\n- Add `-w` to make the tool actually update your files.\n (Use git or some other way to keep a backup.)\n\nAt this point you should probably run mypy and iterate. You probably\nwill have to tweak the changes to make mypy completely happy.\n\nNotes and tips\n--------------\n\n- It's best to do one file at a time, at least until you're\n comfortable with the tool.\n- The tool doesn't touch functions that already have an annotation.\n- The tool can generate either of:\n - type comments, i.e. Python 2 style annotations\n - inline type annotations, i.e. Python 3 style annotations, using `--py3` in v1.0.7+\n\nRed tape\n========\n\nInstallation\n------------\n\nThis should work for Python 2.7 as well as for Python 3.4 and higher.\n\n```\npip install pyannotate\n```\n\nThis installs several items:\n\n- A runtime module, pyannotate_runtime/collect_types.py, which collects\n and dumps types observed at runtime using a profiling hook.\n\n- A library package, pyannotate_tools, containing code that can read the\n data dumped by the runtime module and insert annotations into your\n source code.\n\n- An entry point, pyannotate, which runs the library package on your files.\n\nFor dependencies, see setup.py and requirements.txt.\n\nTesting etc.\n------------\n\nTo run the unit tests, use pytest:\n\n```\npytest\n```\n\nTO DO\n-----\n\nWe'd love your help with some of these issues:\n\n- Better documentation.\n- Python 3 code generation.\n- Refactor the tool modules (currently its legacy architecture shines through).\n\nAcknowledgments\n---------------\n\nThe following people contributed significantly to this tool:\n\n- Tony Grue\n- Sergei Vorobev\n- Jukka Lehtosalo\n- Guido van Rossum\n\nLicence etc.\n------------\n\n1. License: Apache 2.0.\n2. Copyright attribution: Copyright (c) 2017 Dropbox, Inc.\n3. External contributions to the project should be subject to\n Dropbox's Contributor License Agreement (CLA):\n https://opensource.dropbox.com/cla/\n\n\n",
"bugtrack_url": null,
"license": "Apache 2.0",
"summary": "PyAnnotate: Auto-generate PEP-484 annotations",
"version": "1.2.0",
"split_keywords": [],
"urls": [
{
"comment_text": "",
"digests": {
"blake2b_256": "0af02d6c59cc0662d922421df7a15e428e268fd750b9b257ddd12f167fe2402e",
"md5": "e5e96642eb0e3c221dd057fdb479d010",
"sha256": "bc2b5b4ea57aa90f99da9d71b547262eed19ea4b6ba355bf57439eeab9b90e93"
},
"downloads": -1,
"filename": "pyannotate-1.2.0-py2.py3-none-any.whl",
"has_sig": false,
"md5_digest": "e5e96642eb0e3c221dd057fdb479d010",
"packagetype": "bdist_wheel",
"python_version": "py2.py3",
"requires_python": null,
"size": 31675,
"upload_time": "2019-09-16T15:37:03",
"upload_time_iso_8601": "2019-09-16T15:37:03.333422Z",
"url": "https://files.pythonhosted.org/packages/0a/f0/2d6c59cc0662d922421df7a15e428e268fd750b9b257ddd12f167fe2402e/pyannotate-1.2.0-py2.py3-none-any.whl",
"yanked": false,
"yanked_reason": null
},
{
"comment_text": "",
"digests": {
"blake2b_256": "0d262f68c02fae0b88d9cefdbc632edad190d61621b5660c72c920be1e52631e",
"md5": "6d1fcafc9b773560ed72aa3873910b48",
"sha256": "04ed5804bab38153d5981fc92d83dcf6a22883453768561f057e777e5c057599"
},
"downloads": -1,
"filename": "pyannotate-1.2.0.tar.gz",
"has_sig": false,
"md5_digest": "6d1fcafc9b773560ed72aa3873910b48",
"packagetype": "sdist",
"python_version": "source",
"requires_python": null,
"size": 45706,
"upload_time": "2019-09-16T15:37:05",
"upload_time_iso_8601": "2019-09-16T15:37:05.049612Z",
"url": "https://files.pythonhosted.org/packages/0d/26/2f68c02fae0b88d9cefdbc632edad190d61621b5660c72c920be1e52631e/pyannotate-1.2.0.tar.gz",
"yanked": false,
"yanked_reason": null
}
],
"upload_time": "2019-09-16 15:37:05",
"github": true,
"gitlab": false,
"bitbucket": false,
"github_user": "dropbox",
"github_project": "pyannotate",
"travis_ci": true,
"coveralls": false,
"github_actions": false,
"appveyor": true,
"requirements": [
{
"name": "mypy_extensions",
"specs": [
[
">=",
"0.3.0"
]
]
},
{
"name": "pytest",
"specs": [
[
">=",
"3.3.0"
]
]
},
{
"name": "setuptools",
"specs": [
[
">=",
"28.8.0"
]
]
},
{
"name": "six",
"specs": [
[
">=",
"1.11.0"
]
]
},
{
"name": "typing",
"specs": [
[
">=",
"3.6.2"
]
]
}
],
"lcname": "pyannotate"
}
JSON
