docparity

Detects drift between a function's docstring parameters and its real signature -- the classic case of renaming or removing a parameter and forgetting to update the docstring, so the documentation quietly lies to the next reader (or to an LLM/IDE that trusts it).

Supports Google, NumPy, and Sphinx (:param:) docstring styles. Zero runtime dependencies, pure ast-based static analysis.

Why

Docstrings drift silently:

def charge_card(amount, currency):
    """Charge a card.

    Args:
        amount (float): the amount to charge
        card_token (str): the card token to charge   # <- renamed to `currency`, doc never updated
    """

Nothing catches this today. Type checkers don't read docstrings. Linters that check docstring presence (pydocstyle, flake8-docstrings) don't check that documented parameter names still match the signature. The result is stale documentation that misleads humans, and misleads LLM coding assistants and IDEs that surface docstrings as ground truth.

Install

pip install docparity

Usage

docparity src/                 # scan a directory recursively
docparity mymodule.py          # scan a single file
docparity --stale-only src/    # only report renamed/removed params, not missing docs

Exit codes: 0 clean, 1 findings reported, 2 usage/syntax error.

What it checks (v0.1)

1. Stale documented parameter -- the docstring documents a parameter name that no longer exists in the real signature (renamed or removed).
2. Missing documentation for a real parameter -- the function already has a params section, and a real parameter isn't in it (added to the signature, forgotten in the docs).

docparity only checks functions that already document at least one parameter. It never asks you to add documentation to an undocumented function -- that's a coverage tool's job, not a drift tool's job. This keeps false positives near zero.

Library usage

from docparity import scan_file

findings = scan_file("mymodule.py")
for f in findings:
    print(f)

See docs/USAGE.md for more, and DETAILS.md for design rationale and scope boundaries.

License

MIT