parameter-type-mismatch (PDF703)¶

Part of the PDF rule category.

View source · View documentation source · Search issues

Fix is not available.

Rule is disabled if docstring-convention is none or pep257.

Rule is incompatible with PDF702.

What it does¶

Checks that parsed parameter docstring types conservatively match parameter annotations.

The comparison uses a small, syntax-only type-expression subset. Unparseable or ambiguous expressions are skipped instead of guessed. Only entries that match real signature parameters are checked, and NumPy entries that document multiple names are checked once per name.

Why is this useful?¶

Stale parameter type text can mislead readers when annotations have changed.

Ruff compatibility¶

None.

Examples¶

PDF703 reports docstring parameter types that do not match annotations:

docstring-convention = "google"

def function(value: int, timeout: float):
    """Connect to the service.

    Args:
        value (str): Endpoint identifier.
        timeout (float): Timeout in seconds.
    """

PDF703: Line 5: Function parameter 'value' docstring type does not match the annotation

Matching parameter types are accepted, including stringized annotations and union expressions:

docstring-convention = "google"

def function(value: "list[str | None]"):
    """Handle values.

    Args:
        value (list[str | None]): Values to handle.
    """

NumPy entries that document multiple names are checked for each matching signature parameter:

docstring-convention = "numpy"

def function(x: int, y: str):
    """Handle coordinates.

    Parameters
    ----------
    x, y : int
        Coordinate values.
    """

PDF703: Line 6: Function parameter 'y' docstring type does not match the annotation

Unparseable type expressions are ignored by mismatch checks:

docstring-convention = "google"

def function(value: "list["):
    """Handle values.

    Args:
        value (Factory[int]()): Values to handle.
    """

Options¶

None.