210 lines
7.8 KiB
Plaintext
210 lines
7.8 KiB
Plaintext
|
PEP: 257
|
|||
|
|
Title: Docstring Conventions
|
|||
|
|
Version: $Revision$
|
|||
|
|
Last-Modified: $Date$
|
|||
|
|
Author: dgoodger@bigfoot.com (David Goodger)
|
|||
|
|
Discussions-To: doc-sig@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:
|