docparity 0.1.0__py3-none-any.whl

docparity/__init__.py

@@ -0,0 +1,7 @@
+"""docparity - detect drift between a function's docstring and its real signature."""
+
+from .scanner import scan_file, scan_source, Finding
+
+__all__ = ["scan_file", "scan_source", "Finding"]
+
+__version__ = "0.1.0"

docparity/cli.py

@@ -0,0 +1,77 @@
+"""docparity command-line interface."""
+
+from __future__ import annotations
+
+import argparse
+import sys
+from pathlib import Path
+
+from .scanner import scan_file
+
+
+def _iter_python_files(paths: list[str]) -> list[Path]:
+    files: list[Path] = []
+    for raw in paths:
+        p = Path(raw)
+        if p.is_dir():
+            files.extend(sorted(p.rglob("*.py")))
+        elif p.suffix == ".py":
+            files.append(p)
+    return files
+
+
+def build_parser() -> argparse.ArgumentParser:
+    parser = argparse.ArgumentParser(
+        prog="docparity",
+        description=(
+            "Detect drift between a function's docstring parameters and its "
+            "real signature (Google, NumPy, and Sphinx docstring styles)."
+        ),
+    )
+    parser.add_argument(
+        "paths", nargs="+", help="Python files or directories to scan"
+    )
+    parser.add_argument(
+        "--stale-only",
+        action="store_true",
+        help=(
+            "Only report stale documented parameters (removed/renamed in "
+            "the signature). Suppresses 'missing documentation' findings."
+        ),
+    )
+    return parser
+
+
+def main(argv: list[str] | None = None) -> int:
+    parser = build_parser()
+    args = parser.parse_args(argv)
+
+    files = _iter_python_files(args.paths)
+    if not files:
+        print("docparity: no Python files found", file=sys.stderr)
+        return 2
+
+    total = 0
+    had_error = False
+    for f in files:
+        try:
+            findings = scan_file(f)
+        except SyntaxError as exc:
+            print(f"docparity: {f}: syntax error: {exc}", file=sys.stderr)
+            had_error = True
+            continue
+
+        if args.stale_only:
+            findings = [fnd for fnd in findings if fnd.kind == "stale"]
+
+        for finding in findings:
+            print(str(finding))
+            total += 1
+
+    if had_error:
+        return 2
+    return 1 if total else 0
+
+
+if __name__ == "__main__":
+    raise SystemExit(main())

docparity/docstring_parser.py

@@ -0,0 +1,126 @@
+"""Extract documented parameter names from a docstring.
+
+Supports the three docstring styles used in practice:
+
+- Google style::
+
+    Args:
+        name (str): description
+        other: description
+
+- NumPy style::
+
+    Parameters
+    ----------
+    name : str
+        description
+
+- Sphinx / reST style::
+
+    :param name: description
+    :param str other: description
+
+Only the *names* of documented parameters are extracted -- docparity
+compares names against the real signature, it does not attempt to
+validate types or descriptions.
+"""
+
+from __future__ import annotations
+
+import re
+from dataclasses import dataclass, field
+
+
+@dataclass
+class ParsedDocstring:
+    documented_params: list[str] = field(default_factory=list)
+    has_params_section: bool = False
+
+
+_GOOGLE_SECTION_RE = re.compile(
+    r"^\s*(Args|Arguments|Parameters)\s*:\s*$", re.MULTILINE
+)
+_GOOGLE_PARAM_RE = re.compile(
+    r"^\s{2,}(\*{0,2}[A-Za-z_][A-Za-z0-9_]*)\s*(\(.*?\))?\s*:", re.MULTILINE
+)
+_GOOGLE_SECTION_STOP_RE = re.compile(
+    r"^\s*(Returns|Yields|Raises|Examples?|Note|Notes|Attributes)\s*:\s*$",
+    re.MULTILINE,
+)
+
+_NUMPY_SECTION_RE = re.compile(
+    r"^\s*Parameters\s*\n\s*-{3,}\s*$", re.MULTILINE
+)
+_NUMPY_PARAM_RE = re.compile(
+    r"^([A-Za-z_][A-Za-z0-9_]*(?:\s*,\s*[A-Za-z_][A-Za-z0-9_]*)*)\s*(:.*)?$"
+)
+_NUMPY_SECTION_STOP_RE = re.compile(
+    r"^\s*(Returns|Yields|Raises|Examples?|Notes?|Attributes)\s*\n\s*-{3,}\s*$",
+    re.MULTILINE,
+)
+
+_SPHINX_PARAM_RE = re.compile(
+    r"^\s*:param\s+(?:[A-Za-z_][A-Za-z0-9_.\[\]]*\s+)?\*{0,2}([A-Za-z_][A-Za-z0-9_]*)\s*:",
+    re.MULTILINE,
+)
+
+
+def _extract_google(doc: str) -> list[str] | None:
+    m = _GOOGLE_SECTION_RE.search(doc)
+    if not m:
+        return None
+    start = m.end()
+    stop_m = _GOOGLE_SECTION_STOP_RE.search(doc, pos=start)
+    end = stop_m.start() if stop_m else len(doc)
+    section = doc[start:end]
+    return [pm.group(1).lstrip("*") for pm in _GOOGLE_PARAM_RE.finditer(section)]
+
+
+def _extract_numpy(doc: str) -> list[str] | None:
+    m = _NUMPY_SECTION_RE.search(doc)
+    if not m:
+        return None
+    start = m.end()
+    stop_m = _NUMPY_SECTION_STOP_RE.search(doc, pos=start)
+    end = stop_m.start() if stop_m else len(doc)
+    section = doc[start:end]
+    names: list[str] = []
+    for raw_line in section.splitlines():
+        line = raw_line.strip()
+        if not line:
+            continue
+        # Only lines that look like "name : type" or "name" (not indented
+        # description text, which NumPy style indents further than the name).
+        indent = len(raw_line) - len(raw_line.lstrip(" "))
+        if indent > 4:
+            continue
+        pm = _NUMPY_PARAM_RE.match(line)
+        if pm:
+            for n in pm.group(1).split(","):
+                names.append(n.strip())
+    return names
+
+
+def _extract_sphinx(doc: str) -> list[str] | None:
+    names = [pm.group(1) for pm in _SPHINX_PARAM_RE.finditer(doc)]
+    return names or None
+
+
+def parse_docstring(doc: str | None) -> ParsedDocstring:
+    """Parse a docstring and return the set of documented parameter names.
+
+    Returns an empty, ``has_params_section=False`` result when no
+    recognizable parameter section is found. docparity intentionally does
+    not flag functions with no params section at all -- only functions
+    that already document *some* parameters but have drifted from the
+    real signature.
+    """
+    if not doc:
+        return ParsedDocstring()
+
+    for extractor in (_extract_google, _extract_numpy, _extract_sphinx):
+        names = extractor(doc)
+        if names is not None:
+            return ParsedDocstring(documented_params=names, has_params_section=True)
+
+    return ParsedDocstring()

docparity/scanner.py

@@ -0,0 +1,108 @@
+"""Scan Python source for docstring-vs-signature parameter drift."""
+
+from __future__ import annotations
+
+import ast
+from dataclasses import dataclass
+from pathlib import Path
+
+from .docstring_parser import parse_docstring
+
+# Parameters that are conventionally excluded from docstrings and should
+# never trigger an "undocumented parameter" finding.
+_IGNORED_PARAMS = {"self", "cls"}
+
+
+@dataclass
+class Finding:
+    file: str
+    line: int
+    function: str
+    kind: str  # "stale" (documented but not in signature) or "missing" (in
+    # signature but not documented)
+    param: str
+
+    def __str__(self) -> str:
+        if self.kind == "stale":
+            msg = f"docstring documents '{self.param}' which is not a parameter"
+        else:
+            msg = f"parameter '{self.param}' is not documented"
+        return f"{self.file}:{self.line}: {self.function}(): {msg}"
+
+
+def _real_params(node: ast.FunctionDef | ast.AsyncFunctionDef) -> list[str]:
+    args = node.args
+    names = []
+    for a in args.posonlyargs:
+        names.append(a.arg)
+    for a in args.args:
+        names.append(a.arg)
+    if args.vararg:
+        names.append(args.vararg.arg)
+    for a in args.kwonlyargs:
+        names.append(a.arg)
+    if args.kwarg:
+        names.append(args.kwarg.arg)
+    return [n for n in names if n not in _IGNORED_PARAMS]
+
+
+def _check_function(
+    node: ast.FunctionDef | ast.AsyncFunctionDef, filename: str
+) -> list[Finding]:
+    findings: list[Finding] = []
+    doc = ast.get_docstring(node)
+    parsed = parse_docstring(doc)
+    if not parsed.has_params_section:
+        # No documented parameter section -- nothing to compare, and
+        # flagging undocumented functions is out of scope (that is a
+        # coverage tool's job, not a drift tool's job).
+        return findings
+
+    real = _real_params(node)
+    real_set = set(real)
+    documented = parsed.documented_params
+    documented_set = set(documented)
+
+    for name in documented:
+        if name not in real_set:
+            findings.append(
+                Finding(
+                    file=filename,
+                    line=node.lineno,
+                    function=node.name,
+                    kind="stale",
+                    param=name,
+                )
+            )
+
+    for name in real:
+        if name not in documented_set:
+            findings.append(
+                Finding(
+                    file=filename,
+                    line=node.lineno,
+                    function=node.name,
+                    kind="missing",
+                    param=name,
+                )
+            )
+
+    return findings
+
+
+def scan_source(source: str, filename: str = "<string>") -> list[Finding]:
+    """Scan a source string and return a list of drift findings."""
+    tree = ast.parse(source, filename=filename)
+    findings: list[Finding] = []
+    for node in ast.walk(tree):
+        if isinstance(node, (ast.FunctionDef, ast.AsyncFunctionDef)):
+            findings.extend(_check_function(node, filename))
+    findings.sort(key=lambda f: (f.line, f.function, f.param))
+    return findings
+
+
+def scan_file(path: str | Path) -> list[Finding]:
+    """Scan a single Python file on disk and return a list of drift findings."""
+    path = Path(path)
+    source = path.read_text(encoding="utf-8")
+    return scan_source(source, filename=str(path))

docparity-0.1.0.dist-info/METADATA

@@ -0,0 +1,95 @@
+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

docparity-0.1.0.dist-info/RECORD

@@ -0,0 +1,9 @@
+docparity/__init__.py,sha256=Z2BuEgsGYUThYVxXPNIeCWcvlddsg1-dt_zM8Y14uz8,214
+docparity/cli.py,sha256=DP3POljVROSZPXS7KsjrX9fD3Eancc0taMFkqIrZNYM,1963
+docparity/docstring_parser.py,sha256=qIhmYs7fhd8YBibODOcrULRiuz6zf-1A9DEXmRiKD1s,3678
+docparity/scanner.py,sha256=I5SzZM330iCynvxn4RIHTLgX9GiP5S_qOztIF8SzQ-I,3332
+docparity-0.1.0.dist-info/METADATA,sha256=Ict1_r3y8uQBDb8ZnlJRnyGKo3MoQiyTEx87lQxJ8kI,3002
+docparity-0.1.0.dist-info/WHEEL,sha256=W3fkpkm7-wf9vBI5Z-7s0eWkeM-spu78I8Neb98DeEg,87
+docparity-0.1.0.dist-info/entry_points.txt,sha256=kKZZRagnBj1WPdE2-7whqaRZcJnMAxIJhQziSpsRfIc,49
+docparity-0.1.0.dist-info/licenses/LICENSE,sha256=xEsRvzJ-7Nbqa9ppe87ZOX9Xgmc2CJ7HOEFGRa0rcpU,1060
+docparity-0.1.0.dist-info/RECORD,,

docparity-0.1.0.dist-info/WHEEL

@@ -0,0 +1,4 @@
+Wheel-Version: 1.0
+Generator: hatchling 1.32.4
+Root-Is-Purelib: true
+Tag: py3-none-any

docparity-0.1.0.dist-info/entry_points.txt

@@ -0,0 +1,2 @@
+[console_scripts]
+docparity = docparity.cli:main

docparity-0.1.0.dist-info/licenses/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Jay
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.