Docstring Style Guide

All Python code in this project uses Google-style docstrings.

Module-Level Docstring

Every .py file starts with a module docstring before any imports:

"""WebSocket client for paginated bioreactor data fetching."""

import json
import os
...

Function Docstring

Minimum used for every public function:

def save_actual_data_batch(df: pd.DataFrame) -> None:
    """Persist a batch of sensor readings to the prediction database.

    Args:
        df (pd.DataFrame): Sensor readings with a ``time`` column in ISO 8601
            format and one column per parameter.

    Returns:
        None
    """

Full docstring for complex or important functions:

async def fetch_from_websocket(
    cfg: dict,
    experiment_ids: list = None,
    experiment_list_only: bool = False,
) -> pd.DataFrame:
    """Fetch experiment data from the WebSocket in time-paginated batches.

    Uses the last received ``time`` value as a cursor in each subsequent
    query to avoid loading the full dataset into memory at once.

    Args:
        cfg (dict): Configuration dict. Must include:

            - ``cfg["websocket"]["uri"]`` — server URI
            - ``cfg["websocket"]["base_query"]`` — SQL without WHERE clause

        experiment_ids (list, optional): IDs to filter by. Defaults to None
            (fetches all experiments).
        experiment_list_only (bool): If True, returns only ``experiment_id``
            and ``entity`` columns. Defaults to False.

    Returns:
        pd.DataFrame: All fetched rows. Empty DataFrame if no data found.

    Raises:
        websockets.exceptions.ConnectionClosedError: If the connection drops
            mid-fetch.
        KeyError: If required keys are missing from ``cfg``.

    Example:
        >>> df = asyncio.run(fetch_from_websocket(cfg, ["exp_001"]))
        >>> print(df.shape)
        (1200, 5)
    """

Class Docstring

class ModelManager:
    """Registry and lifecycle manager for all ML model instances.

    Loads models from disk at startup and provides a unified interface for
    retrieving, reloading, and switching between models at runtime.

    Attributes:
        models (dict[str, BaseModel]): Loaded models keyed by name.
        config (dict): The ``models`` section of the application config.

    Example:
        >>> manager = ModelManager(cfg)
        >>> result = manager.get("lstm").predict(features)
    """

    def __init__(self, config: dict) -> None:
        """Initialise the manager and load all configured models.

        Args:
            config (dict): Full application config. Only ``models`` key used.
        """

Docstring Sections

Section	When to use
Args	Every parameter except self/cls
Returns	Any non-None return value
Raises	Exceptions the caller should handle
Attributes	Class-level attributes (in the class docstring)
Example	Short runnable snippet
Note	Important caveats or non-obvious behaviour
Yields	Generator functions — replaces Returns