6 exercises — identify and write Google-style, NumPy-style, and Sphinx-style Python docstrings in real engineering contexts.
0 / 6 completed
1 / 6
What style is this Python docstring?
```python
def parse_date(date_str):
"""Parse a date string into a datetime object.
Args:
date_str (str): Date string in ISO 8601 format (YYYY-MM-DD).
Returns:
datetime: Parsed datetime object.
Raises:
ValueError: If the string does not match ISO 8601 format.
"""
```
Google style docstring — recognisable by its indented sections with a colon-terminated header.
Google style sections: • Args: — list of parameters (name (type): description) • Returns: — return type and description • Raises: — exceptions with conditions • Note:, Example:, Yields: — optional sections
When to use Google style: • Most popular in general Python projects • Used by Google, many open-source projects • Works well with Sphinx via the sphinx.ext.napoleon extension • Preferred by Black, isort, and most Python style guides
Linted/generated by: Google's own styleguide, pylint, pydocstyle, mkdocs.
2 / 6
A colleague shows you this docstring. What style is it?
```python
def compute_rmse(y_true, y_pred):
"""
Compute root mean squared error.
Parameters
----------
y_true : array-like of shape (n_samples,)
Ground truth target values.
y_pred : array-like of shape (n_samples,)
Estimated target values.
Returns
-------
float
RMSE value.
"""
```
NumPy style — recognisable by its underlined section headers and the "name : type" annotation pattern.
NumPy style characteristics: • Section headers underlined with dashes: Parameters\n---------- • Parameter format: name : type (space-colon-space) • Type annotations on their own "name : type" line, description indented below • Common sections: Parameters, Returns, Raises, See Also, Notes, References, Examples
When to use NumPy style: • Data science and scientific computing projects • numpy, scipy, pandas, scikit-learn all use this style • Projects where detailed mathematical documentation is needed • When your audience is data scientists (familiar with numpy docs)
Tool support: Sphinx with sphinx.ext.napoleon, numpydoc Sphinx extension.
3 / 6
What style is this docstring?
```python
def connect(host, port=5432):
"""
Connect to a PostgreSQL database.
:param host: Hostname or IP of the database server.
:type host: str
:param port: Port number. Defaults to 5432.
:type port: int
:returns: Active database connection.
:rtype: psycopg2.extensions.connection
:raises ConnectionError: If the server is unreachable.
"""
```
Sphinx / reStructuredText (reST) style — recognisable by inline directives starting with a colon: :param:, :type:, :returns:, :rtype:, :raises:.
Sphinx reST style characteristics: • All annotations inline, not grouped into sections • Separates the parameter description (:param:) from its type (:type:) • :returns: for description, :rtype: for the return type • Oldest of the three styles; native to Sphinx documentation system
When to use Sphinx style: • Projects using Sphinx for documentation (https://www.sphinx-doc.org) • Django, older Python packages, projects targeting Sphinx HTML docs • Mixed into many legacy codebases
Comparison: | Style | Separator | Type notation | |---|---|---| | Google | colon-header sections | (type) in parentheses | | NumPy | underlined sections | name : type | | Sphinx | :param:/:type: inline | :type name: |
4 / 6
In a Google-style docstring, how should you document a function that yields values (a generator)?
Yields: section — used in Google-style (and NumPy-style) docstrings for generator functions.
Example:
def read_lines(filepath):
"""Read lines from a file lazily.
Args:
filepath (str): Path to the text file.
Yields:
str: Each line from the file, stripped of trailing newline.
Raises:
FileNotFoundError: If the file does not exist.
"""
When a function is a generator (uses yield), document with Yields: not Returns: • Returns: — for functions that return a value with return • Yields: — for generator functions that use yield • The type in Yields: should be the type of each yielded value (e.g. str, not Generator[str, None, None])
This distinction matters because generators are iterable objects, not single return values — callers iterate them with a for loop or next().
5 / 6
Which Python docstring first line follows the PEP 257 style convention?
Option B follows PEP 257 conventions:
PEP 257 rules for one-liners and multi-line docstrings: • First line: brief summary — imperative mood ("Validates", "Computes", "Returns", "Converts") • First line should fit on ONE line — detailed description goes after a blank line • First line ends with a period • Multi-line: blank line after summary, then extended description, then sections • Closing quotes on their own line for multi-line docstrings
PEP 257 examples: Good one-liner: """Return the absolute value of x.""" Good multi-line:
"""Validate an email address.
Checks format against RFC 5321, then verifies the domain
via DNS MX record lookup.
"""
Options A and C: "This function..." and "Function that..." — do NOT start with "This function"; PEP 257 says to use imperative mood without preamble. Option D: no capitalisation, no period — violates PEP 257.
6 / 6
You are joining a data science team that uses scikit-learn and pandas. Which docstring style should you use to match the existing codebase?
NumPy style — the dominant convention in the scientific Python ecosystem.
Why NumPy style fits data science: • scikit-learn, numpy, scipy, pandas all use NumPy style • Data scientists recognise it immediately from reading library documentation • Well-suited to complex parameter types (array-like, ndarray, DataFrame) • The underlined section headers are easy to scan when there are many parameters
Practical rule for choosing docstring style: • Check the existing codebase — consistency beats personal preference • Data science (numpy/pandas ecosystem) → NumPy style • General Python (Django, Flask, FastAPI) → Google style • Sphinx documentation sites → Sphinx/reST style • Greenfield project → pick one and add a linter rule (pydocstyle/flake8-docstrings)
Most AI code assistants (GitHub Copilot, Cursor) can generate any style if you write one correctly-styled example and tell the assistant which convention to follow.