Doc 484
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)
| 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)
| File | Interpreter | ABI | Platform | Actions Reset |
|---|---|---|---|---|
| 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.