Metadata-Version: 2.1
Name: doc484
Version: 0.3.0
Summary: Generate PEP 484 type comments from docstrings
Home-page: https://github.com/chadrik/doc484
Author: Chad Dombrova
License: MIT
Description: 
        =======
        Doc 484
        =======
        
        .. image:: https://travis-ci.org/chadrik/doc484.svg?branch=master
           :target: https://travis-ci.org/chadrik/doc484
           :alt: CI Status
        
        Generate PEP 484 type annotations from docstrings
        =================================================
        
        ``doc484`` provides a script to find type declarations within your docstrings and convert them to PEP 484 type comments. It supports the three major docstring conventions `numpy <http://sphinxcontrib-napoleon.readthedocs.io/en/latest/example_numpy.html#example-numpy>`_, `google <http://sphinxcontrib-napoleon.readthedocs.io/en/latest/example_google.html>`_, and `restructuredText (sphinx) <https://thomas-cokelaer.info/tutorials/sphinx/docstring_python.html#template-py-source-file>`_
        
        Regardless of docstring convention you choose, the types declared within your docstrings should following the guidelines in `PEP 484 <https://www.python.org/dev/peps/pep-0484/>`_, especially use of the `typing <https://docs.python.org/3/library/typing.html>`_ module, where necessary.
        
        Why Use This?
        =============
        
        If you answer affirmative to at least 2 of these, this project is probably for you:
        
        - You're stuck supporting python 2.7, so you have to use type comments, instead of the type annotations supported in 3.5+
        - Your projects have existing docstrings with types that are already mostly correct
        - You find it easier to maintain and comprehend types specified alongside the description of an argument
        
        Examples
        ========
        
        Basic
        ~~~~~
        
        Before
        ------
        
        .. code:: python
        
            from typing import Optional
        
            def maxlines(input, numlines=None):
                """
                Trim a string to a maximum number of lines.
        
                Parameters
                ----------
                input : str
                numlines : Optional[int]
                    maximum number of lines
        
                Returns
                -------
                str
                """
                if numlines is None:
                    return input
                return '\n'.join(input.split('\n')[:numlines])
        
        
        After ``doc484``
        ----------------
        
        .. code:: python
        
            from typing import Optional
        
            def maxlines(input, numlines=None):
                # type: (str, Optional[int]) -> str
                """
                Trim a string to a maximum number of lines.
        
                Parameters
                ----------
                input : str
                numlines : Optional[int]
                    maximum number of lines
        
                Returns
                -------
                str
                """
                if numlines is None:
                    return input
                return '\n'.join(input.split('\n')[:numlines])
        
        
        The file is now properly inspectable by mypy or PyCharm.
        
        Advanced
        ~~~~~~~~
        
        A more complex example demonstrates some of the added readability that comes from specifying types within your docstrings.
        Below we use numpy format to document a generator of tuples:
        
        Before
        ------
        
        .. code:: python
        
            from typing import *
        
            def itercount(input, char):
                """
                Iterate over input strings and yield a tuple of the string with `char`
                removed, and the number of occurrences of `char`.
        
                Parameters
                ----------
                input : Iterable[str]
                char : str
                    character to remove and count
        
                Yields
                ------
                stripped : str
                    input string with all occurrences of `char` removed
                count : int
                    number of occurrences of `char`
                """
                for x in input:
                    yield x.strip(char), x.count(char)
        
        
        After ``doc484``
        ----------------
        
        .. code:: python
        
            from typing import *
        
            def itercount(input, char):
                # type: (Iterable[str], str) -> Iterator[Tuple[str, int]]
                """
                Iterate over input strings and yield a tuple of the string with `char`
                removed, and the number of occurrences of `char`.
        
                Parameters
                ----------
                input : Iterable[str]
                char : str
                    character to remove and count
        
                Yields
                ------
                stripped : str
                    input string with all occurrences of `char` removed
                count : int
                    number of occurrences of `char`
                """
                for x in input:
                    yield x.strip(char), x.count(char)
        
        Installing
        ==========
        
        .. code::
        
            pip install doc484
        
        
        Usage
        =====
        
        .. code::
        
            doc484 -h
        
        By default ``doc484`` will *not* modify files, instead it will print out a diff of what would be modified.  When you're ready to make changes, add the ``--write`` flag.
        
        Check the scripts directory for an example of how to automatically run ``doc484`` on modified files in your git or mercurial repository.
        
        
        Configuration
        =============
        
        You can override any of the command line options using an ini-style configuration file.
        By default, ``doc484`` looks for a setup.cfg file in the current working directory, but you can also provide a config explicitly using the ``--config`` option.
        
        For example, to override the number of processes to use when converting, and specify the docstring format for the project, add this to your setup.cfg and run ``doc484`` from the directory where this config file resides:
        
        .. code:: ini
        
           [doc484]
           processes = 12
           format = numpy
        
        TODO
        ====
        
        - automatically insert ``typing`` imports
        - add option to convert docstrings to function annotations (for python 3.5+)
        - finish support for fixing non-PEP484-compliant docstrings (e.g. ``list of str``)
        - convert ``doctypes`` utility script to python?
        
Keywords: mypy,typing,pep484,docstrings,annotations
Platform: UNKNOWN
Classifier: Development Status :: 4 - Beta
Classifier: Intended Audience :: Developers
Classifier: Topic :: Software Development :: Build Tools
Classifier: License :: OSI Approved :: MIT License
Classifier: Programming Language :: Python :: 2
Classifier: Programming Language :: Python :: 2.7
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3.6
Classifier: Programming Language :: Python :: 3.7
Provides-Extra: tests
