pycodecommenter 2.0.3__py3-none-any.whl

pycodecommenter-2.0.3.dist-info/METADATA

@@ -0,0 +1,281 @@
+Metadata-Version: 2.4
+Name: pycodecommenter
+Version: 2.0.3
+Summary: Automatically generate, validate, and maintain Google-style docstrings for Python code
+Author-email: Amos Quety <amosnabasa4@gmail.com>
+License: MIT
+Project-URL: Homepage, https://github.com/AmosQuety/PyCodeCommenter
+Project-URL: Documentation, https://github.com/AmosQuety/PyCodeCommenter/blob/main/README.md
+Project-URL: Repository, https://github.com/AmosQuety/PyCodeCommenter
+Project-URL: Bug Tracker, https://github.com/AmosQuety/PyCodeCommenter/issues
+Keywords: documentation,docstring,validation,coverage,python
+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.8
+Classifier: Programming Language :: Python :: 3.9
+Classifier: Programming Language :: Python :: 3.10
+Classifier: Programming Language :: Python :: 3.11
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Topic :: Software Development :: Documentation
+Classifier: Topic :: Software Development :: Quality Assurance
+Requires-Python: >=3.8
+Description-Content-Type: text/markdown
+License-File: LICENSE
+Provides-Extra: dev
+Requires-Dist: pytest>=7.0; extra == "dev"
+Requires-Dist: pytest-cov>=4.0; extra == "dev"
+Requires-Dist: black>=23.0; extra == "dev"
+Requires-Dist: flake8>=6.0; extra == "dev"
+Dynamic: license-file
+
+# PyCodeCommenter 🚀
+
+[![PyPI version](https://badge.fury.io/py/pycodecommenter.svg)](https://pypi.org/project/pycodecommenter/)
+[![Python Support](https://img.shields.io/pypi/pyversions/pycodecommenter.svg)](https://pypi.org/project/pycodecommenter/)
+[![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](https://opensource.org/licenses/MIT)
+[![GitHub](https://img.shields.io/github/stars/AmosQuety/PyCodeCommenter?style=social)](https://github.com/AmosQuety/PyCodeCommenter)
+
+**The Python documentation tool that developers actually want to use.**
+
+PyCodeCommenter automatically generates, validates, and maintains Google-style docstrings for your Python code. Unlike AI-based tools, it provides **deterministic, rule-based validation** that catches documentation issues AI might miss.
+
+## Why PyCodeCommenter?
+
+### The Problem
+-  AI tools generate inconsistent documentation
+-  No way to validate existing docstrings against code
+-  Documentation drift as code evolves
+-  No coverage metrics for documentation quality
+
+### The Solution
+-  **Generate** professional docstrings automatically
+-  **Validate** existing docs against actual code signatures
+-  **Track** documentation coverage across projects
+-  **Integrate** with CI/CD pipelines
+
+### Terminal Usage
+```bash
+# Generate docstrings for a file
+pycodecommenter generate main.py -i
+
+# Validate documentation
+pycodecommenter validate main.py
+
+# Check project coverage
+pycodecommenter coverage .
+```
+
+##  Features
+
+### Comprehensive Validation
+Six types of validation checks:
+- **Signature Matching**: Params in code match docstring
+- **Type Consistency**: Type hints match documented types
+- **Exception Documentation**: Raised exceptions are documented
+- **Return Documentation**: Return values properly documented
+- **Format Compliance**: Follows Google-style guidelines
+- **Content Quality**: No placeholders or TODOs
+
+###  Coverage Reporting
+- Per-file coverage metrics
+- Project-wide statistics
+- Export to JSON, Markdown, or console
+- CI/CD integration ready
+
+###  Modern Python Support
+- Python 3.8+ support
+- Async functions (`async def`)
+- Complex type hints (`Union`, `Optional`, `Generic`)
+- PEP 604 unions (`int | str`)
+- PEP 585 generics (`list[int]`)
+
+###  Developer-Friendly
+- Beautiful console output
+- Actionable error messages
+- Multiple export formats
+- Fast AST-based analysis (no API calls)
+
+##  Usage Examples
+
+### Example 1: Basic Generation
+```python
+from PyCodeCommenter import PyCodeCommenter
+
+code = """
+def calculate_discount(price: float, rate: float = 0.1) -> float:
+    return price * (1 - rate)
+"""
+
+commenter = PyCodeCommenter().from_string(code)
+docstrings = commenter.generate_docstrings()
+print(commenter.get_patched_code())
+```
+
+**Output:**
+```python
+def calculate_discount(price: float, rate: float = 0.1) -> float:
+    """Calculate discount.
+    
+    Calculates the discount.
+    
+    Args:
+        price (float): Price of the object.
+        rate (float): Rate of the object. (default: 0.1)
+    
+    Returns:
+        float: Description of the return value.
+    """
+    return price * (1 - rate)
+```
+
+### Example 2: Validation in CI/CD
+```python
+# validate_docs.py
+import sys
+from PyCodeCommenter import PyCodeCommenter
+
+commenter = PyCodeCommenter().from_file("src/main.py")
+report = commenter.validate()
+
+if report.stats.errors > 0:
+    report.print_summary()
+    sys.exit(1)  # Fail CI build
+
+print(f"✓ Documentation validated: {report.stats.coverage_percentage:.1f}% coverage")
+```
+
+### Example 3: Coverage Enforcement
+```python
+from PyCodeCommenter import CoverageAnalyzer
+
+analyzer = CoverageAnalyzer()
+project = analyzer.analyze_directory("./src", exclude_patterns=['tests'])
+
+if project.total_coverage < 80.0:
+    print(f"❌ Coverage {project.total_coverage:.1f}% below threshold 80%")
+    project.print_report()
+    sys.exit(1)
+
+print(f"✓ Coverage {project.total_coverage:.1f}% meets threshold")
+```
+
+### Example 4: Export Reports
+```python
+import json
+from PyCodeCommenter import PyCodeCommenter
+
+commenter = PyCodeCommenter().from_file("mycode.py")
+report = commenter.validate()
+
+# JSON export
+with open("validation_report.json", "w") as f:
+    json.dump(report.to_dict(), f, indent=2)
+
+# Markdown export
+with open("validation_report.md", "w") as f:
+    f.write(report.to_markdown())
+```
+
+##  Configuration
+Create `.pycodecommenter.yaml` in your project root:
+```yaml
+style: google  # or 'numpy', 'sphinx'
+validation:
+  level: strict  # or 'moderate', 'lenient'
+  check_types: true
+  check_exceptions: true
+coverage:
+  threshold: 80
+  fail_below: true
+exclude:
+  - "*/tests/*"
+  - "*/migrations/*"
+  - "*/__pycache__/*"
+```
+
+##  Use Cases
+### For Individual Developers
+- Generate documentation for new functions quickly
+- Validate docs before committing
+- Track documentation coverage
+
+### For Teams
+- Enforce documentation standards in CI/CD
+- Prevent PRs with undocumented code
+- Maintain consistent documentation style
+
+### For Open Source Projects
+- Welcome contributors with clear doc requirements
+- Automated documentation checks in PRs
+- Public coverage badges
+
+##  Integration
+
+### Pre-commit Hook
+```yaml
+# .pre-commit-config.yaml
+repos:
+  - repo: local
+    hooks:
+      - id: validate-docstrings
+        name: Validate Docstrings
+        entry: pycodecommenter validate .
+        language: system
+        types: [python]
+```
+
+### GitHub Actions
+```yaml
+# .github/workflows/docs.yml
+name: Documentation Check
+
+on: [push, pull_request]
+
+jobs:
+  validate:
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v2
+      - name: Set up Python
+        uses: actions/setup-python@v2
+        with:
+          python-version: '3.9'
+      - name: Install dependencies
+        run: pip install pycodecommenter
+      - name: Validate documentation
+        run: pycodecommenter validate .
+```
+
+##  Documentation
+- **User Guide** - Comprehensive usage guide
+- **API Reference** - Complete API documentation
+- **Configuration** - Configuration options
+- **Contributing** - How to contribute
+
+##  Known Limitations
+- Does not support Python 2.x (EOL)
+- Match statements (Python 3.10+) have basic support
+- Complex decorators may affect docstring placement
+
+##  Roadmap
+- [ ] VS Code extension
+- [ ] Smart docstring updates (preserve human content)
+- [ ] AI-powered generation (optional)
+- [ ] NumPy and Sphinx style support
+- [ ] GitHub Action for automated PRs
+
+##  License
+MIT License - see [LICENSE](LICENSE) file for details.
+
+##  Contributing
+Contributions welcome! Please read `CONTRIBUTING.md` first.
+
+##  Show Your Support
+If PyCodeCommenter helped you, please star the repo! It helps others discover the project.
+
+##  Contact
+- **Issues**: [GitHub Issues](https://github.com/AmosQuety/PyCodeCommenter/issues)
+- **Discussions**: [GitHub Discussions](https://github.com/AmosQuety/PyCodeCommenter/discussions)
+

pycodecommenter-2.0.3.dist-info/RECORD

@@ -0,0 +1,15 @@
+PyCodeCommenter/__init__.py,sha256=lWNtYjXr-Foe4Bu9ShKeXddqTjU0lPtOp9fUS5knZyI,800
+PyCodeCommenter/cli.py,sha256=Seog190BKtumAfwiqH8TgpMYTCpgzHzGqE5VzfZAtMo,2878
+PyCodeCommenter/commenter.py,sha256=iO1kcOu4-qG_T7rQNceB6NwEOwT7qPN5oCw9UwBvqy8,18383
+PyCodeCommenter/coverage.py,sha256=EWOHo4CPyEyjy76n4zrJBkROydJari-ek0uNNEY7ICU,4721
+PyCodeCommenter/docstring_parser.py,sha256=yImIYPgy7ZTuhVfL837vCGpMkvTiJkbbgmroi92iqDo,4600
+PyCodeCommenter/parameter_descriptions.py,sha256=QTc9ZpRxP6s8xmdMUiLEyW16uC2edC49fHaMri-mUSs,2530
+PyCodeCommenter/templates.py,sha256=NVQ7owE9kKOu0aJwl2VFBoJw2Wy5Hei4bm4bSQVo4iA,5932
+PyCodeCommenter/type_analyzer.py,sha256=Kpvphb88egpWZQ324IJ-OCHtxCGF0ob29Lik0sZ34cI,6949
+PyCodeCommenter/validator.py,sha256=1HnWuVDZjgp4XKjQ2msjUMrU0keD3-AzSp91nOBtrJc,23424
+pycodecommenter-2.0.3.dist-info/licenses/LICENSE,sha256=8p3TvU2B1FY__xFIPqYBoGk_-qckZGLROyHwwySc-0I,1087
+pycodecommenter-2.0.3.dist-info/METADATA,sha256=UaCrriTmU0g0351ytYJLUHjtvWF1JeIys4tYF1imQJM,8590
+pycodecommenter-2.0.3.dist-info/WHEEL,sha256=qELbo2s1Yzl39ZmrAibXA2jjPLUYfnVhUNTlyF1rq0Y,92
+pycodecommenter-2.0.3.dist-info/entry_points.txt,sha256=T5dBrm6mltFaGL7OaZMSj1Uw3Jv8PLkQZGb9O4WN7iM,61
+pycodecommenter-2.0.3.dist-info/top_level.txt,sha256=J0aVA0MqttB-7SkjFw5qSuGVhyhfWUVMs61_HU-rhBA,16
+pycodecommenter-2.0.3.dist-info/RECORD,,

pycodecommenter-2.0.3.dist-info/WHEEL

@@ -0,0 +1,5 @@
+Wheel-Version: 1.0
+Generator: setuptools (80.10.1)
+Root-Is-Purelib: true
+Tag: py3-none-any
+

pycodecommenter-2.0.3.dist-info/entry_points.txt

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

pycodecommenter-2.0.3.dist-info/licenses/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 AmosQuety
+
+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.

pycodecommenter-2.0.3.dist-info/top_level.txt

@@ -0,0 +1 @@
+PyCodeCommenter