Metadata-Version: 2.1
Name: pyannotate
Version: 1.2.0
Summary: PyAnnotate: Auto-generate PEP-484 annotations
Home-page: https://github.com/dropbox/pyannotate
Author: Dropbox
Author-email: guido@dropbox.com
License: Apache 2.0
Description: 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/
        
Platform: POSIX
Classifier: Development Status :: 3 - Alpha
Classifier: Environment :: Console
Classifier: Intended Audience :: Developers
Classifier: License :: OSI Approved :: Apache Software License
Classifier: Operating System :: POSIX
Classifier: Programming Language :: Python :: 2
Classifier: Programming Language :: Python :: 2.7
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3.4
Classifier: Programming Language :: Python :: 3.5
Classifier: Programming Language :: Python :: 3.6
Classifier: Programming Language :: Python :: 3.7
Classifier: Topic :: Software Development
Description-Content-Type: text/markdown
