pymend 1.0.0

Generate, fix and convert docstrings.

Create, update or convert docstrings in existing Python files, managing several styles.

Project Status

Test Status

Supported Versions

Description

Command-line program to generate, update or transform docstrings python source code.

The app will parse the requested source files for docstrings as well as function signatures and class bodies.

This information is combined to build up complete docstrings for every function and class including place holders for types and descriptions where none could be found elsewhere.

The output format of the docstrings can be chosen between google, numpy, reST and epydoc. This means that the tool can also be used to transform docstrings in the file from one format into another.

Note however that not all section types are supported for all docstring styles.

Partially because they have not been added yet, but also because not every style officially supports the sections from all others.

To get further information please refer to the documentation.

The tool offers the choice between generating patch files or directly overwriting the python source files.

Start quickly

• install from PyPi

$ pip install pymend

• install from sources:

$ pip install git+https://github.com/JanEricNitschke/pymend.git
or
$ git clone https://github.com/JanEricNitschke/pymend.git
$ cd pymend
$ python setup.py install

• run from the command line:

$ pymend  myfile.py    # will generate a patch
$ pymend -w myfile.py  # will overwrite the file

or

$ pymend  my/folder/

• get help:

$ pymend -h

Example

TODO

Pre-commit

To use pymend in a pre-commit hook just add the following to your .pre-commit-config.yaml

repos:
-   repo: https://github.com/JanEricNitschke/pymend
    rev: "v1.0.0"
    hooks:
    -   id: pymend
        language: python
        args: ["--write", "--output=numpydoc"]

Acknowledgements

This project was inspired by and is originally based upon pyment. The intended functionality as well as the main entry point remain largerly unchanged. However additional functionality has been added in the form of ast traversal for extracting function and class information.

The docstring parsing has been replaced completely with code taken from the awesome docstring_parser project, specifically this fork.

So far only minor modifications have been made to the docstring parsing functionality. Mainly the addition of the “Methods” section for numpydoc style docstrings. Additionally the the code has been linted as well as type hinted.