Package: wnpp Severity: wishlist Owner: Sandro Tosi <mo...@debian.org>
* Package name : pyannotate Version : 1.2.0 Upstream Author : Dropbox <gu...@dropbox.com> * URL : https://github.com/dropbox/pyannotate * License : Apache 2.0 Programming Lang: Python Description : PyAnnotate: Auto-generate PEP-484 annotations Binary package names: python3-pyannotate 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 ======== .
