peps/pep-0257.txt at main · python/peps

Cannot retrieve contributors at this time

307 lines (234 sloc) 10.6 KB

	PEP: 257
	Title: Docstring Conventions
	Version: $Revision$
	Last-Modified: $Date$
	Author: David Goodger <goodger@python.org>,
	Guido van Rossum <guido@python.org>
	Discussions-To: doc-sig@python.org
	Status: Active
	Type: Informational
	Content-Type: text/x-rst
	Created: 29-May-2001
	Post-History: 13-Jun-2001


	Abstract
	========

	This PEP documents the semantics and conventions associated with
	Python docstrings.


	Rationale
	=========

	The aim of this PEP is to standardize the high-level structure of
	docstrings: what they should contain, and how to say it (without
	touching on any markup syntax within docstrings). The PEP contains
	conventions, not laws or syntax.

	"A universal convention supplies all of maintainability, clarity,
	consistency, and a foundation for good programming habits too.
	What it doesn't do is insist that you follow it against your will.
	That's Python!"

	-- Tim Peters on comp.lang.python, 2001-06-16

	If you violate these conventions, the worst you'll get is some dirty
	looks. But some software (such as the Docutils_ docstring processing
	system :pep:`256`, :pep:`258`) will be aware of the conventions, so following them
	will get you the best results.


	Specification
	=============

	What is a Docstring?
	--------------------

	A docstring is a string literal that occurs as the first statement in
	a module, function, class, or method definition. Such a docstring
	becomes the ``__doc__`` special attribute of that object.

	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.

	String literals occurring elsewhere in Python code may also act as
	documentation. They are not recognized by the Python bytecode
	compiler and are not accessible as runtime object attributes (i.e. not
	assigned to ``__doc__``), but two types of extra docstrings may be
	extracted by software tools:

	1. String literals occurring immediately after a simple assignment at
	the top level of a module, class, or ``__init__`` method are called
	"attribute docstrings".

	2. String literals occurring immediately after another docstring are
	called "additional docstrings".

	Please see :pep:`258`, "Docutils Design Specification", for a
	detailed description of attribute and additional docstrings.

	For consistency, always use ``"""triple double quotes"""`` around
	docstrings. Use ``r"""raw triple double quotes"""`` if you use any
	backslashes in your docstrings. For Unicode docstrings, use
	``u"""Unicode triple-quoted strings"""``.

	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 or method'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/method 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. However, the
	nature of the return value cannot be determined by introspection,
	so it should be mentioned. The preferred form for such a docstring
	would be something like::

	def function(a, b):
	"""Do X and return a list."""

	(Of course "Do X" should be replaced by a useful description!)


	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 summary line may be on
	the same line as the opening quotes or on the next line. The entire
	docstring is indented the same as the quotes at its first line (see
	example below).

	Insert a blank line 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.

	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.

	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 package (i.e., the docstring of the
	package's ``__init__.py`` module) should also list the modules and
	subpackages exported by the package.

	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. For example::

	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
	...

	Unless the entire docstring fits on a line, place the closing quotes
	on a line by themselves. This way, Emacs' ``fill-paragraph`` command
	can be used on it.


	Handling Docstring Indentation
	------------------------------

	Docstring processing tools will strip a uniform amount of indentation
	from the second and further lines of the docstring, equal to the
	minimum indentation of all non-blank lines after the first line. Any
	indentation in the first line of the docstring (i.e., up to the first
	newline) is insignificant and removed. Relative indentation of later
	lines in the docstring is retained. Blank lines should be removed
	from the beginning and end of the docstring.

	Since code is much more precise than words, here is an implementation
	of the algorithm::

	def trim(docstring):
	if not docstring:
	return ''
	# Convert tabs to spaces (following the normal Python rules)
	# and split into a list of lines:
	lines = docstring.expandtabs().splitlines()
	# Determine minimum indentation (first line doesn't count):
	indent = sys.maxsize
	for line in lines[1:]:
	stripped = line.lstrip()
	if stripped:
	indent = min(indent, len(line) - len(stripped))
	# Remove indentation (first line is special):
	trimmed = [lines[0].strip()]
	if indent < sys.maxsize:
	for line in lines[1:]:
	trimmed.append(line[indent:].rstrip())
	# Strip off trailing and leading blank lines:
	while trimmed and not trimmed[-1]:
	trimmed.pop()
	while trimmed and not trimmed[0]:
	trimmed.pop(0)
	# Return a single string:
	return '\n'.join(trimmed)

	The docstring in this example contains two newline characters and is
	therefore 3 lines long. The first and last lines are blank::

	def foo():
	"""
	This is the second line of the docstring.
	"""

	To illustrate::

	>>> print repr(foo.__doc__)
	'\n This is the second line of the docstring.\n '
	>>> foo.__doc__.splitlines()
	['', ' This is the second line of the docstring.', ' ']
	>>> trim(foo.__doc__)
	'This is the second line of the docstring.'

	Once trimmed, these docstrings are equivalent::

	def foo():
	"""A multi-line
	docstring.
	"""

	def bar():
	"""
	A multi-line
	docstring.
	"""


	References and Footnotes
	========================

	.. _Docutils: http://docutils.sourceforge.net/

	.. _Doc-SIG: http://www.python.org/sigs/doc-sig/


	Copyright
	=========

	This document has been placed in the public domain.


	Acknowledgements
	================

	The "Specification" text comes mostly verbatim from :pep:`8`
	by Guido van Rossum.

	This document borrows ideas from the archives of the Python Doc-SIG_.
	Thanks to all members past and present.



	..
	Local Variables:
	mode: indented-text
	indent-tabs-mode: nil
	fill-column: 70
	sentence-end-double-space: t
	End: