[Doc-SIG] PEP: Docstring Conventions
Sun, 03 Jun 2001 10:32:49 -0400
Title: Docstring Conventions
Author: email@example.com (David Goodger)
This PEP documents the semantics and conventions associated with Python
This document has been placed in the public domain.
The "Specificaton" text comes mostly verbatim from the Python Style
Guilde by Guido van Rossum .
(If it's OK with him, I will add GvR as an author of this PEP. I am
quite confident that the BDFL doesn't want to own this PEP :-). Apart
from minor editing, proposed additions to the Style Guide text are
marked with '[+]' to the left of each line, and proposed omissions are
marked with '[-]'. If it is deemed that this PEP is unnecessary, then
it can be taken as suggestions for Style Guide modification.)
This document borrows ideas from the archives of the Python Doc-SIG
. Thanks to all members past & present.
All modules should normally have docstrings, and all functions and
classes exported by a module should also have docstrings. Public
methods (including the __init__ constructor) should also have doc
[+] A package may be documented in the module docstring of the
[+] __init__.py file in the package directory.
The docstring of a script (a stand-alone program) should be usable as
its "usage" message, printed when the script is invoked with incorrect
or missing arguments (or perhaps with a "-h" option, for "help"). Such
a docstring should document the script's function and command line
syntax, environment variables, and files. Usage messages can be fairly
elaborate (several screenfuls) and should be sufficient for a new user
to use the command properly, as well as a complete quick reference to
all options and arguments for the sophisticated user.
For consistency, always use """triple double quotes""" around doc
[+] Use r"""raw triple double quotes""" if you use any
[+] backslashes in your docstrings.
There are two forms of docstrings: one-liners and multi-line
One-liners are for really obvious cases. They should really fit on one
line. For example:
"""Return the pathname of the KOS root directory."""
if _kos_root: return _kos_root
- Triple quotes are used even though the string fits on one line. This
makes it easy to later expand it.
- The closing quotes are on the same line as the opening quotes. This
looks better for one-liners.
- There's no blank line either before or after the docstring.
- The docstring is a phrase ending in a period. It prescribes the
function's effect as a command ("Do this", "Return that"), not as a
description: e.g. don't write "Returns the pathname ..."
[+] - The one-line docstring should NOT be a "signature" reiterating
[+] the function parameters (which can be obtained by introspection).
[+] Don't do:
[+] def function(a, b):
[+] """function(a, b) -> list"""
[+] This type of docstring is only appropriate for C functions (such
[+] as built-ins), where introspection is not possible.
Multi-line docstrings consist of a summary line just like a one-line
docstring, followed by a blank line, followed by a more elaborate
description. The summary line may be used by automatic indexing tools;
it is important that it fits on one line and is separated from the rest
of the docstring by a blank line.
The entire docstring is indented the same as the quotes at its first
line (see example below). Docstring processing tools will strip an
amount of indentation from the second and further lines of the
docstring equal to the indentation of the first non-blank line after
the first line of the docstring. Relative indentation of later lines in
the docstring is retained.
Insert a blank line before and after all docstrings (one-line or
multi-line) that document a class -- generally speaking, the class'
methods are separated from each other by a single blank line, and the
docstring needs to be offset from the first method by a blank line; for
symmetry, put a blank line between the class header and the docstring.
Docstrings documenting functions generally don't have this requirement,
unless the function's body is written as a number of blank-line
separated sections -- in this case, treat the docstring as another
section, and precede it with a blank line.
The docstring for a module should generally list the classes,
exceptions and functions (and any other objects) that are exported by
the module, with a one-line summary of each. (These summaries generally
give less detail than the summary line in the object's docstring.)
The docstring for a function or method should summarize its behavior
and document its arguments, return value(s), side effects, exceptions
raised, and restrictions on when it can be called (all if applicable).
Optional arguments should be indicated. It should be documented whether
keyword arguments are part of the interface.
The docstring for a class should summarize its behavior and list the
public methods and instance variables. If the class is intended to be
subclassed, and has an additional interface for subclasses, this
interface should be listed separately (in the docstring). The class
constructor should be documented in the docstring for its __init__
method. Individual methods should be documented by their own docstring.
If a class subclasses another class and its behavior is mostly
inherited from that class, its docstring should mention this and
summarize the differences. Use the verb "override" to indicate that a
subclass method replaces a superclass method and does not call the
superclass method; use the verb "extend" to indicate that a subclass
method calls the superclass method (in addition to its own behavior).
*Do not* use the Emacs convention of mentioning the arguments of
functions or methods in upper case in running text. Python is case
sensitive and the argument names can be used for keyword arguments, so
the docstring should document the correct argument names. It is best to
list each argument on a separate line,
[-] with two dashes separating the name from the description,
def complex(real=0.0, imag=0.0):
"""Form a complex number.
real -- the real part (default 0.0)
imag -- the imaginary part (default 0.0)
if imag == 0.0 and real == 0.0: return complex_zero
[-] The BDFL  recommends inserting a blank line between the
[-] last paragraph in a multi-line doc string and its closing quotes,
[-] placing the closing quotes on a line by themselves. This way,
[-] Emacs' fill-paragraph command can be used on it.
[+] Attribute Docstrings: see DPS Generic Implementation Details PEP
[+] Additional Docstrings: see DPS Generic Implementation Details PEP
References and Footnotes
 Guido van Rossum, Python's Benevolent Dictator For Life.