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.