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.