Skip to content

PyPI version

Python Docstring Formatting

Docstring Flavors

Python uses docstrings to document code. A docstring is a string that is the first statement in a package, module, class or function. Python docstrings are written in the reStructuredText syntax (abbreviated as RST or reST).

There are at least 4 flavors of docstrings, each following the PEP 257 conventions. The following examples show how to document a function parameter:


@type param1: int
@param param1: The first parameter


:param param1: The first parameter
:type: int


    param1 (int): The first parameter


param1 : int
    The first parameter

DSP-TOOLS uses the Google style without typing, as defined here.

Existing Formatters


Static analysis tool for checking compliance with Python docstring conventions. Pydocstyle supports most PEP 257 conventions out of the box, but it should not be considered a reference implementation. Pydocstyle seems to be the most popular docstring checker. It supports the styles "pep257", "numpy", and "google".


A docstring formatter that follows PEP 8 and PEP 257 but makes some of the more controversial elements of those PEPs optional. Can be configured for other styles as well. This project is heavily inspired by docformatter. Supported styles: "pep257", "numpy".


Automatically formats docstrings to follow a subset of the PEP 257 conventions. Currently, only the style "sphinx" and "epytext" are recognized, but "numpy" and "google" are future styles.


Docstring linter which checks whether a docstring's description matches the actual function/method implementation. Supports the styles "sphinx", "google", and "numpy".

Last update: September 12, 2023