Skip to content

extra-yields-in-docstring

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

Docstring has a Yields section but the function does not yield

What it detects

This rule flags functions and methods that have a Yields: section but no yield or yield from statements in their body. The check is scope-aware — yields inside nested functions or classes are not counted.

Why is this a problem?

A Yields: section on a non-generator function misleads callers into treating the function as an iterator. After a refactor that replaces yield with return or removes generator behaviour entirely, a leftover Yields: section creates confusion about the function's interface.

How to Fix

Remove the Yields: section or convert the function to a generator:

If the function was refactored from a generator to a regular function, replace Yields: with Returns::

Returns:
    A list of processed items.

Example

def get_items(data: list) -> list:
    """Retrieve items from data.

    Yields:
        str: Each item from the data list.
    """
    return [str(item) for item in data]

def get_items(data: list) -> list:
    """Retrieve items from data.

    Returns:
        A list of stringified items.
    """
    return [str(item) for item in data]

Configuration

This rule is controlled by check-extra-yields (default: true). The forward check (missing-yields) is controlled independently by require-yields.

[tool.docvet.enrichment]
check-extra-yields = false

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 Yields: section