Python Docstrings: Reference & Examples

Python Docstrings: Reference & Examples

Last updated:
Table of Contents

Comparison

Pros Cons
ReStructuredTextMost common formatA bit hard to read
Google-StyleBetter for short descriptions
and documentation
Not very good for
complex documentation
Numpy-styleBetter for complex descriptions
and documentation
Uses more vertical space

ReStructuredText (reST)

ReStructuredText is a markup language, much like Markdown, that's been used to document code (among other uses).

See full directives here

  • The most common format

  • Arguably a bit hard to read

def func(arg1, arg2):
    """Summary line.

    Extended description of function.

    :param int arg1: Description of arg1.
    :param str arg2: Description of arg2.
    :raise: ValueError if arg1 is equal to arg2
    :return: Description of return value
    :rtype: bool

    :example:

    >>> a=1
    >>> b=2
    >>> func(a,b)
    True
    """

    if arg1 == arg2:
        raise ValueError('arg1 must not be equal to arg2')

    return True

Google-style

  • Uses more horizontal space (compared with numpy-style)

  • Better for short and simple docstrings.

def func(arg1, arg2):
    """Summary line.

    Extended description of function.

    Args:
        arg1 (int): Description of arg1
        arg2 (str): Description of arg2

    Returns:
        bool: Description of return value

    Raises:
        AttributeError: The ``Raises`` section is a list of all exceptions
            that are relevant to the interface.
        ValueError: If `arg2` is equal to `arg1`.

    Examples:
        Examples should be written in doctest format, and should illustrate how
        to use the function.

        >>> a=1
        >>> b=2
        >>> func(a,b)
        True

    """
    if arg1 == arg2:
        raise ValueError('arg1 must not be equal to arg2')

    return True

Numpy-style

  • Uses more vertical space (compared to google-style)

  • Better for long and in-depth docstrings

def func(arg1, arg2):
    """Summary line.

    Extended description of function.

    Parameters
    ----------
    arg1 : int
        Description of arg1
    arg2 : str
        Description of arg2

    Returns
    -------
    bool
        Description of return value

    Raises
    ------
    AttributeError
        The ``Raises`` section is a list of all exceptions
        that are relevant to the interface.
    ValueError
        If `arg2` is equal to `arg1`.

    See Also
    --------
    otherfunc: some other related function

    Examples
    --------
    These are written in doctest format, and should illustrate how to
    use the function.

    >>> a=1
    >>> b=2
    >>> func(a,b)
    True
    """
    if arg1 == arg2:
        raise ValueError('arg1 must not be equal to arg2')

    return True

Doctest

Doctests are a special form of docstring, used to inform users how to use a method but also to actually run tests.

Any documentation style can be used with doctests, provided you add a small call at the end of the file, the following example (let's call it doctest-example.py)

def func(arg1, arg2):
    """Summary line.

    Extended description of function.

    >>> func(1,2)
    True
    >>> func(1,1)
    Traceback (most recent call last):
    ...
    ValueError: arg1 may not be equal to arg2
    """

    if arg1 == arg2:
        raise ValueError('arg1 must not be equal to arg2')

    return True

if __name__ == "__main__":
    import doctest
    doctest.testmod()

If you run this example with the verbose flag (python doctest-example.py -v), you see the test output:

$ python doctest-example.py -v
Trying:
    func(1,2)
Expecting:
    True
ok
Trying:
    func(1,1)
Expecting:
    Traceback (most recent call last):
    ...
    ValueError: arg1 must not be equal to arg2
ok
1 items had no tests:
    __main__
1 items passed all tests:
   2 tests in __main__.func
2 tests in 2 items.
2 passed and 0 failed.
Test passed.

References