pycodecommenter 2.0.3__tar.gz → 2.1.0__tar.gz

pycodecommenter-2.1.0/.github/workflows/publish.yml

@@ -0,0 +1,33 @@
+name: Publish to PyPI
+
+on:
+  release:
+    types: [published]
+
+jobs:
+  pypi-publish:
+    name: Upload release to PyPI
+    runs-on: ubuntu-latest
+    environment:
+      name: pypi
+      url: https://pypi.org/p/pycodecommenter
+    permissions:
+      id-token: write  # IMPORTANT: this permission is mandatory for trusted publishing
+    steps:
+      - uses: actions/checkout@v4
+      
+      - name: Set up Python
+        uses: actions/setup-python@v5
+        with:
+          python-version: '3.x'
+      
+      - name: Install dependencies
+        run: |
+          python -m pip install --upgrade pip
+          pip install build
+      
+      - name: Build package
+        run: python -m build
+      
+      - name: Publish package distributions to PyPI
+        uses: pypa/gh-action-pypi-publish@release/v1

pycodecommenter-2.1.0/.gitignore

@@ -0,0 +1,56 @@
+# Python
+__pycache__/
+*.py[cod]
+*$py.class
+*.so
+.Python
+build/
+develop-eggs/
+dist/
+downloads/
+eggs/
+.eggs/
+lib/
+lib64/
+parts/
+sdist/
+var/
+wheels/
+share/python-wheels/
+*.egg-info/
+.installed.cfg
+*.egg
+MANIFEST
+
+# Environments
+.env
+.venv
+env/
+venv/
+ENV/
+env.bak/
+venv.bak/
+
+# Pytest
+.pytest_cache/
+.coverage
+htmlcov/
+
+# Local/Temp Files for PyCodeCommenter
+env_info.txt
+out.txt
+output.txt
+modern_output.txt
+modern_results.txt
+test_output.txt
+reproduction.py
+test_cst.txt
+main_output.txt
+out_*.txt
+verify_*.py
+verify_*.txt
+error.txt
+version_info.txt
+
+# VS Code
+.vscode/

pycodecommenter-2.1.0/CHANGELOG.md

@@ -0,0 +1,40 @@
+# Changelog
+
+All notable changes to PyCodeCommenter will be documented in this file.
+
+## [2.0.0] - 2026-01-25
+
+###  Major Release - Complete Rewrite
+
+#### Added
+- **Comprehensive Validation System** - 6 types of documentation checks
+- **Coverage Analysis** - Project-wide documentation metrics
+- **Modern Type Support** - PEP 604 unions, PEP 585 generics
+- **Async Function Support** - Full support for `async def`
+- **Multiple Export Formats** - JSON, Markdown, console output
+- **Smart Docstring Parsing** - Preserves existing documentation
+- **Structured AST Traversal** - NodeVisitor pattern for reliability
+- **Professional Reporting** - Actionable error messages with suggestions
+- **CI/CD Ready** - Easy integration with pipelines
+
+#### Changed
+- Replaced basic type inference with comprehensive `TypeAnalyzer`
+- Improved docstring generation with better templates
+- Enhanced error handling with proper logging
+- Better handling of edge cases and malformed code
+
+#### Fixed
+- Duplicate `_infer_type` methods consolidated
+- Brittle patching logic made robust
+- Import resolution issues
+- Unicode/encoding handling
+
+#### Breaking Changes
+- Minimum Python version: 3.8+
+- Some internal APIs changed (public API remains compatible)
+
+## [1.0.0] - Earlier Version
+
+- Basic docstring generation
+- Template-based descriptions
+- File and string input support

pycodecommenter-2.1.0/CONTRIBUTING.md

@@ -0,0 +1,29 @@
+# Contributing to PyCodeCommenter
+
+First off, thank you for considering contributing to PyCodeCommenter! It's people like you who make it a great tool for everyone.
+
+## How Can I Contribute?
+
+### Reporting Bugs
+*   Check the [Issues](https://github.com/AmosQuety/PyCodeCommenter/issues) to see if it has already been reported.
+*   If not, open a new issue. Include a clear title, a description of the problem, and steps to reproduce (like a small code snippet).
+
+### Proposing Enhancements
+*   Open an issue to discuss your idea before starting work.
+*   Explain why this feature would be useful and how it should work.
+
+### Pull Requests
+1.  Fork the repo and create your branch from `main`.
+2.  Follow the existing code style.
+3.  Add tests if you're adding new functionality.
+4.  Ensure all tests pass.
+5.  Update documentation (including `README.md`) if necessary.
+6.  Open a Pull Request with a clear description of your changes.
+
+## Code Style
+*   Use [black](https://github.com/psf/black) for formatting.
+*   Follow Google-style docstrings (since that's what we generate!).
+*   Maintain Python 3.8+ compatibility.
+
+## Need Help?
+Feel free to open a discussion or an issue if you have any questions!

pycodecommenter-2.1.0/Future Work/Future Release WorkPlan.txt

@@ -0,0 +1,15 @@
+v2.1.0 — Safety & Trust · Jun 10 → Jun 30
+This is the "stop scaring users" release. All four items are independent so you can ship them in any order.
+--dry-run and --backup first — they're the most urgent. Dry-run prints a unified diff to stdout. Backup simply does shutil.copy(path, path + ".bak") before any in-place write. Maybe 2 days each.
+Config loader next. Add a config.py module that walks up the directory tree looking for .pycodecommenter.yaml and loads it with ruamel.yaml. Wire the values to the existing hard-coded defaults. A week's work max.
+Smarter parameter inference is also v2.1 — see the dedicated audit prompt below.
+Test rewrite is ongoing across all phases but the baseline pass (assertions on critical paths) should land here.
+
+v2.2.0 — Accuracy & Output · Jul 1 → Aug 15
+This is the "be correct and be composable" release. Decorator awareness cleans up the false-positive noise. JSON output unlocks every downstream integration — make it a flag on both validate and coverage. The Sphinx :raises: fix is a targeted one-liner in validator.py.
+
+v3.0.0 — Safe, Configurable, Extensible · Aug 16 → Nov 1
+The big one. The merge algorithm is the hardest item in the entire roadmap — budget 3–4 weeks for it alone. The approach: parse the existing docstring into sections, generate fresh sections, then do a section-by-section merge where any section with human content that doesn't match the auto-generated template is preserved. Multi-style support travels alongside — once the generator is style-aware, NumPy and Sphinx become config flags.
+
+v3.1.0 — Integrations · Nov 2, 2026 → Mar 1, 2027
+VS Code extension, GitHub Action for PR automation, SARIF output. These all depend on the v3.0 foundation being solid. Don't start them until merge and JSON output are stable.

pycodecommenter-2.1.0/Future Work/v2.1.0 /342/200/224 Remaining Items (dry-run, backup, config loader, test rewrite).txt"

@@ -0,0 +1,143 @@
+# PyCodeCommenter — v2.1.0 Safety & Trust Implementation
+
+## MANDATORY FIRST STEP — READ BEFORE WRITING ANY CODE
+
+Before proposing or implementing anything, you must read and cross-check
+the following files. Do not assume anything about how they work. If a file
+does not exist, say so explicitly before continuing.
+
+Files to read in full:
+- PyCodeCommenter/cli.py
+- PyCodeCommenter/commenter.py
+- PyCodeCommenter/__init__.py
+- pyproject.toml
+- All existing test_*.py files at the project root
+
+For each file, confirm:
+1. The exact function/class names involved in the feature you are about to touch
+2. The exact argument names and defaults for the CLI subcommands
+3. Whether any config-loading code already exists anywhere (search for
+   "yaml", "config", "load", "settings" across all files before assuming
+   config is absent)
+4. What testing library is currently used and whether conftest.py exists
+
+Report your findings as a short inventory before writing a single line of code.
+
+---
+
+## Feature 1: --dry-run flag for `generate`
+
+### What to build
+Add a `--dry-run` flag to the `generate` CLI subcommand. When set:
+- Generate the patched code in memory (do not write to disk)
+- Print a unified diff between the original file content and the patched
+  content to stdout using Python's built-in `difflib.unified_diff`
+- Exit with code 0 if no changes would be made, code 1 if changes exist
+  (allows CI to detect undocumented files)
+
+### Constraints
+- The flag must be `--dry-run` (hyphenated), stored as `dry_run` in argparse
+- Do not modify any file on disk when --dry-run is active
+- The diff output must be human-readable (use `lineterm=""` in unified_diff)
+- Only touch cli.py and commenter.py. Do not touch validator.py, coverage.py,
+  or any test file for this feature.
+- If commenter.py's generate/patch flow writes to disk inside the class rather
+  than in cli.py, identify exactly where and adjust accordingly — do not guess.
+
+---
+
+## Feature 2: --backup flag for `generate`
+
+### What to build
+Add a `--backup` flag to the `generate` CLI subcommand. When set alongside
+`-i` / `--inplace`:
+- Before writing the patched file, copy the original to `{original_path}.bak`
+  using `shutil.copy2` (preserves metadata)
+- Print a confirmation line: `Backup saved: {path}.bak`
+- If the .bak file already exists, overwrite it (do not prompt)
+
+### Constraints
+- `--backup` has no effect unless `--inplace` is also set; if --backup is
+  passed without --inplace, print a warning and continue normally
+- Only touch cli.py. Do not touch commenter.py or any other module.
+- Use shutil.copy2, not shutil.copy or manual file reads.
+- Do not modify the behavior of --inplace in any way other than inserting
+  the backup step before the write.
+
+---
+
+## Feature 3: Config file loader
+
+### What to build
+Create a new file `PyCodeCommenter/config.py` containing a `load_config`
+function that:
+
+1. Accepts an optional `start_path: str | None = None` parameter (defaults
+   to `os.getcwd()` if None)
+2. Walks UP the directory tree from start_path looking for
+   `.pycodecommenter.yaml`
+3. Returns the parsed config as a plain Python dict on success
+4. Returns an empty dict `{}` if no config file is found anywhere in the tree
+5. Raises `ConfigError` (a custom exception defined in the same file) with
+   a clear message if the file is found but cannot be parsed
+
+The config dict must support these keys (with these exact names and types):
+
+style: str                    # "google" | "numpy" | "sphinx", default "google"
+validation:
+level: str                  # "strict" | "moderate" | "lenient", default "moderate"
+check_types: bool           # default true
+check_exceptions: bool      # default true
+coverage:
+threshold: float            # default 80.0
+fail_below: bool            # default true
+exclude:
+
+str                       # list of exclusion patterns, default []
+
+5. After loading raw YAML, validate the keys against the schema above.
+   Unknown keys should log a warning but not raise.
+6. Wire `load_config` into cli.py so that every subcommand loads config at
+   startup and passes relevant values to the underlying classes.
+
+### Constraints
+- Use `ruamel.yaml` for YAML parsing. If it is not in pyproject.toml,
+  add it to the [dependencies] section before implementing.
+- Do not use PyYAML — check pyproject.toml first to see what is available.
+- Do not modify commenter.py, validator.py, or coverage.py to accept config
+  directly — pass values through the existing constructor/method arguments
+  that already exist. If an argument does not exist, check before adding one.
+- The function must never crash on a missing file — only on a malformed one.
+
+---
+
+## Feature 4: Test suite rewrite
+
+### What to build
+Rewrite all existing `test_*.py` files at the project root to use proper
+pytest assertions. Do not delete any existing test file — rewrite each one
+in place.
+
+### Rules
+- Read every existing test_*.py file before touching any of them.
+- For each test that currently just prints or runs code without asserting,
+  add explicit `assert` statements that verify:
+  - The number of issues found matches an expected count
+  - The severity of each issue matches (use the actual Severity enum values
+    from validator.py — read the file to get exact names)
+  - The message text contains expected substrings where relevant
+- Do not change what is being tested — only add assertions to what already
+  runs.
+- If a test currently catches an exception silently, make it assert the
+  exception is raised using `pytest.raises`.
+- Add a `conftest.py` at the project root with any shared fixtures (e.g.,
+  a helper that creates a temporary Python file from a string).
+- Do not add new test cases in this pass — only harden existing ones.
+  New test cases belong in test_inference.py (already planned).
+
+### Constraints
+- Read validator.py's Severity enum and ValidationIssue dataclass before
+  writing any assertion — use the exact field names.
+- Read coverage.py's FileCoverage and ProjectCoverage before asserting
+  coverage values — use the exact attribute names.
+- Do not add imports that are not already available in the project.

pycodecommenter-2.1.0/Future Work/v2.2.0 /342/200/224 Accuracy & Output.txt"

@@ -0,0 +1,126 @@
+# PyCodeCommenter — v2.2.0 Accuracy & Output Implementation
+
+## MANDATORY FIRST STEP — READ BEFORE WRITING ANY CODE
+
+Before proposing or implementing anything, read the following files in full:
+- PyCodeCommenter/validator.py          (entire file)
+- PyCodeCommenter/commenter.py          (entire file)
+- PyCodeCommenter/cli.py                (entire file)
+- PyCodeCommenter/docstring_parser.py   (entire file)
+- PyCodeCommenter/__init__.py
+- pyproject.toml
+
+For each file confirm:
+1. The exact class and method names you will touch for each feature
+2. Whether any JSON output, decorator detection, or Sphinx raise handling
+   already exists anywhere — search before assuming it is absent
+3. The exact Severity enum values and ValidationIssue field names
+4. What arguments `DocstringValidator.__init__` and `validate()` currently
+   accept
+
+Report a short inventory of findings before writing any code.
+
+---
+
+## Feature 1: Decorator and method-type awareness in validator
+
+### What to build
+Update `DocstringValidator` in `validator.py` to detect and handle these
+decorator types:
+- `@property` — skip return-doc check on setter/deleter variants; getter
+  should still have a return doc
+- `@classmethod` — treat `cls` the same as `self` (already excluded from
+  param checks, but verify this is actually the case by reading the code)
+- `@staticmethod` — no `self`/`cls` at all; ensure the heuristic that
+  detects methods does not misfire on static methods with a non-self first arg
+
+### How to detect decorators
+Read `func_node.decorator_list` from the AST node. Each decorator is an
+`ast.Name` or `ast.Attribute`. Match on `.id` for simple decorators
+(`@property`, `@staticmethod`, `@classmethod`).
+
+### Constraints
+- Read the current method-detection heuristic in validator.py first and
+  document exactly what it does before changing it.
+- Do not change the public API of `DocstringValidator` — no new constructor
+  arguments.
+- Do not touch commenter.py, coverage.py, or cli.py.
+- Add test cases for each decorator type to `test_validation.py` (rewrite
+  it in place, do not create a new file).
+
+---
+
+## Feature 2: Structured JSON output for validate and coverage
+
+### What to build
+Add `--output-format` flag to both `validate` and `coverage` subcommands
+in cli.py. Accepted values: `text` (default, existing behavior) and `json`.
+
+When `--output-format json`:
+- For `validate`: serialize the ValidationReport to JSON and print to stdout.
+  The JSON shape must be:
+```json
+  {
+    "file": "<path>",
+    "stats": {
+      "total": 0,
+      "errors": 0,
+      "warnings": 0,
+      "info": 0,
+      "coverage_percentage": 0.0
+    },
+    "issues": [
+      {
+        "line": 0,
+        "severity": "ERROR|WARNING|INFO",
+        "check": "<check name>",
+        "message": "<message>"
+      }
+    ]
+  }
+```
+- For `coverage`: serialize ProjectCoverage to JSON. The shape must match
+  whatever `to_json()` already returns — read coverage.py first to confirm
+  this method exists and what it returns before adding anything.
+
+### Constraints
+- Use Python's built-in `json` module only — no third-party serializers.
+- If ValidationReport does not have a `to_dict()` method, add one to
+  validator.py. Read the full class first to check.
+- If ValidationIssue is a dataclass, use `dataclasses.asdict`. Verify this
+  before assuming it.
+- The Severity enum must serialize to its string name (e.g., `"ERROR"` not
+  `<Severity.ERROR: 1>`). Handle this explicitly.
+- Do not change text output behavior in any way — json mode is additive only.
+- Do not touch commenter.py or coverage.py beyond what is needed for
+  to_dict()/to_json() additions.
+
+---
+
+## Feature 3: Sphinx :raises: detection fix
+
+### What to build
+Update the exception documentation check in `validator.py` so that it
+recognises Sphinx-style raises syntax (`:raises ExcType:`) in addition to
+the existing Google-style (`Raises:` section header).
+
+### How to find the current check
+Search validator.py for the string `'Raises'` and `raises`. Read the full
+method that performs this check before touching it. Document exactly what
+substring/regex it currently uses.
+
+### What to change
+The check for whether a "Raises" section exists should match any of:
+- `Raises:` (Google style — already works, do not break it)
+- `:raises ` (Sphinx style — note the trailing space to avoid false matches)
+- `Raises\n` or `Raises\r\n` (bare header variant)
+
+Do this with a helper function `_has_raises_section(docstring: str) -> bool`
+added to validator.py. Replace all existing inline checks with calls to this
+helper.
+
+### Constraints
+- Read the entire exception-check method before writing the helper.
+- Do not use a third-party regex library — use the `re` module from stdlib.
+- Write one test case for Sphinx-style raises in `test_validation.py`.
+- Do not touch any other file.

pycodecommenter-2.1.0/Future Work/v3.0.0 /342/200/224 Safe, Configurable, Extensible.txt"

@@ -0,0 +1,132 @@
+# PyCodeCommenter — v3.0.0 Smart Merge & Multi-Style Implementation
+
+## MANDATORY FIRST STEP — READ BEFORE WRITING ANY CODE
+
+This is the most complex release. More than any other phase, the risk is
+building on wrong assumptions. You must read and fully understand the
+existing code before designing anything.
+
+Read these files in full before writing a single line:
+- PyCodeCommenter/commenter.py          (entire file — this is the core)
+- PyCodeCommenter/docstring_parser.py   (entire file)
+- PyCodeCommenter/templates.py          (entire file)
+- PyCodeCommenter/parameter_descriptions.py
+- PyCodeCommenter/inference.py          (added in v2.1.0 — confirm it exists)
+- PyCodeCommenter/config.py             (added in v2.1.0 — confirm it exists)
+- PyCodeCommenter/cli.py
+- PyCodeCommenter/__init__.py
+- pyproject.toml
+
+For each file, document:
+1. Exactly how `generate_docstrings()` produces and inserts docstring text
+2. Whether `get_patched_code()` does string manipulation or AST rewriting
+3. How `DocstringParser` breaks a docstring into sections — what the output
+   structure looks like (dict? dataclass? list?)
+4. Whether the parser already handles NumPy or Sphinx style, or only Google
+5. How the config system (from v2.1.0) passes `style` to the generator —
+   if it does not yet, document the gap
+
+Report this inventory before proceeding. Do not design the merge algorithm
+until you understand exactly how the current insertion works.
+
+---
+
+## Feature 1: Smart docstring merge algorithm
+
+### What to build
+Today, `generate_docstrings()` replaces any existing docstring entirely.
+Change this so that when a docstring already exists:
+
+1. Parse the existing docstring into sections using `DocstringParser`
+2. Generate a fresh docstring for the same function
+3. Merge: for each section in the generated docstring, check if the
+   corresponding section in the existing docstring was human-written
+   (i.e., its content does not match what the generator would have
+   auto-produced)
+4. If the section is human-written → keep the existing content
+5. If the section is missing in existing → insert the generated version
+6. If the section matches the auto-generated template exactly → replace
+   with the freshly generated version (it may now be more accurate)
+
+### Defining "auto-generated content"
+A section is considered auto-generated if it matches a template from
+`templates.py` or `inference.py` (from v2.1.0). Read these files and
+define the exact matching criteria before implementing.
+
+### Where to implement
+Add a `DocstringMerger` class to a new file `PyCodeCommenter/merger.py`.
+It must have this interface:
+
+```python
+class DocstringMerger:
+    def merge(
+        self,
+        existing_docstring: str,
+        generated_docstring: str,
+        function_name: str,
+        param_names: list[str],
+    ) -> str:
+        """Return the merged docstring string, ready to insert."""
+```
+
+Integrate it into `commenter.py` by calling `DocstringMerger().merge()`
+wherever an existing docstring would currently be replaced.
+
+### Constraints
+- Read exactly how commenter.py currently detects and replaces an existing
+  docstring before writing any merger logic.
+- The merger must never produce an invalid docstring — if merging fails for
+  any reason, fall back to the existing docstring unchanged and log a warning.
+- Do not change the public API of `PyCodeCommenter` — no new constructor
+  arguments required for basic usage.
+- Export `DocstringMerger` from `__init__.py`.
+- Write tests in `test_merger.py` covering:
+  - A function with no existing docstring (merger is not called)
+  - A function with a fully auto-generated docstring (gets replaced)
+  - A function with a human-written summary (summary preserved)
+  - A function with human-written Args entries (entries preserved)
+  - A function where the signature changed (new param added to Args)
+
+---
+
+## Feature 2: NumPy and Sphinx style generation
+
+### What to build
+Make the generator emit NumPy or Sphinx style docstrings when configured.
+The `style` config key (added in v2.1.0 config.py) controls this.
+
+### Step 1: Extend the parser
+Read `docstring_parser.py` in full. Document which styles it currently
+handles. Extend `DocstringParser.parse()` to fully handle:
+- **NumPy style**: `Parameters\n----------\nparam_name : type\n    description`
+- **Sphinx style**: `:param name: description\n:type name: type\n:returns:`
+
+The parse output structure must be identical regardless of input style —
+the validator and merger must not need to know which style was parsed.
+
+### Step 2: Add style templates
+Add NumPy and Sphinx output formatters alongside the existing Google formatter.
+Structure them as separate functions or a class with a `format(style)` method
+— read `templates.py` first to see the existing pattern, then extend it
+consistently.
+
+### Step 3: Wire to config
+In `commenter.py`, read the `style` value from the loaded config and pass it
+to the formatter. Default to `"google"` if not set.
+
+### Constraints
+- Google style must remain the default and must be completely unaffected.
+- The `DocstringParser` output structure must not change — keep the same
+  dict/dataclass keys. Add new keys only if absolutely necessary, and document
+  each addition.
+- Do not touch `validator.py` — validation is style-agnostic at this stage.
+- Write tests in `test_styles.py` covering generation and parsing round-trips
+  for all three styles.
+
+---
+
+## Integration requirement
+After both features are implemented, run the full test suite. Every existing
+test must still pass. If any test fails due to the merge algorithm changing
+generated output, update the test's expected value — do not suppress the
+failure.