PEP 257: Docstring Conventions
David Goodger
dgoodger at bigfoot.com
Wed Jun 13 00:42:24 EDT 2001
This is a PEP-ification of part of Guido van Rossum's Python Style Guide
(http://www.python.org/doc/essays/styleguide.html), with some modifications
with respect to PEPs 256 & 258.
I am posting this PEP to comp.lang.python for greatest community exposure.
Please direct replies to the Python Documentation SIG's mailing list:
mailto:doc-sig at python.org.
In addition to the master copy at http://python.sf.net/peps/pep-0257.txt
(HTML at http://python.sf.net/peps/pep-0257.html), a working copy is kept at
the project web site, http://docstring.sf.net/.
--
David Goodger dgoodger at bigfoot.com Open-source projects:
- Python Docstring Processing System: http://docstring.sf.net
- reStructuredText: http://structuredtext.sf.net
- The Go Tools Project: http://gotools.sf.net
PEP: 257
Title: Docstring Conventions
Version: $Revision: 1.1 $
Last-Modified: $Date: 1935/06/06 05:55:20 $
Author: dgoodger at bigfoot.com (David Goodger)
Discussions-To: doc-sig at python.org
Status: Draft
Type: Informational
Created: 29-May-2001
Post-History:
Abstract
This PEP documents the semantics and conventions associated with
Python docstrings.
Specification
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
docstrings.
[+] 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 screens full) 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
docstrings.
[+] 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
docstrings.
One-line Docstrings
--------------------
One-liners are for really obvious cases. They should really fit
on one line. For example:
def kos_root():
"""Return the pathname of the KOS root directory."""
global _kos_root
if _kos_root: return _kos_root
...
Notes:
- 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
----------------------
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's 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,
[-] like this:
def complex(real=0.0, imag=0.0):
"""Form a complex number.
Keyword arguments:
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 [3] recommends inserting a blank line between the
[-] last paragraph in a multi-line docstring 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 PEP 258, "DPS Generic Implementation
[+] Details" [4]
[+] Additional Docstrings: see PEP 258, "DPS Generic Implementation
[+] Details" [4]
References and Footnotes
[1] http://www.python.org/doc/essays/styleguide.html
[2] http://www.python.org/sigs/doc-sig/
[3] Guido van Rossum, Python's Benevolent Dictator For Life.
[4] http://python.sf.net/peps/pep-0258.html
Copyright
This document has been placed in the public domain.
Acknowledgements
The "Specification" text comes mostly verbatim from the Python
Style Guide by Guido van Rossum [1].
(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
[2]. Thanks to all members past and present.
Local Variables:
mode: indented-text
indent-tabs-mode: nil
End:
More information about the Python-list
mailing list