Metadata-Version: 2.5
Name: docparity
Version: 0.1.0
Summary: Detects drift between a function's docstring parameters and its real signature (Google, NumPy, and Sphinx styles).
Author: Jay
License: MIT
License-File: LICENSE
Keywords: code-quality,docstring,documentation,linter,static-analysis
Classifier: Development Status :: 4 - Beta
Classifier: Intended Audience :: Developers
Classifier: License :: OSI Approved :: MIT License
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3.10
Classifier: Topic :: Documentation
Classifier: Topic :: Software Development :: Quality Assurance
Requires-Python: >=3.10
Provides-Extra: dev
Requires-Dist: pytest>=8.0; extra == 'dev'
Description-Content-Type: text/markdown

# 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:

```python
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

```bash
pip install docparity
```

## Usage

```bash
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

```python
from docparity import scan_file

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

See [docs/USAGE.md](docs/USAGE.md) for more, and [DETAILS.md](DETAILS.md)
for design rationale and scope boundaries.

## License

MIT
