Python API Reference¶

PyCodeCommenter exposes a clean Python API for all three of its core capabilities — generation, validation, and coverage analysis. This page documents every public class exported from the package.

All classes listed here are importable directly from the top-level package:

from PyCodeCommenter import (
    PyCodeCommenter,
    DocstringValidator,
    ValidationReport,
    ValidationIssue,
    Severity,
    CoverageAnalyzer,
    FileCoverage,
    ProjectCoverage,
    TypeAnalyzer,
    DocstringParser,
)

PyCodeCommenter¶

The main class for loading Python code, generating docstrings, and patching the source. All methods return self or a computed value, enabling a fluent interface.

Constructor¶

PyCodeCommenter()

No parameters. After construction, call from_string() or from_file() to load code.

Attribute	Type	Description
`code`	`str`	The raw source code (set by `from_string` / `from_file`)
`parsed_code`	`ast.Module` or `None`	The parsed AST; `None` if parsing failed
`comments`	`list`	Populated by `generate_docstrings()`
`tokenized_comments`	`list`	Raw comment tokens extracted during load
`type_analyzer`	`TypeAnalyzer`	Instance used internally for type inference

Methods¶

from_string(code_string) -> PyCodeCommenter¶

Load code from a string. Returns self so calls can be chained.

Parameters:

Parameter	Type	Description
`code_string`	`str`	A string containing valid Python source code

Returns: PyCodeCommenter (the same instance)

Raises: Does not raise. Logs a warning on empty input; logs an error on SyntaxError and sets parsed_code = None.

Example:

from PyCodeCommenter import PyCodeCommenter

code = """
def greet(name: str) -> str:
    return f"Hello, {name}"
"""

commenter = PyCodeCommenter().from_string(code)

from_file(file_path) -> PyCodeCommenter¶

Load code from a file on disk. Returns self.

Parameters:

Parameter	Type	Description
`file_path`	`str`	Absolute or relative path to a Python `.py` file

Returns: PyCodeCommenter (the same instance)

Raises: Does not raise. Logs an error and sets parsed_code = None on FileNotFoundError, IOError, or SyntaxError.

Example:

commenter = PyCodeCommenter().from_file("src/api.py")
if not commenter.parsed_code:
    print("Could not parse the file")

generate_docstrings() -> list¶

Walk the AST and generate docstring strings for every function and class. Returns a flat list of generated docstring strings (one per node). Does not modify the source.

Parameters: None

Returns: list of str — one entry per function/class found (including module docstring if present)

Example:

commenter = PyCodeCommenter().from_string(code)
docstrings = commenter.generate_docstrings()
for doc in docstrings:
    print(doc)

get_patched_code() -> str¶

Return the full source code with all docstrings inserted or replaced. If a function or class already has a docstring, it is updated (the existing summary, parameter descriptions, and return text are preserved). New docstrings are inserted at the correct indentation level.

Parameters: None

Returns: str — the complete patched source code

Example:

commenter = PyCodeCommenter().from_string(code)
patched = commenter.get_patched_code()
print(patched)

# Write to disk yourself:
with open("output.py", "w", encoding="utf-8") as f:
    f.write(patched)

validate(strict=False) -> ValidationReport¶

Validate all docstrings in the loaded code against the actual AST signatures. Returns a full ValidationReport.

Parameters:

Parameter	Type	Default	Description
`strict`	`bool`	`False`	Parameter is accepted but does not yet affect behaviour. Reserved for future use

Returns: ValidationReport

Raises: Does not raise. Returns an empty ValidationReport if parsed_code is None.

Example:

import sys
from PyCodeCommenter import PyCodeCommenter

commenter = PyCodeCommenter().from_file("src/api.py")
report = commenter.validate()
report.print_summary()

if report.stats.errors > 0:
    sys.exit(1)

check_coverage() -> FileCoverage¶

Calculate documentation coverage for the loaded code.

Parameters: None

Returns: FileCoverage — coverage stats for the in-memory code (path is set to "<string>")

Example:

commenter = PyCodeCommenter().from_string(code)
coverage = commenter.check_coverage()
print(f"{coverage.coverage_percentage:.1f}%")
print(f"Functions: {coverage.documented_functions}/{coverage.total_functions}")
print(f"Classes:   {coverage.documented_classes}/{coverage.total_classes}")

DocstringValidator¶

Validates an existing Python source file or code string for documentation quality.

Constructor¶

DocstringValidator(code_string=None, file_path=None)

Provide exactly one of the two parameters.

Parameter	Type	Default	Description
`code_string`	`str` or `None`	`None`	Python source code as a string
`file_path`	`str` or `None`	`None`	Path to a `.py` file to read and validate

If both are provided, code_string takes precedence.

Example:

from PyCodeCommenter import DocstringValidator

# From string
validator = DocstringValidator(code_string=my_code)

# From file
validator = DocstringValidator(file_path="src/models.py")

Methods¶

validate_all() -> ValidationReport¶

Run all six validation checks across all functions and classes in the parsed code.

Returns: ValidationReport

Example:

validator = DocstringValidator(file_path="src/models.py")
report = validator.validate_all()
report.print_summary()

check_signature_match(func_node, docstring, location) -> List[ValidationIssue]¶

Check that every parameter in the function signature is documented and every documented parameter exists in the signature.

Parameters:

Parameter	Type	Description
`func_node`	`ast.FunctionDef` or `ast.AsyncFunctionDef`	The function AST node
`docstring`	`str`	The raw docstring text
`location`	`str`	Location string for issue reporting, e.g. `"file.py:10:my_func"`