Python Docstring Conventions

Contract

Write every Python function, method, and class docstring in this house variant of Google style. The rules below differ from standard Google style on several arbitrary, specific points — apply them exactly whenever you author or edit a docstring.

Rules

1. Summary line — imperative mood, bare verb. Start with a command verb:

Calculate, Fetch, Return, Parse, Build, Merge. Never third-person (Calculates, Fetches, Returns). One line, ending in a period.

1. Returns — always parenthesize the type, on its own indented line. Write

(bool): Whether the row was inserted. Never a bare bool:. The parentheses wrap the type only; the description follows the colon.

1. Multiple return values — list each named value separately. Never a tuple type.

For a function returning two things, write two entries (first (str): ... and last (str): ...), not (tuple[str, str]): or (tuple):.

1. Args — document every parameter; never state default values. No

Defaults to 5., no default: 5, no (default 5). Describe behavior only. Erase any default value you find in an existing Args description.

1. Optional parameters — put , optional inside the type parentheses. Write

timeout (int, optional): Seconds to wait. The marker goes in the parens, not in the prose, and it never carries a default value.

1. Types — builtins lowercase, PEP 604 unions. Use list, dict, tuple,

int, str, bool, bytes — never the capitalized typing forms List, Dict, Tuple. Use | for unions (int | None), never Optional[int] or Union[int, None]. Capitalize Any, Path, None.

1. Omit empty sections. Omit Returns: when the function returns nothing

(annotated -> None). Omit Args: when there are no parameters. Omit Raises: UNLESS the raise is a critical, contractual part of the function's behavior.

1. self and cls are never documented in a method's Args: section.

1. Indentation. Section headers (Args:, Returns:, Raises:, Examples:)

sit at 0 indent relative to the docstring body; their entries indent 4 spaces.

1. Classes get an Attributes: section only — omit Methods: and Args:.

__init__ gets Args: only — no Examples:, Notes:, or Methods:. Test functions get single-line docstrings only.

Worked examples

Rule 1 — imperative summary.

# BEFORE (base default: third-person)
"""Calculates the sum of two integers."""
# AFTER (house)
"""Calculate the sum of two integers."""

Rule 2 — parenthesized return type.

# BEFORE (standard Google: bare type)
Returns:
    bool: Whether the row was inserted.
# AFTER (house)
Returns:
    (bool): Whether the row was inserted.

Rule 3 — named values, not a tuple type.

# BEFORE
Returns:
    (tuple[str, str]): The first and last name.
# AFTER
Returns:
    first (str): The given name.
    last (str): The family name.

Rule 4 — no defaults in Args.

# BEFORE
Args:
    limit (int): Max rows to return. Defaults to 100.
# AFTER
Args:
    limit (int, optional): Max rows to return.

Rule 5 — , optional inside the parens.

# BEFORE
Args:
    timeout (int): Optional. Seconds to wait, defaults to 30.
# AFTER
Args:
    timeout (int, optional): Seconds to wait.

Rule 6 — lowercase builtins, | unions.

# BEFORE
Args:
    columns (Optional[List[str]]): Columns to select.
Returns:
    Optional[int]: The index, or None.
# AFTER
Args:
    columns (list | None, optional): Columns to select.
Returns:
    (int | None): The index, or None.

Rule 7 — omit empty/uncritical sections.

# BEFORE (base reflexively adds Returns + Raises)
"""Record an event.

Args:
    name (str): The event name.

Returns:
    None: Nothing.

Raises:
    RuntimeError: If logging is unconfigured.
"""
# AFTER (None return + non-critical raise both dropped)
"""Record an event.

Args:
    name (str): The event name.
"""

Rule 8 — never document self.

# BEFORE
Args:
    self: The instance.
    key (str): The lookup key.
# AFTER
Args:
    key (str): The lookup key.

Rule 6/Path — capitalize Path even when the param is untyped.

# BEFORE
Args:
    path (str): The file to read.
# AFTER
Args:
    path (Path): The file to read.

Edge cases & exceptions

• A Raises: that IS the contract stays. If a function's documented job is to

raise on bad input (e.g. divide raising ValueError when the divisor is zero), keep Raises:. The rule omits reflexive raises (impossible-scenario guards), not contractual ones.

• Untyped parameters still get a type in the docstring. If the signature is

parse_config(path) with no annotation but the function opens a file, document it as path (Path). The docstring carries the intended type even when the signature omits it.

• -> Any returns are documented, with Any capitalized: (Any): .... Only a

-> None return drops the Returns: section.

• tuple as a literal return shape vs. multiple values. If the function genuinely

returns one tuple object that callers treat as a unit, a single entry is fine — but the common case (returning "the min and the max") is two named entries.

• Single-line docstrings ("""Return the cached value.""") are valid and

preferred for trivial functions and all test functions; don't expand them into multi-section blocks.

• Mutable-default params still document the parameter normally; the docstring

never mentions the default regardless of mutability.

Do / Don't

• Never write Returns:\n dict:. Always write Returns:\n (dict):.
• Never write Calculates/Returns/Fetches. Always start with the bare verb.
• Never echo a default value in an Args description. Always describe behavior only.
• Never write Optional[X] or Union[X, Y]. Always use X | None / X | Y.
• Never write List/Dict/Tuple. Always lowercase list/dict/tuple.
• Never collapse two return values into (tuple):. Always name each value.
• Never add Raises: for a guard the caller can't trigger. Always omit it unless

the raise is part of the contract.

• Never document self/cls. Always start Args at the first real parameter.

Common mistakes

• Emitting standard Google style (bare bool: return) because that's the base's

default — the house variant parenthesizes it.

• Writing Returns:\n None for a -> None function instead of omitting the

section entirely.

• Adding an empty Args: header to a zero-parameter function.
• Carrying Defaults to N into the Args text — the single most common slip.
• Using Optional[int] for a int | None return, or List[str] for list.
• Forgetting , optional on a parameter that has a default in the signature.

Quick checklist

• ] Summary starts with a bare imperative verb, ends with a period.
• ] Every return type is wrapped in ( ); multiple values are named separately.
• ] No Args description states a default value.
• ] Optional params carry , optional inside the type parens.
• ] Builtins are lowercase; unions use |; Any/Path/None capitalized.
• ] Returns:/Args:/Raises: omitted when empty or non-contractual.
• ] self/cls not documented.