missing-warns

Part of: Enrichment Check

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

Function calls warnings.warn() but has no Warns section

What it detects

This rule flags functions that call warnings.warn() but have no Warns: section in their docstring.

Why is this a problem?

Users of the function don't know which warnings to expect or suppress. Undocumented warnings create noisy log output in production and make it impossible to write targeted warning filters. Callers need to know the warning category and trigger condition to handle them appropriately.

Example

ViolationFix

def connect(host: str, timeout: int = 30) -> Connection:
    """Connect to the remote server.

    Args:
        host: Server hostname.
        timeout: Connection timeout in seconds.

    Returns:
        Active connection object.
    """
    if timeout < 5:
        warnings.warn(
            "Very short timeout may cause failures",
            stacklevel=2,
        )
    return Connection(host, timeout)

def connect(host: str, timeout: int = 30) -> Connection:
    """Connect to the remote server.

    Args:
        host: Server hostname.
        timeout: Connection timeout in seconds.

    Returns:
        Active connection object.

    Warns:
        UserWarning: If timeout is less than 5 seconds.
    """
    if timeout < 5:
        warnings.warn(
            "Very short timeout may cause failures",
            stacklevel=2,
        )
    return Connection(host, timeout)