iSharkFly-Open
/
python-peps
mirror of https://github.com/python/peps.git
1
0
Fork 0
Code Issues Packages Projects Releases Wiki Activity

New version from David Goodger, where he makes me co-author (since 

it's mostly lifted from my style guide).  I don't plan to actively
contribute much -- David is the primary author.

There are many miscellaneous updates here.
This commit is contained in:
Guido van Rossum 2001-06-18 19:18:58 +00:00
parent 9bab4aa88d
commit d96e4fbc05
1 changed files with 88 additions and 66 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

148
pep-0257.txt
View File

@ -2,12 +2,13 @@ PEP: 257
Title: Docstring Conventions Title: Docstring Conventions
Version: $Revision$ Version: $Revision$
Last-Modified: $Date$ Last-Modified: $Date$
Author: dgoodger@bigfoot.com (David Goodger) Author: dgoodger@bigfoot.com (David Goodger),
guido@digicool.com (Guido van Rossum)
Discussions-To: doc-sig@python.org Discussions-To: doc-sig@python.org
Status: Draft Status: Draft
Type: Informational Type: Informational
Created: 29-May-2001 Created: 29-May-2001
Post-History: Post-History: 13-Jun-2001
Abstract Abstract
@ -16,31 +17,60 @@ Abstract
Python docstrings. 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 the conventions, the worst you'll get is some dirty
looks. But some software (such as the Docstring Processing System
[1]) will be aware of the conventions, so following them will get
you the best results.
Specification 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 All modules should normally have docstrings, and all functions and
classes exported by a module should also have docstrings. Public classes exported by a module should also have docstrings. Public
methods (including the __init__ constructor) should also have methods (including the __init__ constructor) should also have
docstrings. docstrings. A package may be documented in the module docstring
of the __init__.py file in the package directory.
[+] A package may be documented in the module docstring of the String literals occuring elsewhere in Python code may also act as
[+] __init__.py file in the package directory. 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
are recognized by software tools:
The docstring of a script (a stand-alone program) should be usable 1. String literals occuring immediately after a simple assignment
as its "usage" message, printed when the script is invoked with at the top level of a module, class, or __init__ method
incorrect or missing arguments (or perhaps with a "-h" option, for are called "attribute docstrings".
"help"). Such a docstring should document the script's function
and command line syntax, environment variables, and files. Usage 2. String literals occuring immediately after another docstring
messages can be fairly elaborate (several screens full) and should are called "additional docstrings".
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 Please see PEP 258 "DPS Generic Implementation Details" [2] for a
sophisticated user. detailed description of attribute and additional docstrings.
For consistency, always use """triple double quotes""" around For consistency, always use """triple double quotes""" around
docstrings. docstrings. Use r"""raw triple double quotes""" if you use any
backslashes in your 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 There are two forms of docstrings: one-liners and multi-line
docstrings. docstrings.
@ -49,7 +79,7 @@ Specification
-------------------- --------------------
One-liners are for really obvious cases. They should really fit One-liners are for really obvious cases. They should really fit
on one line. For example: on one line. For example::
def kos_root(): def kos_root():
"""Return the pathname of the KOS root directory.""" """Return the pathname of the KOS root directory."""
@ -71,15 +101,15 @@ Specification
function's effect as a command ("Do this", "Return that"), not function's effect as a command ("Do this", "Return that"), not
as a description: e.g. don't write "Returns the pathname ..." as a description: e.g. don't write "Returns the pathname ..."
[+] - The one-line docstring should NOT be a "signature" reiterating - The one-line docstring should NOT be a "signature" reiterating
[+] the function parameters (which can be obtained by introspection). the function parameters (which can be obtained by
[+] Don't do: introspection). Don't do::
[+] def function(a, b): def function(a, b):
[+] """function(a, b) -> list""" """function(a, b) -> list"""
[+] This type of docstring is only appropriate for C functions (such This type of docstring is only appropriate for C functions (such
[+] as built-ins), where introspection is not possible. as built-ins), where introspection is not possible.
Multi-line Docstrings Multi-line Docstrings
---------------------- ----------------------
@ -108,11 +138,23 @@ Specification
case, treat the docstring as another section, and precede it with case, treat the docstring as another section, and precede it with
a blank line. 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, The docstring for a module should generally list the classes,
exceptions and functions (and any other objects) that are exported exceptions and functions (and any other objects) that are exported
by the module, with a one-line summary of each. (These summaries by the module, with a one-line summary of each. (These summaries
generally give less detail than the summary line in the object's generally give less detail than the summary line in the object's
docstring.) 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 The docstring for a function or method should summarize its
behavior and document its arguments, return value(s), side behavior and document its arguments, return value(s), side
@ -141,10 +183,8 @@ Specification
functions or methods in upper case in running text. Python is functions or methods in upper case in running text. Python is
case sensitive and the argument names can be used for keyword case sensitive and the argument names can be used for keyword
arguments, so the docstring should document the correct argument arguments, so the docstring should document the correct argument
names. It is best to list each argument on a separate line, names. It is best to list each argument on a separate line. For
example::
[-] with two dashes separating the name from the description,
[-] like this:
def complex(real=0.0, imag=0.0): def complex(real=0.0, imag=0.0):
"""Form a complex number. """Form a complex number.
@ -157,27 +197,24 @@ Specification
if imag == 0.0 and real == 0.0: return complex_zero if imag == 0.0 and real == 0.0: return complex_zero
... ...
[-] The BDFL [3] recommends inserting a blank line between the The BDFL [3] recommends inserting a blank line between the last
[-] last paragraph in a multi-line docstring and its closing quotes, paragraph in a multi-line docstring and its closing quotes,
[-] placing the closing quotes on a line by themselves. This way, placing the closing quotes on a line by themselves. This way,
[-] Emacs' fill-paragraph command can be used on it. 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 References and Footnotes
[1] http://www.python.org/doc/essays/styleguide.html [1] http://python.sf.net/peps/pep-0256.html
[2] http://www.python.org/sigs/doc-sig/ [2] http://python.sf.net/peps/pep-0258.html
[3] Guido van Rossum, Python's Benevolent Dictator For Life. [3] Guido van Rossum, Python's creator and Benevolent Dictator For
Life.
[4] http://python.sf.net/peps/pep-0258.html [4] http://www.python.org/doc/essays/styleguide.html
[5] http://www.python.org/sigs/doc-sig/
Copyright Copyright
@ -188,22 +225,7 @@ Copyright
Acknowledgements Acknowledgements
The "Specification" text comes mostly verbatim from the Python The "Specification" text comes mostly verbatim from the Python
Style Guide by Guido van Rossum [1]. Style Guide by Guido van Rossum [4].
(If it's OK with him, I will add GvR as an author of this PEP. I This document borrows ideas from the archives of the Python
am quite confident that the BDFL doesn't want to own this PEP :-). Doc-SIG [5]. Thanks to all members past and present.
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: