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

Converted to reStructuredText & updated.

This commit is contained in:
David Goodger 2002-08-30 03:10:51 +00:00
parent 2bba139678
commit dde379d684
4 changed files with 1638 additions and 1616 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

372
pep-0256.txt
View File

@ -2,290 +2,298 @@ PEP: 256
Title: Docstring Processing System Framework
Version: $Revision$
Last-Modified: $Date$
Author: goodger@users.sourceforge.net (David Goodger)
Discussions-To: doc-sig@python.org
Author: David Goodger <goodger@users.sourceforge.net>
Discussions-To: <doc-sig@python.org>
Status: Draft
Type: Standards Track
Content-Type: text/x-rst
Created: 01-Jun-2001
Post-History: 13-Jun-2001
Abstract
========
Python lends itself to inline documentation. With its built-in
docstring syntax, a limited form of Literate Programming [1]_ is
easy to do in Python. However, there are no satisfactory standard
tools for extracting and processing Python docstrings. The lack
of a standard toolset is a significant gap in Python's
infrastructure; this PEP aims to fill the gap.
Python lends itself to inline documentation. With its built-in
docstring syntax, a limited form of `Literate Programming`_ is easy to
do in Python. However, there are no satisfactory standard tools for
extracting and processing Python docstrings. The lack of a standard
toolset is a significant gap in Python's infrastructure; this PEP aims
to fill the gap.
The issues surrounding docstring processing have been contentious
and difficult to resolve. This PEP proposes a generic Docstring
Processing System (DPS) framework, which separates out the
components (program and conceptual), enabling the resolution of
individual issues either through consensus (one solution) or
through divergence (many). It promotes standard interfaces which
will allow a variety of plug-in components (input context readers,
markup parsers, and output format writers) to be used.
The issues surrounding docstring processing have been contentious and
difficult to resolve. This PEP proposes a generic Docstring
Processing System (DPS) framework, which separates out the components
(program and conceptual), enabling the resolution of individual issues
either through consensus (one solution) or through divergence (many).
It promotes standard interfaces which will allow a variety of plug-in
components (input context readers, markup parsers, and output format
writers) to be used.
The concepts of a DPS framework are presented independently of
implementation details.
The concepts of a DPS framework are presented independently of
implementation details.
Roadmap to the Doctring PEPs
============================
There are many aspects to docstring processing. The "Docstring
PEPs" have broken up the issues in order to deal with each of them
in isolation, or as close as possible. The individual aspects and
associated PEPs are as follows:
There are many aspects to docstring processing. The "Docstring PEPs"
have broken up the issues in order to deal with each of them in
isolation, or as close as possible. The individual aspects and
associated PEPs are as follows:
* Docstring syntax. PEP 287, reStructuredText Docstring Format,
proposes a syntax for Python docstrings, PEPs, and other uses.
* Docstring syntax. PEP 287, "reStructuredText Docstring Format"
[#PEP-287]_, proposes a syntax for Python docstrings, PEPs, and
other uses.
* Docstring semantics consist of at least two aspects:
* Docstring semantics consist of at least two aspects:
- Conventions: the high-level structure of docstrings. Dealt
with in PEP 257, Docstring Conventions.
- Conventions: the high-level structure of docstrings. Dealt with
in PEP 257, "Docstring Conventions" [#PEP-257]_.
- Methodology: rules for the informational content of
docstrings. Not addressed.
- Methodology: rules for the informational content of docstrings.
Not addressed.
* Processing mechanisms. This PEP outlines the high-level issues
and specification of an abstract docstring processing system
(DPS). PEP 258, Docutils Design Specification, is an overview
of the design and implementation of one DPS under development.
* Processing mechanisms. This PEP (PEP 256) outlines the high-level
issues and specification of an abstract docstring processing system
(DPS). PEP 258, "Docutils Design Specification" [#PEP-258]_, is an
overview of the design and implementation of one DPS under
development.
* Output styles: developers want the documentation generated from
their source code to look good, and there are many different
ideas about what that means. PEP 258 touches on "Stylist
Transforms". This aspect of docstring processing has yet to be
fully explored.
* Output styles: developers want the documentation generated from
their source code to look good, and there are many different ideas
about what that means. PEP 258 touches on "Stylist Transforms".
This aspect of docstring processing has yet to be fully explored.
By separating out the issues, we can form consensus more easily
(smaller fights ;-), and accept divergence more readily.
By separating out the issues, we can form consensus more easily
(smaller fights ;-), and accept divergence more readily.
Rationale
=========
There are standard inline documentation systems for some other
languages. For example, Perl has POD [2]_ and Java has Javadoc
[3]_, but neither of these mesh with the Pythonic way. POD syntax
is very explicit, but takes after Perl in terms of readability.
Javadoc is HTML-centric; except for '@field' tags, raw HTML is
used for markup. There are also general tools such as Autoduck
[4]_ and Web (Tangle & Weave) [5]_, useful for multiple languages.
There are standard inline documentation systems for some other
languages. For example, Perl has POD_ ("Plain Old Documentation") and
Java has Javadoc_, but neither of these mesh with the Pythonic way.
POD syntax is very explicit, but takes after Perl in terms of
readability. Javadoc is HTML-centric; except for "``@field``" tags,
raw HTML is used for markup. There are also general tools such as
Autoduck_ and Web_ (Tangle & Weave), useful for multiple languages.
There have been many attempts to write auto-documentation systems
for Python (not an exhaustive list):
There have been many attempts to write auto-documentation systems
for Python (not an exhaustive list):
- Marc-Andre Lemburg's doc.py [6]_
- Marc-Andre Lemburg's doc.py_
- Daniel Larsson's pythondoc & gendoc [7]_
- Daniel Larsson's pythondoc_ & gendoc_
- Doug Hellmann's HappyDoc [8]_
- Doug Hellmann's HappyDoc_
- Laurence Tratt's Crystal [9]_
- Laurence Tratt's Crystal_
- Ka-Ping Yee's htmldoc & pydoc [10]_ (pydoc.py is now part of the
Python standard library; see below)
- Ka-Ping Yee's pydoc_ (pydoc.py is now part of the Python standard
library; see below)
- Tony Ibbs' docutils [11]_
- Tony Ibbs' docutils_ (Tony has donated this name to the `Docutils
project`_)
- Edward Loper's STminus formalization and related efforts [12]_
- Edward Loper's STminus_ formalization and related efforts
These systems, each with different goals, have had varying degrees
of success. A problem with many of the above systems was
over-ambition combined with inflexibility. They provided a
self-contained set of components: a docstring extraction system, a
markup parser, an internal processing system and one or more
output format writers with a fixed style. Inevitably, one or more
aspects of each system had serious shortcomings, and they were not
easily extended or modified, preventing them from being adopted as
standard tools.
These systems, each with different goals, have had varying degrees of
success. A problem with many of the above systems was over-ambition
combined with inflexibility. They provided a self-contained set of
components: a docstring extraction system, a markup parser, an
internal processing system and one or more output format writers with
a fixed style. Inevitably, one or more aspects of each system had
serious shortcomings, and they were not easily extended or modified,
preventing them from being adopted as standard tools.
It has become clear (to this author, at least) that the "all or
nothing" approach cannot succeed, since no monolithic
self-contained system could possibly be agreed upon by all
interested parties. A modular component approach designed for
extension, where components may be multiply implemented, may be
the only chance for success. Standard inter-component APIs will
make the DPS components comprehensible without requiring detailed
knowledge of the whole, lowering the barrier for contributions,
and ultimately resulting in a rich and varied system.
It has become clear (to this author, at least) that the "all or
nothing" approach cannot succeed, since no monolithic self-contained
system could possibly be agreed upon by all interested parties. A
modular component approach designed for extension, where components
may be multiply implemented, may be the only chance for success.
Standard inter-component APIs will make the DPS components
comprehensible without requiring detailed knowledge of the whole,
lowering the barrier for contributions, and ultimately resulting in a
rich and varied system.
Each of the components of a docstring processing system should be
developed independently. A 'best of breed' system should be
chosen, either merged from existing systems, and/or developed
anew. This system should be included in Python's standard
library.
Each of the components of a docstring processing system should be
developed independently. A "best of breed" system should be chosen,
either merged from existing systems, and/or developed anew. This
system should be included in Python's standard library.
PyDoc & Other Existing Systems
------------------------------
PyDoc became part of the Python standard library as of release
2.1. It extracts and displays docstrings from within the Python
interactive interpreter, from the shell command line, and from a
GUI window into a web browser (HTML). Although a very useful
tool, PyDoc has several deficiencies, including:
PyDoc became part of the Python standard library as of release 2.1.
It extracts and displays docstrings from within the Python interactive
interpreter, from the shell command line, and from a GUI window into a
web browser (HTML). Although a very useful tool, PyDoc has several
deficiencies, including:
- In the case of the GUI/HTML, except for some heuristic
hyperlinking of identifier names, no formatting of the
docstrings is done. They are presented within <p><small><tt>
tags to avoid unwanted line wrapping. Unfortunately, the result
is not attractive.
- In the case of the GUI/HTML, except for some heuristic hyperlinking
of identifier names, no formatting of the docstrings is done. They
are presented within ``<p><small><tt>`` tags to avoid unwanted line
wrapping. Unfortunately, the result is not attractive.
- PyDoc extracts docstrings and structural information (class
identifiers, method signatures, etc.) from imported module
objects. There are security issues involved with importing
untrusted code. Also, information from the source is lost when
importing, such as comments, "additional docstrings" (string
literals in non-docstring contexts; see PEP 258 [13]_), and the
order of definitions.
- PyDoc extracts docstrings and structural information (class
identifiers, method signatures, etc.) from imported module objects.
There are security issues involved with importing untrusted code.
Also, information from the source is lost when importing, such as
comments, "additional docstrings" (string literals in non-docstring
contexts; see PEP 258 [#PEP-258]_), and the order of definitions.
The functionality proposed in this PEP could be added to or used
by PyDoc when serving HTML pages. The proposed docstring
processing system's functionality is much more than PyDoc needs in
its current form. Either an independent tool will be developed
(which PyDoc may or may not use), or PyDoc could be expanded to
encompass this functionality and *become* the docstring processing
system (or one such system). That decision is beyond the scope of
this PEP.
The functionality proposed in this PEP could be added to or used by
PyDoc when serving HTML pages. The proposed docstring processing
system's functionality is much more than PyDoc needs in its current
form. Either an independent tool will be developed (which PyDoc may
or may not use), or PyDoc could be expanded to encompass this
functionality and *become* the docstring processing system (or one
such system). That decision is beyond the scope of this PEP.
Similarly for other existing docstring processing systems, their
authors may or may not choose compatibility with this framework.
However, if this framework is accepted and adopted as the Python
standard, compatibility will become an important consideration in
these systems' future.
Similarly for other existing docstring processing systems, their
authors may or may not choose compatibility with this framework.
However, if this framework is accepted and adopted as the Python
standard, compatibility will become an important consideration in
these systems' future.
Specification
=============
The docstring processing system framework consists of components,
as follows::
The docstring processing system framework is broken up as follows:
1. Docstring conventions. Documents issues such as:
1. Docstring conventions. Documents issues such as:
- What should be documented where.
- What should be documented where.
- First line is a one-line synopsis.
- First line is a one-line synopsis.
PEP 257, Docstring Conventions [14]_, documents some of these
issues.
PEP 257 [#PEP-257]_ documents some of these issues.
2. Docstring processing system design specification. Documents
issues such as:
2. Docstring processing system design specification. Documents
issues such as:
- High-level spec: what a DPS does.
- High-level spec: what a DPS does.
- Command-line interface for executable script.
- Command-line interface for executable script.
- System Python API.
- System Python API.
- Docstring extraction rules.
- Docstring extraction rules.
- Readers, which encapsulate the input context .
- Readers, which encapsulate the input context .
- Parsers.
- Parsers.
- Document tree: the intermediate internal data structure. The
output of the Parser and Reader, and the input to the Writer
all share the same data structure.
- Document tree: the intermediate internal data structure. The
output of the Parser and Reader, and the input to the Writer all
share the same data structure.
- Transforms, which modify the document tree.
- Transforms, which modify the document tree.
- Writers for output formats.
- Writers for output formats.
- Distributors, which handle output management (one file, many
files, or objects in memory).
- Distributors, which handle output management (one file, many
files, or objects in memory).
These issues are applicable to any docstring processing system
implementation. PEP 258, Docutils Design Specification [13 ]_,
documents these issues.
These issues are applicable to any docstring processing system
implementation. PEP 258 [#PEP-258]_ documents these issues.
3. Docstring processing system implementation.
3. Docstring processing system implementation.
4. Input markup specifications: docstring syntax. PEP 287,
reStructuredText Docstring Format [15]_, proposes a standard
syntax.
4. Input markup specifications: docstring syntax. PEP 287 [#PEP-287]_
proposes a standard syntax.
5. Input parser implementations.
5. Input parser implementations.
6. Input context readers ("modes": Python source code, PEP,
standalone text file, email, etc.) and implementations.
6. Input context readers ("modes": Python source code, PEP, standalone
text file, email, etc.) and implementations.
7. Stylists: certain input context readers may have associated
stylists which allow for a variety of output document styles.
7. Stylists: certain input context readers may have associated
stylists which allow for a variety of output document styles.
8. Output formats (HTML, XML, TeX, DocBook, info, etc.) and writer
implementations.
8. Output formats (HTML, XML, TeX, DocBook, info, etc.) and writer
implementations.
Components 1, 2/3, and 4/5 are the subject of individual companion
PEPs. If there is another implementation of the framework or
syntax/parser, additional PEPs may be required. Multiple
implementations of each of components 6 and 7 will be required;
the PEP mechanism may be overkill for these components.
Components 1, 2/3/5, and 4 are the subject of individual companion
PEPs. If there is another implementation of the framework or
syntax/parser, additional PEPs may be required. Multiple
implementations of each of components 6 and 7 will be required; the
PEP mechanism may be overkill for these components.
Project Web Site
================
A SourceForge project has been set up for this work at
http://docutils.sourceforge.net/.
A SourceForge project has been set up for this work at
http://docutils.sourceforge.net/.
References and Footnotes
========================
[1] http://www.literateprogramming.com/
.. [#PEP-287] PEP 287, reStructuredText Docstring Format, Goodger
(http://www.python.org/peps/pep-0287.html)
[2] Perl "Plain Old Documentation"
http://www.perldoc.com/perl5.6/pod/perlpod.html
.. [#PEP-257] PEP 257, Docstring Conventions, Goodger, Van Rossum
(http://www.python.org/peps/pep-0257.html)
[3] http://java.sun.com/j2se/javadoc/
.. [#PEP-258] PEP 258, Docutils Design Specification, Goodger
(http://www.python.org/peps/pep-0258.html)
[4] http://www.helpmaster.com/hlp-developmentaids-autoduck.htm
.. _Literate Programming: http://www.literateprogramming.com/
[5] http://www-cs-faculty.stanford.edu/~knuth/cweb.html
.. _POD: http://www.perldoc.com/perl5.6/pod/perlpod.html
[6] http://www.lemburg.com/files/python/SoftwareDescriptions.html#doc.py
.. _Javadoc: http://java.sun.com/j2se/javadoc/
[7] http://starship.python.net/crew/danilo/pythondoc/
.. _Autoduck:
http://www.helpmaster.com/hlp-developmentaids-autoduck.htm
[8] http://happydoc.sourceforge.net/
.. _Web: http://www-cs-faculty.stanford.edu/~knuth/cweb.html
[9] http://www.btinternet.com/~tratt/comp/python/crystal/
.. _doc.py:
http://www.lemburg.com/files/python/SoftwareDescriptions.html#doc.py
[10] http://www.python.org/doc/current/lib/module-pydoc.html
.. _pythondoc:
.. _gendoc: http://starship.python.net/crew/danilo/pythondoc/
[11] http://homepage.ntlworld.com/tibsnjoan/docutils/
.. _HappyDoc: http://happydoc.sourceforge.net/
[12] http://www.cis.upenn.edu/~edloper/pydoc/
.. _Crystal: http://www.btinternet.com/~tratt/comp/python/crystal/
[13] PEP 258, Docutils Design Specification, Goodger
http://www.python.org/peps/pep-0258.html
.. _pydoc: http://www.python.org/doc/current/lib/module-pydoc.html
[14] PEP 257, Docstring Conventions, Goodger, Van Rossum
http://www.python.org/peps/pep-0257.html
.. _docutils: http://homepage.ntlworld.com/tibsnjoan/docutils/
[15] PEP 287, reStructuredText Docstring Format, Goodger
http://www.python.org/peps/pep-0287.html
.. _Docutils project: http://docutils.sourceforge.net/
[16] http://www.python.org/sigs/doc-sig/
.. _STMinus: http://www.cis.upenn.edu/~edloper/pydoc/
.. _Python Doc-SIG: http://www.python.org/sigs/doc-sig/
Copyright
=========
This document has been placed in the public domain.
This document has been placed in the public domain.
Acknowledgements
================
This document borrows ideas from the archives of the Python
Doc-SIG [16]_. Thanks to all members past & present.
This document borrows ideas from the archives of the `Python
Doc-SIG`_. Thanks to all members past & present.
Local Variables:
mode: indented-text
indent-tabs-mode: nil
fill-column: 70
sentence-end-double-space: t
End:
..
Local Variables:
mode: indented-text
indent-tabs-mode: nil
sentence-end-double-space: t
fill-column: 70
End:

359
pep-0257.txt
View File

@ -2,255 +2,262 @@ PEP: 257
Title: Docstring Conventions
Version: $Revision$
Last-Modified: $Date$
Author: goodger@users.sourceforge.net (David Goodger),
guido@python.org (Guido van Rossum)
Author: David Goodger <goodger@users.sourceforge.net>,
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.
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.
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!"
"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
-- 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 Docutils docstring
processing system [1] [2]) will be aware of the conventions, so
following them will get you the best results.
If you violate these conventions, the worst you'll get is some dirty
looks. But some software (such as the Docutils_ docstring processing
system [1]_ [2]_) will be aware of the conventions, so following them
will get you the best results.
Specification
=============
What is a Docstring?
--------------------
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.
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.
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:
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".
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".
2. String literals occurring immediately after another docstring are
called "additional docstrings".
Please see PEP 258 "Docutils Design Specification" [2] for a
detailed description of attribute and additional docstrings.
Please see PEP 258, "Docutils Design Specification" [2]_, for a
detailed description of attribute and additional docstrings.
XXX Mention docstrings of 2.2 properties.
XXX Mention docstrings of 2.2 properties.
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""".
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.
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::
One-line Docstrings
--------------------
def kos_root():
"""Return the pathname of the KOS root directory."""
global _kos_root
if _kos_root: return _kos_root
...
One-liners are for really obvious cases. They should really fit on
one line. For example::
Notes:
def kos_root():
"""Return the pathname of the KOS root directory."""
global _kos_root
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.
Notes:
- The closing quotes are on the same line as the opening quotes.
This looks better for one-liners.
- Triple quotes are used even though the string fits on one line.
This makes it easy to later expand it.
- There's no blank line either before or after the docstring.
- The closing quotes are on the same line as the opening quotes. This
looks better for one-liners.
- 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 ..."
- There's no blank line either before or after the docstring.
- The one-line docstring should NOT be a "signature" reiterating
the function/method parameters (which can be obtained by
introspection). Don't do::
- 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 ...".
def function(a, b):
"""function(a, b) -> list"""
- The one-line docstring should NOT be a "signature" reiterating the
function/method parameters (which can be obtained by introspection).
Don't do::
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):
"""function(a, b) -> list"""
def function(a, b):
"""Do X and return a 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::
(Of course "Do X" should be replaced by a useful description!)
def function(a, b):
"""Do X and return a list."""
Multi-line Docstrings
----------------------
(Of course "Do X" should be replaced by a useful description!)
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). 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.
Multi-line Docstrings
----------------------
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 or
methods generally don't have this requirement, unless the function
or method'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.
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 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 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.
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.
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 or methods generally
don't have this requirement, unless the function or method'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 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 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 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.
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.
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).
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.
*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::
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.
def complex(real=0.0, imag=0.0):
"""Form a complex number.
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).
Keyword arguments:
real -- the real part (default 0.0)
imag -- the imaginary part (default 0.0)
*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::
"""
if imag == 0.0 and real == 0.0: return complex_zero
...
def complex(real=0.0, imag=0.0):
"""Form a complex number.
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.
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.
References and Footnotes
========================
[1] PEP 256, Docstring Processing System Framework, Goodger
http://www.python.org/peps/pep-0256.html
.. [1] PEP 256, Docstring Processing System Framework, Goodger
(http://www.python.org/peps/pep-0256.html)
[2] PEP 258, Docutils Design Specification, Goodger
http://www.python.org/peps/pep-0258.html
.. [2] PEP 258, Docutils Design Specification, Goodger
(http://www.python.org/peps/pep-0258.html)
[3] Guido van Rossum, Python's creator and Benevolent Dictator For
Life.
.. [3] Guido van Rossum, Python's creator and Benevolent Dictator For
Life.
[4] http://www.python.org/doc/essays/styleguide.html
.. _Docutils: http://docutils.sourceforge.net/
[5] http://www.python.org/sigs/doc-sig/
.. _Python Style Guide:
http://www.python.org/doc/essays/styleguide.html
.. _Doc-SIG: http://www.python.org/sigs/doc-sig/
Copyright
=========
This document has been placed in the public domain.
This document has been placed in the public domain.
Acknowledgements
================
The "Specification" text comes mostly verbatim from the Python
Style Guide essay by Guido van Rossum [4].
The "Specification" text comes mostly verbatim from the `Python Style
Guide`_ essay by Guido van Rossum.
This document borrows ideas from the archives of the Python
Doc-SIG [5]. Thanks to all members past and present.
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:
..
Local Variables:
mode: indented-text
indent-tabs-mode: nil
fill-column: 70
sentence-end-double-space: t
End:

1341
pep-0258.txt
View File

File diff suppressed because it is too large Load Diff

1182
pep-0287.txt
View File

File diff suppressed because it is too large Load Diff