pycodecommenter 2.1.0__tar.gz → 2.2.0__tar.gz

pycodecommenter-2.2.0/.github/workflows/docs.yml

@@ -0,0 +1,66 @@
+# .github/workflows/docs.yml
+# Builds and deploys the MkDocs documentation site to GitHub Pages.
+#
+# Trigger: any push to `main` that touches docs/ or this workflow file.
+# Manual trigger: workflow_dispatch (run from the Actions tab at any time).
+#
+# REQUIRED ONE-TIME SETUP:
+# GitHub repo → Settings → Pages → Source → select "GitHub Actions"
+# Without that change the deploy job runs but the site never goes live.
+
+name: Deploy Documentation
+
+on:
+  push:
+    branches:
+      - main
+    paths:
+      - 'docs/**'
+      - 'mkdocs.yml'
+      - '.github/workflows/docs.yml'
+  workflow_dispatch:
+
+permissions:
+  contents: read
+  pages: write
+  id-token: write
+
+concurrency:
+  group: "pages"
+  cancel-in-progress: false
+
+jobs:
+  build:
+    name: Build Documentation Site
+    runs-on: ubuntu-latest
+    steps:
+      - name: Checkout repository
+        uses: actions/checkout@v4
+
+      - name: Set up Python
+        uses: actions/setup-python@v5
+        with:
+          python-version: '3.x'
+
+      - name: Install MkDocs and theme
+        run: pip install mkdocs mkdocs-material
+
+      - name: Build site
+        run: mkdocs build --strict --site-dir _site
+
+      - name: Upload Pages artifact
+        uses: actions/upload-pages-artifact@v3
+        with:
+          path: _site
+
+  deploy:
+    name: Deploy to GitHub Pages
+    needs: build
+    runs-on: ubuntu-latest
+    environment:
+      name: github-pages
+      url: ${{ steps.deployment.outputs.page_url }}
+    steps:
+      - name: Deploy to GitHub Pages
+        id: deployment
+        uses: actions/deploy-pages@v4

{pycodecommenter-2.1.0 → pycodecommenter-2.2.0}/.github/workflows/publish.yml

@@ -1,33 +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
+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 → pycodecommenter-2.2.0}/.gitignore

@@ -1,56 +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/
+# 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.2.0/.well-known/ai-plugin.json

@@ -0,0 +1,23 @@
+{
+  "schema_version": "v1",
+  "name_for_human": "PyCodeCommenter",
+  "name_for_model": "pycodecommenter",
+  "description_for_human": "Python docstring generator and validator. Generates Google-style docstrings from AST, validates them against real function signatures, and measures documentation coverage.",
+  "description_for_model": "PyCodeCommenter is a deterministic, AST-based Python tool. It can: (1) generate Google-style docstrings for undocumented Python functions and classes from their AST, (2) validate existing docstrings against real function signatures across six check categories, (3) measure documentation coverage per file or project, and (4) export structured JSON reports. It requires no AI, no network access, and no API keys. Install with 'pip install pycodecommenter'. Main classes: PyCodeCommenter (generation), DocstringValidator (validation), CoverageAnalyzer (coverage).",
+  "auth": {
+    "type": "none"
+  },
+  "api": {
+    "type": "none"
+  },
+  "logo_url": "https://amosquety.github.io/PyCodeCommenter/assets/logo.png",
+  "contact_email": "amosnabasa4@gmail.com",
+  "legal_info_url": "https://github.com/AmosQuety/PyCodeCommenter/blob/main/LICENSE",
+  "homepage": "https://amosquety.github.io/PyCodeCommenter/",
+  "repository": "https://github.com/AmosQuety/PyCodeCommenter",
+  "pypi": "https://pypi.org/project/pycodecommenter/",
+  "install_command": "pip install pycodecommenter",
+  "version": "2.2.0",
+  "license": "MIT",
+  "author": "Nabasa Amos (Amos Quety)"
+}

pycodecommenter-2.2.0/CHANGELOG.md

@@ -0,0 +1,63 @@
+# Changelog
+
+All notable changes to PyCodeCommenter will be documented in this file.
+Format follows [Keep a Changelog](https://keepachangelog.com/en/1.0.0/).
+
+## [2.2.0] - 2026-07-12
+
+### Added
+- **Decorator-aware validation** — `@property` setter and deleter variants no longer produce false-positive
+  "missing Returns section" warnings. `@classmethod` (`cls`) and `@staticmethod` were verified already correct.
+- **`--output-format json`** flag on both `validate` and `coverage` subcommands. Prints machine-readable
+  JSON to stdout; text output is completely unchanged.
+- **`ValidationReport.to_dict()`** updated to spec-compliant shape: `stats.total`, `stats.info`,
+  `stats.coverage_percentage`; issues now include `line` (integer), `severity` (uppercase), `check`, `message`.
+- **`_has_raises_section()` helper** in `validator.py` — recognises `Raises:` (Google), `Raises\n`
+  (bare header), and `:raises ` (Sphinx, trailing space prevents false matches).
+- **`llms.txt`** file at repo root — AI agent and LLM crawler discovery file.
+- **SEO/AEO optimisation** — keyword-rich README, PyPI classifiers/keywords, per-page meta tags on all
+  doc pages, JSON-LD `SoftwareApplication` schema on docs homepage.
+
+### Changed
+- `test_validation.py` rewritten from script-style to proper pytest (17 tests, all pass).
+- `pyproject.toml` keywords expanded to 20 terms; classifiers expanded with `Code Generators`,
+  `Libraries :: Python Modules`, `Environment :: Console`, `Operating System :: OS Independent`.
+- `mkdocs.yml` enriched with `site_author`, explicit `language: en`, `navigation.indexes`,
+  `search.share`, `toc.follow`, and `meta` markdown extension for per-page SEO tags.
+
+## [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.2.0/CITATION.cff

@@ -0,0 +1,32 @@
+cff-version: 1.2.0
+message: "If you use PyCodeCommenter in your research or project, please cite it using this metadata."
+type: software
+title: PyCodeCommenter
+abstract: >
+  PyCodeCommenter is an open-source Python tool for automatically generating
+  Google-style docstrings from Python AST, validating existing docstrings
+  against real function signatures, and measuring documentation coverage.
+  It is deterministic, rule-based, and requires no AI or network access.
+authors:
+  - family-names: Amos
+    given-names: Nabasa
+    alias: Amos Quety
+    email: amosnabasa4@gmail.com
+    website: https://nabasa-amos.netlify.app
+    orcid: ""
+version: 2.2.0
+date-released: "2026-07-12"
+license: MIT
+repository-code: https://github.com/AmosQuety/PyCodeCommenter
+url: https://amosquety.github.io/PyCodeCommenter/
+keywords:
+  - python
+  - docstring
+  - documentation
+  - validation
+  - coverage
+  - google-style
+  - ast
+  - developer-tools
+  - ci-cd
+  - static-analysis

{pycodecommenter-2.1.0 → pycodecommenter-2.2.0}/CONTRIBUTING.md

@@ -1,29 +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!
+# 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 → pycodecommenter-2.2.0}/Future Work/Future Release WorkPlan.txt

@@ -1,15 +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
+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.