Skip to content

PyCodeCommenter — Python Docstring Generator & Validator

Keep Python docstrings accurate as your code evolves.

Deterministic docstring generation and validation for production Python. No AI guesswork by default — just reliable, rule-based inference that syncs your docs with your AST. AI drafting is opt-in.

What is PyCodeCommenter?

PyCodeCommenter is an open-source Python tool that:

  1. Writes docstrings from what your code proves — names, types, defaults, raise conditions, boolean checks — keeping anything you already wrote (including a # comment above the function) and marking what only a person can say.
  2. Drafts the rest with AI, if you opt in (--ai-draft), labelling every drafted line (AI-drafted, unreviewed) — then pycodecommenter review lets you accept, edit or skip each one.
  3. Validates existing docstrings against real function signatures across six check categories.
  4. Measures documentation coverage per file and across entire projects, with JSON output for CI.

Install with: pip install pycodecommenter · Requires Python 3.10+

The Problem & The Solution

Before PyCodeCommenter: Code changes, but docstrings don't. 

def process_data(items, strict=False):
    return items  # 'strict' isn't documented anywhere

After PyCodeCommenter: Run $ pycodecommenter generate <path/to/your_file.py> to sync the skeleton — names, types and defaults, always accurate because they're extracted, not guessed. What the tool can't extract (what process_data actually means) is left as an explicit TODO(pycodecommenter): describe marker, not a guessed sentence (real output): 

def process_data(items, strict=False):
    """Process data.

    Args:
        items (Any): TODO(pycodecommenter): describe.
        strict (Any): TODO(pycodecommenter): describe. (default: False)

    Returns:
        Any: TODO(pycodecommenter): describe
    """
    return items

Add --ai-draft to have those gaps drafted (each line labelled (AI-drafted, unreviewed)), then pycodecommenter review to accept, edit or skip each drafted line.

1. Install

pip install pycodecommenter

2. Run

Preview the changes PyCodeCommenter will make to your project without writing to disk:

pycodecommenter generate <path/to/your_file.py> --dry-run

Ready to apply? Write docstrings directly into the file:

pycodecommenter generate <path/to/your_file.py> --inplace

Validate and get a JSON report:

pycodecommenter validate <path/to/your_file.py> --output-format json

3. Explore the Documentation

▸ Getting Started Step-by-step from install to your first generate, validate, and coverage run. ✓ Validation Checks All checks — severity levels, violation examples, and how to fix each one. ⟲ Recipes & CI Pre-commit hooks, GitHub Actions, and coverage gating patterns. ›_ CLI Reference Every flag and argument for generate, validate, and coverage — derived directly from the source. { } Python API Use PyCodeCommenter programmatically: PyCodeCommenter, DocstringValidator, CoverageAnalyzer. ? FAQ Common questions answered directly from the source code.

Key Facts

Property Value
PyPI package pycodecommenter
Import name PyCodeCommenter
Python support 3.10, 3.11, 3.12, 3.13
Output docstring style Google for new docstrings; existing NumPy/Sphinx docstrings keep their style
Input parsing Google (full), Sphinx (full), NumPy (full)
AI / LLM dependency None by default (deterministic); optional --ai-draft via a free hosted service or your own Gemini/OpenAI/Anthropic/DeepSeek key
Runtime dependencies ruamel.yaml (config), libcst (patching)
License MIT
Version 2.6.1