Python Docstrings: Reference & Examples
Last updated:Table of Contents
Comparison
| Pros | Cons | |
|---|---|---|
| ReStructuredText | Most common format | A bit hard to read |
| Google-Style | Better for short descriptions and documentation | Not very good for complex documentation |
| Numpy-style | Better 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.