Python REST Docstrings

Python Docstrings — reST Style

A docstring earns its place by saying what type hints cannot: meaning, constraints, side effects, and failure conditions. reST style expresses those in Sphinx's native language — info field lists (:param:, :returns:, :raises:) and cross-reference roles — so write for two readers at once: a human scanning a tooltip and Sphinx rendering API docs with real links.

Canonical shape

async def fetch_one(self, query: str, *args: Any) -> Mapping[str, Any] | None:
    """Execute a query and return the first matching row.

    :param query: SQL query text with numbered placeholders.
    :param args: Positional parameters bound to the placeholders.
    :returns: The first row as a mapping, or ``None`` when no rows match.
    :raises QueryError: If the query is malformed or the connection is closed.
    """

• Field order: :param: → :returns: → :raises:; keep the field list as one block after the summary (and optional body), separated by a blank line.
• Name varargs without stars in the field (:param args:); the signature already shows the stars.
• With annotations present, omit :type: and :rtype: — duplicating annotations invites drift, and Sphinx autodoc can merge annotations into the output.

Summary line

• One line directly after """, ending with a period; blank line before anything else. State what the caller gets — never "This function ...".
• PEP 257 prescribes imperative mood for functions and methods: a command such as "Return the first row.", not the description "Returns the first row.".

Field lists

Standardize on :param:, :returns:, and :raises: — the aliases render the same, but one spelling keeps grep and review trivial. Sphinx cross-references the exception name in :raises ExcName: automatically, like an implicit :exc: role. Include only fields that add information; a restating field is noise.

Cross-references and literals

Use roles instead of plain names — they become real links in rendered docs: :mod: (modules), :class: (classes), :meth: (methods), :func: (functions), :attr: (attributes and properties), :exc: (exceptions), :data: (module-level data), :obj: (anything else). Prefix a target with ~ to render only its last component:

:meth:`initialize`          -> link "initialize" (resolved within the class)
:class:`pkg.mod.Foo`        -> link "pkg.mod.Foo" (cross-module: fully qualify)
:meth:`~queue.Queue.get`    -> link rendered as just "get"

Unqualified targets resolve against the current class, then the current module — so short names work locally; fully qualify cross-module targets. Use double backticks for literal values — None, 'tuple', SQL fragments, flags, environment variables — so they render as code, not prose.

:raises: discipline

• Document only exceptions relevant to the caller's interface, each with its trigger condition — a bare exception name tells the caller nothing actionable.
• Never document exceptions raised because the caller violated the documented contract: that would paradoxically make behavior under violation of the API part of the API.
• On protocols and other interfaces, add :raises: only when raising is a required part of the contract, not a detail of one implementation.

Beyond plain functions

Classes and their attributes, properties, generators, type aliases, constants, TypedDict, and @overload / Protocol stubs each have a shape of their own — references/constructs.md. The rule that governs all of them: document the contract at the level the caller meets it. A property is documented as the value it yields, not as the method it happens to be; an @overload stub documents the one signature it declares, and the implementation carries the shared body.

Length and formatting

• Default docstring is the summary line alone. Add a body only when it earns its place — non-obvious behavior, side effects, invariants, "why" — in 1–3 sentences. Size :param:/:returns:/:raises: to the real API surface.
• Never restate the type in prose. Annotations carry the type; the description adds semantics: units, constraints, defaults on absence.
• Blank line between the summary (or body) and the field list.
• Wrap near 88 columns; the summary must stay on one physical line.

Anti-patterns

Related skills

• python-google-docstrings — the same rules expressed as Google-style sections via Sphinx Napoleon
• readable-code — better names and structure shrink what a docstring must explain. Absent it, the boundary still holds: a docstring states the contract, not the implementation.
• altitude-docs — deciding what belongs in docstrings vs higher-level documentation