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. It checks only entries that match real signature parameters and have both a documented type and a usable annotation.

The comparison uses a syntax-only type-expression subset that covers common names, qualified names, subscriptions, tuples, unions, and stringized annotations. Unshadowed import aliases are normalized before comparison. Unparseable, unsupported, or ambiguous expressions are skipped instead of guessed.

Google, NumPy, and inline or paired reStructuredText types are supported. NumPy entries that document multiple names are checked once per matching parameter, so one shared type can produce a finding for only the names whose annotations differ. Findings are diagnostic-only because choosing between conflicting documentation and code requires human judgment.

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.
    """

For paired reStructuredText fields, a mismatch is reported on the type field rather than the value field:

docstring-convention = "rest"

def function(value: int):
    """Handle a value.

    :param value: Value to handle.
    :type value: str
    """

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

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 rather than compared speculatively:

docstring-convention = "google"

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

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

Options¶

None.