Writing Docstrings

source:
  python:
    docstring_style: "google"

def connect(host: str, port: int = 8080, timeout: float = 30.0) -> Connection:
    """Establish a connection to the remote server.
 
    Opens a TCP connection using the specified host and port. The connection
    will be kept alive until explicitly closed or the timeout is reached.
 
    Args:
        host: The hostname or IP address to connect to.
        port: The port number. Defaults to 8080.
        timeout: Maximum time in seconds to wait for the connection.
 
    Returns:
        A Connection object representing the active connection.
 
    Raises:
        ConnectionError: If the server is unreachable.
        ValueError: If the host string is empty.
 
    Examples:
        >>> conn = connect("localhost")
        >>> conn.is_alive()
        True
 
    Notes:
        This function does not support Unix domain sockets.
    """

source:
  python:
    docstring_style: "numpy"

def connect(host: str, port: int = 8080) -> Connection:
    """Establish a connection to the remote server.
 
    Parameters
    ----------
    host : str
        The hostname or IP address.
    port : int, optional
        The port number, by default 8080.
 
    Returns
    -------
    Connection
        The active connection object.
 
    Raises
    ------
    ConnectionError
        If the server is unreachable.
    """

def train(data: Dataset, epochs: int = 10, lr: float = 0.001) -> Model:
    """Train a model on the given dataset.
 
    Args:
        data: The training dataset.
        epochs: Number of training epochs.
        lr: Learning rate for the optimizer.
    """

def load(path: str) -> dict:
    """Load configuration from a YAML file.
 
    Returns:
        A dictionary containing the parsed configuration.
    """

def parse(text: str) -> AST:
    """Parse source code into an AST.
 
    Raises:
        SyntaxError: If the source code is invalid.
        FileNotFoundError: If the source file does not exist.
    """

def add(a: int, b: int) -> int:
    """Add two numbers.
 
    Examples:
        >>> add(2, 3)
        5
        >>> add(-1, 1)
        0
    """

def encrypt(data: bytes, key: bytes) -> bytes:
    """Encrypt data using AES-256-GCM.
 
    Notes:
        The nonce is generated randomly and prepended to the ciphertext.
        This function is not suitable for encrypting data larger than 2 GiB.
    """

# Type from signature (preferred)
def greet(name: str) -> str:
    """Greet a user.
 
    Args:
        name: The user's name.
    """
 
# Type from docstring (fallback)
def greet(name):
    """Greet a user.
 
    Args:
        name (str): The user's name.
 
    Returns:
        str: A greeting message.
    """

class User:
    @property
    def full_name(self) -> str:
        """The user's full name, computed from first and last name."""
        return f"{self.first} {self.last}"

class MathUtils:
    @staticmethod
    def clamp(value: float, low: float, high: float) -> float:
        """Clamp a value to a range.
 
        Args:
            value: The value to clamp.
            low: Minimum bound.
            high: Maximum bound.
        """

class Config:
    @classmethod
    def from_file(cls, path: str) -> "Config":
        """Load configuration from a file.
 
        Args:
            path: Path to the configuration file.
        """

class EventHandler:
    @retry(max_attempts=3)
    def handle(self, event: Event) -> None:
        """Handle an incoming event with automatic retry."""

def log(message: str, *args: Any, **kwargs: Any) -> None:
    """Log a message with optional formatting arguments.
 
    Args:
        message: The log message template.
        *args: Positional arguments for string formatting.
        **kwargs: Additional keyword arguments passed to the logger.
    """

__all__ = ["PublicClass", "public_function"]
 
class PublicClass:
    """This will be documented."""
 
class _InternalHelper:
    """This is private by convention but would be documented without __all__."""
 
def public_function():
    """This will be documented."""
 
def helper():
    """This will NOT be documented because it's not in __all__."""

class Model:
    """A machine learning model.
 
    The Model class supports nested configuration via inner classes.
    """
 
    class Config:
        """Model configuration.
 
        Args are defined as class variables with type annotations.
        """
        learning_rate: float = 0.001
        batch_size: int = 32
 
    class Callbacks:
        """Lifecycle callbacks for training."""
 
        def on_epoch_end(self, epoch: int, metrics: dict) -> None:
            """Called at the end of each training epoch.
 
            Args:
                epoch: The epoch number that just completed.
                metrics: Dictionary of metric names to values.
            """

DEFAULT_TIMEOUT: float = 30.0
MAX_RETRIES: int = 3
API_BASE_URL: str = "https://api.example.com"

VERSION = "1.0.0"          # documented (UPPER_CASE)
DEFAULT_PORT = 8080        # documented (UPPER_CASE)
_internal_cache = {}       # NOT documented (leading underscore)
some_config = "value"      # NOT documented (not UPPER_CASE)

class Server:
    """An HTTP server.
 
    Attributes are documented from annotated class-level assignments.
    """
    host: str = "localhost"
    port: int = 8080
    max_connections: int = 100

async def fetch(url: str, timeout: float = 10.0) -> Response:
    """Fetch a resource from the given URL.
 
    Args:
        url: The URL to fetch.
        timeout: Maximum time to wait in seconds.
 
    Returns:
        The HTTP response.
 
    Raises:
        TimeoutError: If the request exceeds the timeout.
    """

"""Connection management for the RPC framework.
 
This module provides connection pooling and lifecycle management
for RPC clients.
"""
 
__all__ = ["ConnectionPool", "DEFAULT_POOL_SIZE"]
 
DEFAULT_POOL_SIZE: int = 10
 
class ConnectionPool:
    """A thread-safe pool of reusable connections.
 
    The pool maintains a set of open connections and distributes them
    to callers on demand. Connections are returned to the pool when
    released.
 
    Examples:
        >>> pool = ConnectionPool("localhost", max_size=5)
        >>> async with pool.acquire() as conn:
        ...     await conn.execute("SELECT 1")
 
    Notes:
        The pool does not currently support connection health checks.
    """
 
    max_size: int = DEFAULT_POOL_SIZE
    timeout: float = 30.0
 
    class Stats:
        """Pool usage statistics."""
        active: int = 0
        idle: int = 0
 
    def __init__(self, host: str, port: int = 5432, max_size: int = 10) -> None:
        """Initialize the connection pool.
 
        Args:
            host: Database hostname.
            port: Database port.
            max_size: Maximum number of connections in the pool.
        """
 
    async def acquire(self, timeout: float | None = None) -> Connection:
        """Acquire a connection from the pool.
 
        Args:
            timeout: Maximum time to wait for a connection.
                If None, uses the pool's default timeout.
 
        Returns:
            An open database connection.
 
        Raises:
            PoolExhaustedError: If no connection is available within the timeout.
        """
 
    @property
    def size(self) -> int:
        """The current number of connections in the pool."""
 
    @classmethod
    def from_url(cls, url: str) -> "ConnectionPool":
        """Create a pool from a database URL.
 
        Args:
            url: A connection string like ``postgresql://host:port/db``.
        """
 
    @staticmethod
    def is_valid_url(url: str) -> bool:
        """Check whether a connection string is valid.
 
        Args:
            url: The connection string to validate.
        """