NumPy-Style Docstring Convention

Contract

Every Python function, method, class, and generator is documented with a NumPy-style docstring: hyphen-underlined section headers, name : type parameter lines, and a bare-type Returns. Apply this whenever you write or edit a docstring. Do not use Google style (Args:), reStructuredText (:param:), or Epytext (@param) — those are the defaults to avoid.

Rules (the complete spec)

1. Quotes and summary. Open with """ and put the one-line summary on the line

immediately after the opening """ — not on the same line as the quotes. The summary is a single sentence in the imperative mood ("Compute…", "Fetch…", not "Computes…" / "Returns the…") and ends with a period. Close with """ on its own line.

1. Blank line, then sections. Leave one blank line after the summary, then emit the

applicable sections in this exact order, omitting any that do not apply: Parameters → Returns (or Yields) → Raises. (Less common sections, when used, slot in as: Parameters, Returns/Yields, Other Parameters, Raises, See Also, Notes, Examples.)

1. Header underline. Write each section header as a plain word on its own line, followed

immediately by a line of hyphens (-) exactly as long as the header text — never a trailing colon:

• Parameters then ---------- (10 hyphens)
• Returns then ------- (7 hyphens)
• Raises then ------ (6 hyphens)
• Yields then ------ (6 hyphens)

1. Parameter lines. Document each parameter as name : type — name, single space,

colon, single space, type — on its own line. The description goes on the following line(s), indented four spaces. Multiple types are joined with or (int or None). Optional arguments append , optional after the type: page : int, optional.

1. Returns. Give the bare type on its own line — no parameter name — with the

description indented four spaces beneath it. A name before the colon (result : dict) is a Returns-line error; that form is only for Parameters.

1. Raises. List each raised exception as the bare ExceptionType on its own line,

with the triggering condition indented four spaces beneath it. One entry per distinct exception, in the order they can be raised.

1. Generators. Use a Yields section (not Returns) for the yielded value, formatted

exactly like Returns — bare type, description indented beneath.

1. self / cls. Never document self or cls in Parameters. For a class, the Parameters

section documents the constructor (__init__) arguments.

1. Variadics. Document *args as *args : type and **kwargs as **kwargs : type

(keep the stars), or under their real names (*dicts : dict).

1. Forbidden tokens. Never emit Args:, Arguments:, Attributes:, :param,

:returns:, :raises:, @param, or any colon-terminated header. Headers are always underlined with hyphens.

Worked examples (BEFORE = the wrong default, AFTER = conforming)

Rule 1 + 3 — summary placement and underlines. Base default = Google style.

python
# BEFORE (Google)
def to_celsius(f):
    """Convert Fahrenheit to Celsius.

    Args:
        f: Temperature in Fahrenheit.
    """
# AFTER (NumPy)
def to_celsius(f):
    """Convert Fahrenheit to Celsius.

    Parameters
    ----------
    f : float
        Temperature in Fahrenheit.
    """

Rule 4 — name : type spacing. Base writes f: float or f (float):.

python
# BEFORE
    """...
    Parameters
    ----------
    f: float            # no space before colon
        ...
    """
# AFTER
    """...
    Parameters
    ----------
    f : float           # space, colon, space
        ...
    """

Rule 5 — Returns is a bare type, no name. Base names the return value.

python
# BEFORE
    """Compute cosine similarity.

    Returns:
        score (float): Similarity in [-1, 1].
    """
# AFTER
    """Compute cosine similarity.

    Returns
    -------
    float
        Similarity in [-1, 1].
    """

Rule 6 — Raises lists bare exception types. Base uses RST or omits Raises.

python
# BEFORE
    """Divide a by b.

    :raises ZeroDivisionError: if b is zero.
    """
# AFTER
    """Divide a by b.

    Raises
    ------
    ZeroDivisionError
        If b is zero.
    """

Rule 7 — generators use Yields. Base writes Returns.

python
# BEFORE
    """Yield fixed-size batches.

    Returns:
        list: Each successive batch.
    """
# AFTER
    """Yield fixed-size batches.

    Yields
    ------
    list
        Each successive batch of items.
    """

Rule 8 — self is not documented. Base lists self under Args.

python
# BEFORE
    """Withdraw from the account.

    Args:
        self: The account.
        amount (float): Amount to withdraw.
    """
# AFTER
    """Withdraw from the account.

    Parameters
    ----------
    amount : float
        Amount to withdraw.
    """

Edge cases & exceptions

• No parameters / returns nothing. Omit the empty section entirely — do not write an

empty Parameters header. For -> None, you may omit Returns or write a Returns section whose bare type is None; never write a Google Returns: header.

• Optional with default. Reflect the default in the type, not a separate field:

cc : list, optional. The description states the default behavior ("Defaults to None.").

• Union / multiple types. Join with or: value : int or float. Do not use Python typing

syntax like Union[int, float] in the type slot unless that is the literal annotation.

• Class docstring. Place it under the class line and document constructor args in

Parameters; if you also document instance state, use an Attributes NumPy section (hyphen-underlined, 10 hyphens), never Google's Attributes: colon header.

• Async functions. Identical rules — async def changes nothing about the docstring.
• Multiple raises. Each distinct exception gets its own bare-type line under one Raises

header; do not collapse them into one line or repeat the Raises header.

Do / Don't

• Never end a section header with a colon (Parameters:). Always underline it with

hyphens matching the header length.

• Never write name: type or name (type):. Always write name : type (spaced colon).
• Never put a name on the Returns type line. Always give the bare type only.
• Never use :param: / @param: / Args:. Always use the hyphen-underlined headers.
• Never document self/cls. Always start Parameters at the first real argument.
• Never put the summary on the same line as the opening """. Always drop it to the

next line.

Common mistakes (the base's wrong defaults)

• Falling back to Google style (Args: / Returns:) — the single most frequent miss.
• Using name: type (Python annotation spacing) instead of name : type.
• Writing Returns\n-------\nresult : dict — putting a parameter name on the Returns line.
• Underlining with the wrong count (e.g. Parameters with 8 hyphens) or omitting the

underline and using a colon instead.

• Using Returns for a generator instead of Yields.
• Documenting self as the first parameter.
• Mixing RST (:raises:) into an otherwise NumPy docstring.

Quick checklist

• ] Summary on the line after """, imperative, ends with a period.
• ] Sections in order: Parameters → Returns/Yields → Raises; empties omitted.
• ] Every header underlined with hyphens of matching length (10 / 7 / 6 / 6), no colons.
• ] Params as name : type, description indented 4 spaces; self/cls excluded.
• ] Returns/Yields = bare type, no name. Raises = bare exception types.
• ] Zero occurrences of Args:, :param, @param, or any colon-terminated header.