Skip to main content

Doc 484

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, google, and restructuredText (sphinx)

Regardless of docstring convention you choose, the types declared within your docstrings should following the guidelines in PEP 484, especially use of the typing 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

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

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

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

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

pip install doc484

Usage

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:

[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?

Metadata

Release files for doc484 0.3.5

For a detailed explanation of source distributions (sdists) and built distributions (wheels), please see the package formats documentation.

Source distribution (sdist)

Source distribution for doc484 0.3.5
File Size Uploaded Provenance Actions
doc484-0.3.5.tar.gz 19.8 kB Without provenance Details for doc484-0.3.5.tar.gz

Built distribution (wheel)

Table of built distributions (wheels) for doc484 0.3.5
File Interpreter ABI Platform Actions
doc484-0.3.5-py2.py3-none-any.whl Python 3, Python 2 none any Details for doc484-0.3.5-py2.py3-none-any.whl

Total release size: 41.1 kB

Release files / doc484-0.3.5.tar.gz

Download URL doc484-0.3.5.tar.gz
Size 19.8 kB
Tags Source
SHA-256 checksum
How to use checksums
4146c512215846c956c3214a45a79d6e51e6ad4e5ac05857f0f32af51b86cba9
BLAKE2b-256 checksum
How to use checksums
9260b6028b34b9f2911ef81580ed87c8c5f74e2beb20ea2245ff991bf7c20fde
Upload date
Uploaded using Trusted Publishing?
What is trusted publishing?
No
Uploaded via twine/1.11.0 pkginfo/1.4.2 requests/2.19.1 setuptools/40.8.0 requests-toolbelt/0.8.0 tqdm/4.24.0 CPython/3.7.2

Release files / doc484-0.3.5-py2.py3-none-any.whl

Download URL doc484-0.3.5-py2.py3-none-any.whl
Size 21.3 kB
Tags Python 2 Python 3
SHA-256 checksum
How to use checksums
e3c8fe4cfbe2dc5c643525268593536187d22308f95cc70cc7786c7a4fa7361a
BLAKE2b-256 checksum
How to use checksums
55568cd949918eeeff2b839a07a5eb92c5769195b44b128d8da4622bb4a590c0
Upload date
Uploaded using Trusted Publishing?
What is trusted publishing?
No
Uploaded via twine/1.11.0 pkginfo/1.4.2 requests/2.19.1 setuptools/40.8.0 requests-toolbelt/0.8.0 tqdm/4.24.0 CPython/3.7.2

Security for doc484 0.3.5

Provenance

Provenance describes where a file came from. On PyPI, provenance is shared via attestations, which provide a verifiable record of the build or publishing details. View details, limitations and caveats.

No provenance found

None of the files in this release were uploaded with provenance metadata.

A note on package security

PyPI is a repository for distributing packages, not a service for auditing them. While third-party security researchers and our staff do their best to detect and remove malicious packages, PyPI cannot guarantee the quality, security or suitability of any given package.

To learn more about protecting yourself from malicious actors, visit our package security documentation.

Anthropic, PBC Visionary sponsor Bloomberg Visionary sponsor Hudson River Trading Visionary sponsor Meta Visionary sponsor NVIDIA Visionary sponsor Microsoft Sustainability sponsor Depot Continuous Integration AWS Cloud computing and Security Sponsor Datadog Monitoring Fastly CDN Google Download Analytics Sentry Error logging StatusPage Status page