Skip to content

extra-raises-in-docstring

Part of: Enrichment Check
Check enrichment
Category recommended
Applies to functions, methods
Since v1.16.0

Docstring documents exceptions not raised in the function body

What it detects

This rule flags functions and methods whose Raises: section documents exception types that are not actually raised in the function body. It compares documented exception names against raise statements found via scope-aware AST walking.

Why is this a problem?

Documenting exceptions that are never raised misleads callers into writing unnecessary try/except blocks. After a refactor that removes or changes exception paths, leftover Raises: entries create false expectations about error handling.

How to Fix

Remove the documented exception from the Raises: section, or add the corresponding raise statement to the function body:

Raises:
    ValueError: If the input is invalid.

Only document exceptions that the function directly raises. Exceptions from called functions should be documented in their docstrings.

Example

def parse(text: str) -> dict:
    """Parse the input text.

    Raises:
        ValueError: If the text is malformed.
        TypeError: If the input is not a string.
    """
    return json.loads(text)

def parse(text: str) -> dict:
    """Parse the input text.

    Raises:
        ValueError: If the text is malformed.
    """
    if not isinstance(text, str):
        raise ValueError("expected string input")
    return json.loads(text)

Configuration

This rule is opt-in and disabled by default due to false positives on propagated exceptions (exceptions raised by callees but documented in the caller's Raises: section). Enable it with:

[tool.docvet.enrichment]
check-extra-raises = true

The forward check (missing-raises) is controlled independently by require-raises and remains enabled by default.

Exceptions

This rule is automatically skipped when:

  • The function is @abstractmethod (interface contract documentation)
  • The function body is a stub (pass, ..., or raise NotImplementedError)
  • The symbol is a class, module, or other non-function type
  • The docstring has no Raises: section