/usr/share/doc/docutils-doc/docs/peps/pep-0257.html is in docutils-doc 0.12+dfsg-1.
This file is owned by root:root, with mode 0o644.
The actual contents of the file can be viewed below.
1 2 3 4 5 6 7 8 9 10 11 12 13 14 15 16 17 18 19 20 21 22 23 24 25 26 27 28 29 30 31 32 33 34 35 36 37 38 39 40 41 42 43 44 45 46 47 48 49 50 51 52 53 54 55 56 57 58 59 60 61 62 63 64 65 66 67 68 69 70 71 72 73 74 75 76 77 78 79 80 81 82 83 84 85 86 87 88 89 90 91 92 93 94 95 96 97 98 99 100 101 102 103 104 105 106 107 108 109 110 111 112 113 114 115 116 117 118 119 120 121 122 123 124 125 126 127 128 129 130 131 132 133 134 135 136 137 138 139 140 141 142 143 144 145 146 147 148 149 150 151 152 153 154 155 156 157 158 159 160 161 162 163 164 165 166 167 168 169 170 171 172 173 174 175 176 177 178 179 180 181 182 183 184 185 186 187 188 189 190 191 192 193 194 195 196 197 198 199 200 201 202 203 204 205 206 207 208 209 210 211 212 213 214 215 216 217 218 219 220 221 222 223 224 225 226 227 228 229 230 231 232 233 234 235 236 237 238 239 240 241 242 243 244 245 246 247 248 249 250 251 252 253 254 255 256 257 258 259 260 261 262 263 264 265 266 267 268 269 270 271 272 273 274 275 276 277 278 279 280 281 282 283 284 285 286 287 288 289 290 291 292 293 294 295 296 297 298 299 300 301 302 303 304 305 306 307 308 309 310 311 312 313 314 315 316 317 318 319 320 321 322 323 324 325 326 327 328 329 330 331 332 333 334 335 336 337 338 339 340 341 342 343 344 345 346 347 348 349 350 351 352 353 354 355 356 357 358 359 360 361 362 363 364 365 366 367 368 369 370 371 372 373 374 375 376 377 378 379 380 381 382 | <?xml version="1.0" encoding="utf-8" ?>
<!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Transitional//EN" "http://www.w3.org/TR/xhtml1/DTD/xhtml1-transitional.dtd">
<html xmlns="http://www.w3.org/1999/xhtml" xml:lang="en" lang="en">
<!--
This HTML is auto-generated. DO NOT EDIT THIS FILE! If you are writing a new
PEP, see http://www.python.org/dev/peps/pep-0001 for instructions and links
to templates. DO NOT USE THIS HTML FILE AS YOUR TEMPLATE!
-->
<head>
<meta http-equiv="Content-Type" content="text/html; charset=utf-8" />
<meta name="generator" content="Docutils 0.12: http://docutils.sourceforge.net/" />
<title>PEP 257 -- Docstring Conventions</title>
<link rel="stylesheet" href="../../css/pep.css" type="text/css" />
</head>
<body bgcolor="white">
<table class="navigation" cellpadding="0" cellspacing="0"
width="100%" border="0">
<tr><td class="navicon" width="150" height="35">
<a href="http://www.python.org/" title="Python Home Page">
[Python]</a></td>
<td class="textlinks" align="left">
[<b><a href="http://www.python.org/">Python Home</a></b>]
[<b><a href="http://www.python.org/dev/peps/">PEP Index</a></b>]
[<b><a href="./pep-0257.txt">PEP Source</a></b>]
</td></tr></table>
<div class="document">
<table class="rfc2822 docutils field-list" frame="void" rules="none">
<col class="field-name" />
<col class="field-body" />
<tbody valign="top">
<tr class="field"><th class="field-name">PEP:</th><td class="field-body">257</td>
</tr>
<tr class="field"><th class="field-name">Title:</th><td class="field-body">Docstring Conventions</td>
</tr>
<tr class="field"><th class="field-name">Version:</th><td class="field-body">4564</td>
</tr>
<tr class="field"><th class="field-name">Last-Modified:</th><td class="field-body"><a class="reference external" href="http://svn.python.org/view/*checkout*/peps/trunk/pep-0257.txt">2006-05-21 22:44:42 +0200 (Son, 21. Mai 2006)</a></td>
</tr>
<tr class="field"><th class="field-name">Authors:</th><td class="field-body">David Goodger <<a class="reference external" href="mailto:goodger@python.org">goodger@python.org</a>>,
Guido van Rossum <<a class="reference external" href="mailto:guido@python.org">guido@python.org</a>></td>
</tr>
<tr class="field"><th class="field-name">Discussions-To:</th><td class="field-body"><a class="reference external" href="mailto:doc-sig@python.org?subject=PEP%20257">doc-sig at python.org</a></td>
</tr>
<tr class="field"><th class="field-name">Status:</th><td class="field-body">Active</td>
</tr>
<tr class="field"><th class="field-name">Type:</th><td class="field-body">Informational</td>
</tr>
<tr class="field"><th class="field-name">Content-Type:</th><td class="field-body"><a class="reference external" href="http://www.python.org/dev/peps/pep-0012">text/x-rst</a></td>
</tr>
<tr class="field"><th class="field-name">Created:</th><td class="field-body">29-May-2001</td>
</tr>
<tr class="field"><th class="field-name">Post-History:</th><td class="field-body">13-Jun-2001</td>
</tr>
</tbody>
</table>
<hr />
<div class="contents topic" id="contents">
<p class="topic-title first">Contents</p>
<ul class="simple">
<li><a class="reference internal" href="#abstract" id="id14">Abstract</a></li>
<li><a class="reference internal" href="#rationale" id="id15">Rationale</a></li>
<li><a class="reference internal" href="#specification" id="id16">Specification</a><ul>
<li><a class="reference internal" href="#what-is-a-docstring" id="id17">What is a Docstring?</a></li>
<li><a class="reference internal" href="#one-line-docstrings" id="id18">One-line Docstrings</a></li>
<li><a class="reference internal" href="#multi-line-docstrings" id="id19">Multi-line Docstrings</a></li>
<li><a class="reference internal" href="#handling-docstring-indentation" id="id20">Handling Docstring Indentation</a></li>
</ul>
</li>
<li><a class="reference internal" href="#references-and-footnotes" id="id21">References and Footnotes</a></li>
<li><a class="reference internal" href="#copyright" id="id22">Copyright</a></li>
<li><a class="reference internal" href="#acknowledgements" id="id23">Acknowledgements</a></li>
</ul>
</div>
<div class="section" id="abstract">
<h1><a class="toc-backref" href="#id14">Abstract</a></h1>
<p>This PEP documents the semantics and conventions associated with
Python docstrings.</p>
</div>
<div class="section" id="rationale">
<h1><a class="toc-backref" href="#id15">Rationale</a></h1>
<p>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.</p>
<blockquote>
<p>"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!"</p>
<p class="attribution">—Tim Peters on comp.lang.python, 2001-06-16</p>
</blockquote>
<p>If you violate these conventions, the worst you'll get is some dirty
looks. But some software (such as the <a class="reference external" href="http://docutils.sourceforge.net/">Docutils</a> <a class="footnote-reference" href="#id8" id="id9">[4]</a> docstring processing
system <a class="footnote-reference" href="#id5" id="id1">[1]</a> <a class="footnote-reference" href="#id6" id="id2">[2]</a>) will be aware of the conventions, so following them
will get you the best results.</p>
</div>
<div class="section" id="specification">
<h1><a class="toc-backref" href="#id16">Specification</a></h1>
<div class="section" id="what-is-a-docstring">
<h2><a class="toc-backref" href="#id17">What is a Docstring?</a></h2>
<p>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 <tt class="docutils literal">__doc__</tt> special attribute of that object.</p>
<p>All modules should normally have docstrings, and all functions and
classes exported by a module should also have docstrings. Public
methods (including the <tt class="docutils literal">__init__</tt> constructor) should also have
docstrings. A package may be documented in the module docstring of
the <tt class="docutils literal">__init__.py</tt> file in the package directory.</p>
<p>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 <tt class="docutils literal">__doc__</tt>), but two types of extra docstrings may be
extracted by software tools:</p>
<ol class="arabic simple">
<li>String literals occurring immediately after a simple assignment at
the top level of a module, class, or <tt class="docutils literal">__init__</tt> method are called
"attribute docstrings".</li>
<li>String literals occurring immediately after another docstring are
called "additional docstrings".</li>
</ol>
<p>Please see <a class="reference external" href="http://www.python.org/dev/peps/pep-0258">PEP 258</a>, "Docutils Design Specification" <a class="footnote-reference" href="#id6" id="id3">[2]</a>, for a
detailed description of attribute and additional docstrings.</p>
<p>XXX Mention docstrings of 2.2 properties.</p>
<p>For consistency, always use <tt class="docutils literal"><span class="pre">"""triple</span> double <span class="pre">quotes"""</span></tt> around
docstrings. Use <tt class="docutils literal"><span class="pre">r"""raw</span> triple double <span class="pre">quotes"""</span></tt> if you use any
backslashes in your docstrings. For Unicode docstrings, use
<tt class="docutils literal"><span class="pre">u"""Unicode</span> <span class="pre">triple-quoted</span> <span class="pre">strings"""</span></tt>.</p>
<p>There are two forms of docstrings: one-liners and multi-line
docstrings.</p>
</div>
<div class="section" id="one-line-docstrings">
<h2><a class="toc-backref" href="#id18">One-line Docstrings</a></h2>
<p>One-liners are for really obvious cases. They should really fit on
one line. For example:</p>
<pre class="literal-block">
def kos_root():
"""Return the pathname of the KOS root directory."""
global _kos_root
if _kos_root: return _kos_root
...
</pre>
<p>Notes:</p>
<ul>
<li><p class="first">Triple quotes are used even though the string fits on one line.
This makes it easy to later expand it.</p>
</li>
<li><p class="first">The closing quotes are on the same line as the opening quotes. This
looks better for one-liners.</p>
</li>
<li><p class="first">There's no blank line either before or after the docstring.</p>
</li>
<li><p class="first">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 ...".</p>
</li>
<li><p class="first">The one-line docstring should NOT be a "signature" reiterating the
function/method parameters (which can be obtained by introspection).
Don't do:</p>
<pre class="literal-block">
def function(a, b):
"""function(a, b) -> list"""
</pre>
<p>This type of docstring is only appropriate for C functions (such as
built-ins), where introspection is not possible. However, the
nature of the <em>return value</em> cannot be determined by introspection,
so it should be mentioned. The preferred form for such a docstring
would be something like:</p>
<pre class="literal-block">
def function(a, b):
"""Do X and return a list."""
</pre>
<p>(Of course "Do X" should be replaced by a useful description!)</p>
</li>
</ul>
</div>
<div class="section" id="multi-line-docstrings">
<h2><a class="toc-backref" href="#id19">Multi-line Docstrings</a></h2>
<p>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).</p>
<p>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.</p>
<p>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.</p>
<p>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 <tt class="docutils literal">__init__.py</tt> module) should also list the modules and
subpackages exported by the package.</p>
<p>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.</p>
<p>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 <tt class="docutils literal">__init__</tt>
method. Individual methods should be documented by their own
docstring.</p>
<p>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).</p>
<p><em>Do not</em> 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:</p>
<pre class="literal-block">
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
...
</pre>
<p>The BDFL <a class="footnote-reference" href="#id7" id="id4">[3]</a> 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'
<tt class="docutils literal"><span class="pre">fill-paragraph</span></tt> command can be used on it.</p>
</div>
<div class="section" id="handling-docstring-indentation">
<h2><a class="toc-backref" href="#id20">Handling Docstring Indentation</a></h2>
<p>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.</p>
<p>Since code is much more precise than words, here is an implementation
of the algorithm:</p>
<pre class="literal-block">
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.maxint
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.maxint:
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)
</pre>
<p>The docstring in this example contains two newline characters and is
therefore 3 lines long. The first and last lines are blank:</p>
<pre class="literal-block">
def foo():
"""
This is the second line of the docstring.
"""
</pre>
<p>To illustrate:</p>
<pre class="literal-block">
>>> 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.'
</pre>
<p>Once trimmed, these docstrings are equivalent:</p>
<pre class="literal-block">
def foo():
"""A multi-line
docstring.
"""
def bar():
"""
A multi-line
docstring.
"""
</pre>
</div>
</div>
<div class="section" id="references-and-footnotes">
<h1><a class="toc-backref" href="#id21">References and Footnotes</a></h1>
<table class="docutils footnote" frame="void" id="id5" rules="none">
<colgroup><col class="label" /><col /></colgroup>
<tbody valign="top">
<tr><td class="label"><a class="fn-backref" href="#id1">[1]</a></td><td><a class="reference external" href="http://www.python.org/dev/peps/pep-0256">PEP 256</a>, Docstring Processing System Framework, Goodger
(<a class="reference external" href="http://www.python.org/peps/pep-0256.html">http://www.python.org/peps/pep-0256.html</a>)</td></tr>
</tbody>
</table>
<table class="docutils footnote" frame="void" id="id6" rules="none">
<colgroup><col class="label" /><col /></colgroup>
<tbody valign="top">
<tr><td class="label">[2]</td><td><em>(<a class="fn-backref" href="#id2">1</a>, <a class="fn-backref" href="#id3">2</a>)</em> <a class="reference external" href="http://www.python.org/dev/peps/pep-0258">PEP 258</a>, Docutils Design Specification, Goodger
(<a class="reference external" href="http://www.python.org/peps/pep-0258.html">http://www.python.org/peps/pep-0258.html</a>)</td></tr>
</tbody>
</table>
<table class="docutils footnote" frame="void" id="id7" rules="none">
<colgroup><col class="label" /><col /></colgroup>
<tbody valign="top">
<tr><td class="label"><a class="fn-backref" href="#id4">[3]</a></td><td>Guido van Rossum, Python's creator and Benevolent Dictator For
Life.</td></tr>
</tbody>
</table>
<table class="docutils footnote" frame="void" id="id8" rules="none">
<colgroup><col class="label" /><col /></colgroup>
<tbody valign="top">
<tr><td class="label"><a class="fn-backref" href="#id9">[4]</a></td><td><a class="reference external" href="http://docutils.sourceforge.net/">http://docutils.sourceforge.net/</a></td></tr>
</tbody>
</table>
<table class="docutils footnote" frame="void" id="id10" rules="none">
<colgroup><col class="label" /><col /></colgroup>
<tbody valign="top">
<tr><td class="label"><a class="fn-backref" href="#id11">[5]</a></td><td><a class="reference external" href="http://www.python.org/doc/essays/styleguide.html">http://www.python.org/doc/essays/styleguide.html</a></td></tr>
</tbody>
</table>
<table class="docutils footnote" frame="void" id="id12" rules="none">
<colgroup><col class="label" /><col /></colgroup>
<tbody valign="top">
<tr><td class="label"><a class="fn-backref" href="#id13">[6]</a></td><td><a class="reference external" href="http://www.python.org/sigs/doc-sig/">http://www.python.org/sigs/doc-sig/</a></td></tr>
</tbody>
</table>
</div>
<div class="section" id="copyright">
<h1><a class="toc-backref" href="#id22">Copyright</a></h1>
<p>This document has been placed in the public domain.</p>
</div>
<div class="section" id="acknowledgements">
<h1><a class="toc-backref" href="#id23">Acknowledgements</a></h1>
<p>The "Specification" text comes mostly verbatim from the <a class="reference external" href="http://www.python.org/doc/essays/styleguide.html">Python Style
Guide</a> <a class="footnote-reference" href="#id10" id="id11">[5]</a> essay by Guido van Rossum.</p>
<p>This document borrows ideas from the archives of the Python <a class="reference external" href="http://www.python.org/sigs/doc-sig/">Doc-SIG</a> <a class="footnote-reference" href="#id12" id="id13">[6]</a>.
Thanks to all members past and present.</p>
<!-- Local Variables:
mode: indented-text
indent-tabs-mode: nil
fill-column: 70
sentence-end-double-space: t
End: -->
</div>
</div>
</body>
</html>
|