CINXE.COM

<!DOCTYPE html> <html lang="en"> <head> <meta charset="utf-8"> <meta name="viewport" content="width=device-width, initial-scale=1.0"> <meta name="color-scheme" content="light dark"> <title>PEP 257 – Docstring Conventions | peps.python.org</title> <link rel="shortcut icon" href="../_static/py.png"> <link rel="canonical" href="https://peps.python.org/pep-0257/"> <link rel="stylesheet" href="../_static/style.css" type="text/css"> <link rel="stylesheet" href="../_static/mq.css" type="text/css"> <link rel="stylesheet" href="../_static/pygments.css" type="text/css" media="(prefers-color-scheme: light)" id="pyg-light"> <link rel="stylesheet" href="../_static/pygments_dark.css" type="text/css" media="(prefers-color-scheme: dark)" id="pyg-dark"> <link rel="alternate" type="application/rss+xml" title="Latest PEPs" href="https://peps.python.org/peps.rss"> <meta property="og:title" content='PEP 257 – Docstring Conventions | peps.python.org'> <meta property="og:description" content="This PEP documents the semantics and conventions associated with Python docstrings."> <meta property="og:type" content="website"> <meta property="og:url" content="https://peps.python.org/pep-0257/"> <meta property="og:site_name" content="Python Enhancement Proposals (PEPs)"> <meta property="og:image" content="https://peps.python.org/_static/og-image.png"> <meta property="og:image:alt" content="Python PEPs"> <meta property="og:image:width" content="200"> <meta property="og:image:height" content="200"> <meta name="description" content="This PEP documents the semantics and conventions associated with Python docstrings."> <meta name="theme-color" content="#3776ab"> </head> <body> <svg xmlns="http://www.w3.org/2000/svg" style="display: none;"> <symbol id="svg-sun-half" viewBox="0 0 24 24" pointer-events="all"> <title>Following system colour scheme</title> <svg xmlns="http://www.w3.org/2000/svg" viewBox="0 0 24 24" fill="none" stroke="currentColor" stroke-width="2" stroke-linecap="round" stroke-linejoin="round"> <circle cx="12" cy="12" r="9"></circle> <path d="M12 3v18m0-12l4.65-4.65M12 14.3l7.37-7.37M12 19.6l8.85-8.85"></path> </svg> </symbol> <symbol id="svg-moon" viewBox="0 0 24 24" pointer-events="all"> <title>Selected dark colour scheme</title> <svg xmlns="http://www.w3.org/2000/svg" viewBox="0 0 24 24" fill="none" stroke="currentColor" stroke-width="2" stroke-linecap="round" stroke-linejoin="round"> <path stroke="none" d="M0 0h24v24H0z" fill="none"></path> <path d="M12 3c.132 0 .263 0 .393 0a7.5 7.5 0 0 0 7.92 12.446a9 9 0 1 1 -8.313 -12.454z"></path> </svg> </symbol> <symbol id="svg-sun" viewBox="0 0 24 24" pointer-events="all"> <title>Selected light colour scheme</title> <svg xmlns="http://www.w3.org/2000/svg" viewBox="0 0 24 24" fill="none" stroke="currentColor" stroke-width="2" stroke-linecap="round" stroke-linejoin="round"> <circle cx="12" cy="12" r="5"></circle> <line x1="12" y1="1" x2="12" y2="3"></line> <line x1="12" y1="21" x2="12" y2="23"></line> <line x1="4.22" y1="4.22" x2="5.64" y2="5.64"></line> <line x1="18.36" y1="18.36" x2="19.78" y2="19.78"></line> <line x1="1" y1="12" x2="3" y2="12"></line> <line x1="21" y1="12" x2="23" y2="12"></line> <line x1="4.22" y1="19.78" x2="5.64" y2="18.36"></line> <line x1="18.36" y1="5.64" x2="19.78" y2="4.22"></line> </svg> </symbol> </svg> <script> document.documentElement.dataset.colour_scheme = localStorage.getItem("colour_scheme") || "auto" </script> <section id="pep-page-section"> <header> <h1>Python Enhancement Proposals</h1> <ul class="breadcrumbs"> <li><a href="https://www.python.org/" title="The Python Programming Language">Python</a> » </li> <li><a href="../pep-0000/">PEP Index</a> » </li> <li>PEP 257</li> </ul> <button id="colour-scheme-cycler" onClick="setColourScheme(nextColourScheme())"> <svg aria-hidden="true" class="colour-scheme-icon-when-auto"><use href="#svg-sun-half"></use></svg> <svg aria-hidden="true" class="colour-scheme-icon-when-dark"><use href="#svg-moon"></use></svg> <svg aria-hidden="true" class="colour-scheme-icon-when-light"><use href="#svg-sun"></use></svg> Toggle light / dark / auto colour theme </button> </header> <article> <section id="pep-content"> <h1 class="page-title">PEP 257 – Docstring Conventions</h1> <dl class="rfc2822 field-list simple"> <dt class="field-odd">Author:</dt> <dd class="field-odd">David Goodger <goodger at python.org>, Guido van Rossum <guido at python.org></dd> <dt class="field-even">Discussions-To:</dt> <dd class="field-even"><a class="reference external" href="https://mail.python.org/mailman/listinfo/doc-sig">Doc-SIG list</a></dd> <dt class="field-odd">Status:</dt> <dd class="field-odd"><abbr title="Currently valid informational guidance, or an in-use process">Active</abbr></dd> <dt class="field-even">Type:</dt> <dd class="field-even"><abbr title="Non-normative PEP containing background, guidelines or other information relevant to the Python ecosystem">Informational</abbr></dd> <dt class="field-odd">Created:</dt> <dd class="field-odd">29-May-2001</dd> <dt class="field-even">Post-History:</dt> <dd class="field-even">13-Jun-2001</dd> </dl> <hr class="docutils" /> <section id="contents"> <details><summary>Table of Contents</summary><ul class="simple"> <li><a class="reference internal" href="#abstract">Abstract</a></li> <li><a class="reference internal" href="#rationale">Rationale</a></li> <li><a class="reference internal" href="#specification">Specification</a><ul> <li><a class="reference internal" href="#what-is-a-docstring">What is a Docstring?</a></li> <li><a class="reference internal" href="#one-line-docstrings">One-line Docstrings</a></li> <li><a class="reference internal" href="#multi-line-docstrings">Multi-line Docstrings</a></li> <li><a class="reference internal" href="#handling-docstring-indentation">Handling Docstring Indentation</a></li> </ul> </li> <li><a class="reference internal" href="#copyright">Copyright</a></li> <li><a class="reference internal" href="#acknowledgements">Acknowledgements</a></li> </ul> </details></section> <section id="abstract"> <h2><a class="toc-backref" href="#abstract" role="doc-backlink">Abstract</a></h2> This PEP documents the semantics and conventions associated with Python docstrings. </section> <section id="rationale"> <h2><a class="toc-backref" href="#rationale" role="doc-backlink">Rationale</a></h2> 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. <blockquote> <div>“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 </div></blockquote> 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="https://docutils.sourceforge.io/">Docutils</a> docstring processing system <a class="pep reference internal" href="../pep-0256/" title="PEP 256 – Docstring Processing System Framework">PEP 256</a>, <a class="pep reference internal" href="../pep-0258/" title="PEP 258 – Docutils Design Specification">PEP 258</a>) will be aware of the conventions, so following them will get you the best results. </section> <section id="specification"> <h2><a class="toc-backref" href="#specification" role="doc-backlink">Specification</a></h2> <section id="what-is-a-docstring"> <h3><a class="toc-backref" href="#what-is-a-docstring" role="doc-backlink">What is a Docstring?</a></h3> 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 <code class="docutils literal notranslate">__doc__</code> 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 <code class="docutils literal notranslate">__init__</code> constructor) should also have docstrings. A package may be documented in the module docstring of the <code class="docutils literal notranslate">__init__.py</code> 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 <code class="docutils literal notranslate">__doc__</code>), but two types of extra docstrings may be extracted by software tools: <ol class="arabic simple"> <li>String literals occurring immediately after a simple assignment at the top level of a module, class, or <code class="docutils literal notranslate">__init__</code> method are called “attribute docstrings”.</li> <li>String literals occurring immediately after another docstring are called “additional docstrings”.</li> </ol> Please see <a class="pep reference internal" href="../pep-0258/" title="PEP 258 – Docutils Design Specification">PEP 258</a>, “Docutils Design Specification”, for a detailed description of attribute and additional docstrings. For consistency, always use <code class="docutils literal notranslate">"""triple double quotes"""</code> around docstrings. Use <code class="docutils literal notranslate">r"""raw triple double quotes"""</code> if you use any backslashes in your docstrings. There are two forms of docstrings: one-liners and multi-line docstrings. </section> <section id="one-line-docstrings"> <h3><a class="toc-backref" href="#one-line-docstrings" role="doc-backlink">One-line Docstrings</a></h3> One-liners are for really obvious cases. They should really fit on one line. For example: <div class="highlight-default notranslate"><div class="highlight"><pre>def kos_root(): """Return the pathname of the KOS root directory.""" global _kos_root if _kos_root: return _kos_root ... </pre></div> </div> Notes: <ul> <li>Triple quotes are used even though the string fits on one line. This makes it easy to later expand it.</li> <li>The closing quotes are on the same line as the opening quotes. This looks better for one-liners.</li> <li>There’s no blank line either before or after the docstring.</li> <li>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 …”.</li> <li>The one-line docstring should NOT be a “signature” reiterating the function/method parameters (which can be obtained by introspection). Don’t do:<div class="highlight-default notranslate"><div class="highlight"><pre>def function(a, b): """function(a, b) -> list""" </pre></div> </div> 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: <div class="highlight-default notranslate"><div class="highlight"><pre>def function(a, b): """Do X and return a list.""" </pre></div> </div> (Of course “Do X” should be replaced by a useful description!) </li> </ul> </section> <section id="multi-line-docstrings"> <h3><a class="toc-backref" href="#multi-line-docstrings" role="doc-backlink">Multi-line Docstrings</a></h3> 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 <code class="docutils literal notranslate">__init__.py</code> 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 <code class="docutils literal notranslate">__init__</code> 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: <div class="highlight-default notranslate"><div class="highlight"><pre>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></div> </div> Unless the entire docstring fits on a line, place the closing quotes on a line by themselves. This way, Emacs’ <code class="docutils literal notranslate">fill-paragraph</code> command can be used on it. </section> <section id="handling-docstring-indentation"> <h3><a class="toc-backref" href="#handling-docstring-indentation" role="doc-backlink">Handling Docstring Indentation</a></h3> 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: <div class="highlight-default notranslate"><div class="highlight"><pre>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) </pre></div> </div> The docstring in this example contains two newline characters and is therefore 3 lines long. The first and last lines are blank: <div class="highlight-default notranslate"><div class="highlight"><pre>def foo(): """ This is the second line of the docstring. """ </pre></div> </div> To illustrate: <div class="highlight-default notranslate"><div class="highlight"><pre>>>> 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></div> </div> Once trimmed, these docstrings are equivalent: <div class="highlight-default notranslate"><div class="highlight"><pre>def foo(): """A multi-line docstring. """ def bar(): """ A multi-line docstring. """ </pre></div> </div> </section> </section> <section id="copyright"> <h2><a class="toc-backref" href="#copyright" role="doc-backlink">Copyright</a></h2> This document has been placed in the public domain. </section> <section id="acknowledgements"> <h2><a class="toc-backref" href="#acknowledgements" role="doc-backlink">Acknowledgements</a></h2> The “Specification” text comes mostly verbatim from <a class="pep reference internal" href="../pep-0008/" title="PEP 8 – Style Guide for Python Code">PEP 8</a> by Guido van Rossum. This document borrows ideas from the archives of the Python <a class="reference external" href="https://www.python.org/community/sigs/current/doc-sig/">Doc-SIG</a>. Thanks to all members past and present. </section> </section> <hr class="docutils" /> Source: <a class="reference external" href="https://github.com/python/peps/blob/main/peps/pep-0257.rst">https://github.com/python/peps/blob/main/peps/pep-0257.rst</a> Last modified: <a class="reference external" href="https://github.com/python/peps/commits/main/peps/pep-0257.rst">2024-04-17 11:35:59 GMT</a> </article> <nav id="pep-sidebar"> <h2>Contents</h2> <ul> <li><a class="reference internal" href="#abstract">Abstract</a></li> <li><a class="reference internal" href="#rationale">Rationale</a></li> <li><a class="reference internal" href="#specification">Specification</a><ul> <li><a class="reference internal" href="#what-is-a-docstring">What is a Docstring?</a></li> <li><a class="reference internal" href="#one-line-docstrings">One-line Docstrings</a></li> <li><a class="reference internal" href="#multi-line-docstrings">Multi-line Docstrings</a></li> <li><a class="reference internal" href="#handling-docstring-indentation">Handling Docstring Indentation</a></li> </ul> </li> <li><a class="reference internal" href="#copyright">Copyright</a></li> <li><a class="reference internal" href="#acknowledgements">Acknowledgements</a></li> </ul> <a id="source" href="https://github.com/python/peps/blob/main/peps/pep-0257.rst">Page Source (GitHub)</a> </nav> </section> <script src="../_static/colour_scheme.js"></script> <script src="../_static/wrap_tables.js"></script> <script src="../_static/sticky_banner.js"></script> </body> </html>