missing-raises

Part of: Enrichment Check

Check	enrichment
Category	required
Applies to	functions, methods
Since	v1.0.0

Function raises exceptions but has no Raises section

What it detects

This rule flags functions and methods that contain raise statements in their body but have no Raises: section in their docstring.

Why is this a problem?

Callers of the function don't know which exceptions to expect. Without a documented Raises: section, downstream code can't write correct try/except blocks, leading to unhandled exceptions in production. API documentation generated by mkdocstrings will also lack exception information.

Example

ViolationFix

def parse_config(path: str) -> dict:
    """Parse a TOML configuration file.

    Args:
        path: Path to the config file.

    Returns:
        Parsed configuration dictionary.
    """
    if not path.endswith(".toml"):
        raise ValueError(f"Expected .toml file, got: {path}")
    with open(path) as f:
        return toml.load(f)

def parse_config(path: str) -> dict:
    """Parse a TOML configuration file.

    Args:
        path: Path to the config file.

    Returns:
        Parsed configuration dictionary.

    Raises:
        ValueError: If the file does not have a .toml extension.
    """
    if not path.endswith(".toml"):
        raise ValueError(f"Expected .toml file, got: {path}")
    with open(path) as f:
        return toml.load(f)