docstring-format-checker 0.1.0__py3-none-any.whl

docstring_format_checker/utils/exceptions.py

@@ -0,0 +1,39 @@
+class DocstringError(Exception):
+    """
+    Exception raised when a docstring validation error occurs.
+    """
+
+    def __init__(
+        self,
+        message: str,
+        file_path: str,
+        line_number: int,
+        item_name: str,
+        item_type: str,
+    ) -> None:
+        self.message = message
+        self.file_path = file_path
+        self.line_number = line_number
+        self.item_name = item_name
+        self.item_type = item_type
+        super().__init__(f"Line {line_number}, {item_type} '{item_name}': {message}")
+
+
+class InvalidConfigError(Exception):
+    pass
+
+
+class InvalidConfigError_DuplicateOrderValues(Exception):
+    pass
+
+
+class InvalidTypeValuesError(Exception):
+    pass
+
+
+class InvalidFileError(OSError):
+    pass
+
+
+class DirectoryNotFoundError(OSError):
+    pass

docstring_format_checker-0.1.0.dist-info/METADATA

@@ -0,0 +1,467 @@
+Metadata-Version: 2.4
+Name: docstring-format-checker
+Version: 0.1.0
+Summary: A CLI tool to check and validate Python docstring formatting and completeness
+Author: Chris Mahoney
+Author-email: Chris Mahoney <docstring-format-checker@data-science-extensions.com>
+License-Expression: MIT
+Classifier: Development Status :: 4 - Beta
+Classifier: License :: OSI Approved :: MIT License
+Classifier: Topic :: Software Development :: Quality Assurance
+Classifier: Topic :: Software Development :: Libraries :: Python Modules
+Classifier: Topic :: Software Development :: Testing :: Unit
+Classifier: Topic :: Utilities
+Classifier: Programming Language :: Python :: 3
+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: Programming Language :: Python :: 3.13
+Classifier: Intended Audience :: Developers
+Classifier: Environment :: Console
+Requires-Dist: typer>=0.9.0
+Requires-Dist: tomli>=2.0.0 ; python_full_version < '3.11'
+Requires-Dist: rich>=13.0.0
+Requires-Dist: toolbox-python==1.*
+Maintainer: Chris Mahoney
+Maintainer-email: Chris Mahoney <docstring-format-checker@data-science-extensions.com>
+Requires-Python: >=3.9
+Project-URL: Changelog, https://github.com/data-science-extensions/docstring-format-checker/releases
+Project-URL: Documentation, https://github.com/data-science-extensions/docstring-format-checker/blob/main/README.md
+Project-URL: Homepage, https://github.com/data-science-extensions/docstring-format-checker
+Project-URL: Issues, https://github.com/data-science-extensions/docstring-format-checker/issues
+Project-URL: Repository, https://github.com/data-science-extensions/docstring-format-checker
+Description-Content-Type: text/markdown
+
+<h1 align="center"><u><code>docstring-format-checker</code></u></h1>
+
+<p align="center">
+<a href="https://github.com/data-science-extensions/docstring-format-checker/releases">
+    <img src="https://img.shields.io/github/v/release/data-science-extensions/docstring-format-checker?logo=github" alt="github-release"></a>
+<a href="https://pypi.org/project/docstring-format-checker">
+    <img src="https://img.shields.io/pypi/implementation/docstring-format-checker?logo=pypi&logoColor=ffde57" alt="implementation"></a>
+<a href="https://pypi.org/project/docstring-format-checker">
+    <img src="https://img.shields.io/pypi/v/docstring-format-checker?label=version&logo=python&logoColor=ffde57&color=blue" alt="version"></a>
+<a href="https://pypi.org/project/docstring-format-checker">
+    <img src="https://img.shields.io/pypi/pyversions/docstring-format-checker?logo=python&logoColor=ffde57" alt="python-versions"></a>
+<br>
+<a href="https://github.com/data-science-extensions/docstring-format-checker/actions/workflows/ci.yml">
+    <img src="https://img.shields.io/static/v1?label=os&message=ubuntu+|+macos+|+windows&color=blue&logo=ubuntu&logoColor=green" alt="os"></a>
+<a href="https://pypi.org/project/docstring-format-checker">
+    <img src="https://img.shields.io/pypi/status/docstring-format-checker?color=green" alt="pypi-status"></a>
+<a href="https://pypi.org/project/docstring-format-checker">
+    <img src="https://img.shields.io/pypi/format/docstring-format-checker?color=green" alt="pypi-format"></a>
+<a href="https://github.com/data-science-extensions/docstring-format-checker/blob/main/LICENSE">
+    <img src="https://img.shields.io/github/license/data-science-extensions/docstring-format-checker?color=green" alt="github-license"></a>
+<a href="https://piptrends.com/package/docstring-format-checker">
+    <img src="https://img.shields.io/pypi/dm/docstring-format-checker?color=green" alt="pypi-downloads"></a>
+<a href="https://codecov.io/gh/data-science-extensions/docstring-format-checker">
+    <img src="https://codecov.io/gh/data-science-extensions/docstring-format-checker/graph/badge.svg" alt="codecov-repo"></a>
+<a href="https://github.com/psf/black">
+    <img src="https://img.shields.io/static/v1?label=style&message=black&color=black&logo=windows-terminal&logoColor=white" alt="style"></a>
+<br>
+<a href="https://github.com/data-science-extensions/docstring-format-checker">
+    <img src="https://img.shields.io/badge/contributions-welcome-brightgreen.svg?style=flat" alt="contributions"></a>
+<br>
+<a href="https://github.com/data-science-extensions/docstring-format-checker/actions/workflows/ci.yml">
+    <img src="https://github.com/data-science-extensions/docstring-format-checker/actions/workflows/ci.yml/badge.svg?event=pull_request" alt="CI"></a>
+<a href="https://github.com/data-science-extensions/docstring-format-checker/actions/workflows/cd.yml">
+    <img src="https://github.com/data-science-extensions/docstring-format-checker/actions/workflows/cd.yml/badge.svg?event=release" alt="CD"></a>
+</p>
+
+
+### Introduction
+
+A powerful Python CLI tool that validates docstring formatting and completeness using AST parsing. Ensure consistent, high-quality documentation across your entire codebase with configurable validation rules and rich terminal output.
+
+**Key Features:**
+
+- 🔍 **AST-based parsing** - Robust code analysis without regex fragility
+- ⚙️ **Configurable validation** - Four section types with TOML-based configuration
+- 📁 **Hierarchical config discovery** - Automatic `pyproject.toml` detection
+- 🎨 **Rich terminal output** - Beautiful colored output and error tables
+- 🚀 **Dual CLI entry points** - Use `docstring-format-checker` or `dfc`
+- 🛡️ **100% test coverage** - Thoroughly tested and reliable
+
+
+### Quick Start
+
+```bash
+# Install
+uv add docstring-format-checker
+
+# Check a single file
+dfc check my_module.py
+
+# Check entire directory
+dfc check src/
+
+# Generate example configuration
+dfc config-example
+```
+
+
+### Key URLs
+
+For reference, these URL's are used:
+
+| Type           | Source | URL                                                                 |
+| -------------- | ------ | ------------------------------------------------------------------- |
+| Git Repo       | GitHub | https://github.com/data-science-extensions/docstring-format-checker |
+| Python Package | PyPI   | https://pypi.org/project/docstring-format-checker                   |
+| Package Docs   | Pages  | https://data-science-extensions.com/docstring-format-checker        |
+
+
+### Section Types
+
+Configure validation for four types of docstring sections:
+
+| Type                 | Description               | Example Use                    |
+| -------------------- | ------------------------- | ------------------------------ |
+| `free_text`          | Admonition-style sections | Summary, details, examples     |
+| `list_name`          | Simple name lists         | Simple parameter lists         |
+| `list_type`          | Type-only lists           | Raises, yields sections        |
+| `list_name_and_type` | Name and type lists       | Parameters, returns with types |
+
+
+### Configuration
+
+Create a `pyproject.toml` with your validation rules:
+
+```toml
+[tool.dfc]
+
+[[tool.dfc.sections]]
+order = 1
+name = "summary"
+type = "free_text"
+admonition = "note"
+prefix = "!!!"
+required = true
+
+[[tool.dfc.sections]]
+order = 2
+name = "params"
+type = "list_name_and_type"
+required = true
+
+[[tool.dfc.sections]]
+order = 3
+name = "returns"
+type = "list_name_and_type"
+required = false
+
+[[tool.dfc.sections]]
+order = 4
+name = "raises"
+type = "list_type"
+required = false
+```
+
+
+### Installation
+
+You can install and use this package multiple ways by using any of your preferred methods: [`pip`][pip], [`pipenv`][pipenv], [`poetry`][poetry], or [`uv`][uv].
+
+
+#### Using [`pip`][pip]:
+
+1. In your terminal, run:
+
+    ```sh
+    python3 -m pip install --upgrade pip
+    python3 -m pip install docstring-format-checker
+    ```
+
+2. Or, in your `requirements.txt` file, add:
+
+    ```txt
+    docstring-format-checker
+    ```
+
+    Then run:
+
+    ```sh
+    python3 -m pip install --upgrade pip
+    python3 -m pip install --requirement=requirements.txt
+    ```
+
+
+#### Using [`pipenv`][pipenv]:
+
+1. Install using environment variables:
+
+    In your `Pipfile` file, add:
+
+    ```toml
+    [[source]]
+    url = "https://pypi.org/simple"
+    verify_ssl = false
+    name = "pypi"
+
+    [packages]
+    docstring-format-checker = "*"
+    ```
+
+    Then run:
+
+    ```sh
+    python3 -m pip install pipenv
+    python3 -m pipenv install --verbose --skip-lock --categories=root index=pypi docstring-format-checker
+    ```
+
+2. Or, in your `requirements.txt` file, add:
+
+    ```sh
+    docstring-format-checker
+    ```
+
+    Then run:
+
+    ```sh
+    python3 -m pipenv install --verbose --skip-lock --requirements=requirements.txt
+    ```
+
+3. Or just run this:
+
+    ```sh
+    python3 -m pipenv install --verbose --skip-lock docstring-format-checker
+    ```
+
+
+#### Using [`poetry`][poetry]:
+
+1. In your `pyproject.toml` file, add:
+
+    ```toml
+    [project]
+    dependencies = [
+        "docstring-format-checker==0.*",
+    ]
+    ```
+
+    Then run:
+
+    ```sh
+    poetry sync
+    poetry install
+    ```
+
+2. Or just run this:
+
+    ```sh
+    poetry add "docstring-format-checker==0.*"
+    poetry sync
+    poetry install
+    ```
+
+
+#### Using [`uv`][uv]:
+
+1. In your `pyproject.toml` file, add:
+
+    ```toml
+    [project]
+    dependencies = [
+        "docstring-format-checker==0.*",
+    ]
+    ```
+
+   Then run:
+
+   ```sh
+   uv sync
+   ```
+
+2. Or run this:
+
+    ```sh
+    uv add "docstring-format-checker==0.*"
+    uv sync
+    ```
+
+3. Or just run this:
+
+    ```sh
+    uv pip install "docstring-format-checker==0.*"
+    ```
+
+
+### Usage Examples
+
+
+#### Basic Usage
+
+```bash
+# Check a single Python file
+dfc check src/my_module.py
+
+# Check entire directory recursively
+dfc check src/
+
+# Check with verbose output
+dfc check --verbose src/
+
+# Generate example configuration file
+dfc config-example > pyproject.toml
+```
+
+
+#### Advanced Configuration
+
+```bash
+# Use custom config file location
+dfc check --config custom_config.toml src/
+
+# Check specific function patterns
+dfc check --include-pattern "**/api/*.py" src/
+
+# Exclude test files
+dfc check --exclude-pattern "**/test_*.py" src/
+```
+
+
+#### Integration with CI/CD
+
+```yaml
+# .github/workflows/docs.yml
+name: Documentation Quality
+on: [push, pull_request]
+
+jobs:
+  docstring-check:
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v4
+      - uses: astral-sh/setup-uv@v3
+      - run: uv pip install docstring-format-checker
+      - run: dfc check src/
+```
+
+
+### Example Output
+
+```
+📋 Docstring Format Checker Results
+
+✅ src/utils/helpers.py
+❌ src/models/user.py
+   └── Function 'create_user' missing required section: 'params'
+   └── Function 'delete_user' missing required section: 'returns'
+
+❌ src/api/endpoints.py
+   └── Method 'UserAPI.get_user' invalid section format: 'raises'
+
+📊 Summary: 1/3 files passed (33.3%)
+```
+
+
+### Architecture
+
+The tool follows a clean, modular architecture:
+
+- **`core.py`** - `DocstringChecker` class with AST parsing and validation logic
+- **`config.py`** - Configuration loading and `SectionConfig` management
+- **`cli.py`** - Typer-based CLI with dual entry points
+- **`utils/exceptions.py`** - Custom exception classes for structured error handling
+
+
+### Contribution
+
+Check the [CONTRIBUTING.md][github-contributing] file or [Contributing][docs-contributing] page.
+
+
+### Development
+
+1. **Clone the repository:**
+
+    ```sh
+    git clone https://github.com/data-science-extensions/docstring-format-checker.git
+    cd docstring-format-checker
+    ```
+
+2. **Set up development environment:**
+
+    ```sh
+    uv sync --all-groups
+    ```
+
+3. **Run tests:**
+
+    ```sh
+    uv run pytest --config-file=pyproject.toml --cov-report=term-missing
+    ```
+
+4. **Run CLI locally:**
+
+    ```sh
+    uv run dfc check examples/example_code.py
+    ```
+
+
+### Build and Test
+
+To ensure that the package is working as expected, please ensure that:
+
+1. You write your code as per [PEP8][pep8] requirements.
+2. You write a [UnitTest][unittest] for each function/feature you include.
+3. The [CodeCoverage][codecov] is 100%.
+4. All [UnitTests][pytest] are passing.
+5. [MyPy][mypy] is passing 100%.
+
+
+#### Testing
+
+- Run them all together:
+
+    ```sh
+    uv run pytest --config-file=pyproject.toml
+    ```
+
+- Or run them individually:
+
+    - **Tests with Coverage:**
+        ```sh
+        uv run pytest --config-file=pyproject.toml --cov-report=term-missing
+        ```
+
+    - **Type Checking:**
+        ```sh
+        uv run mypy src/
+        ```
+
+    - **Code Formatting:**
+        ```sh
+        uv run black --check src/
+        ```
+
+    - **Linting:**
+        ```sh
+        uv run ruff check src/
+        ```
+
+
+### License
+
+This project is licensed under the MIT License - see the [LICENSE][github-license] file for details.
+
+[github-repo]: https://github.com/data-science-extensions/docstring-format-checker
+[github-contributing]: https://github.com/data-science-extensions/docstring-format-checker/blob/main/CONTRIBUTING.md
+[docs-contributing]: https://data-science-extensions.com/docstring-format-checker/latest/usage/contributing/
+[github-release]: https://github.com/data-science-extensions/docstring-format-checker/releases
+[github-ci]: https://github.com/data-science-extensions/docstring-format-checker/actions/workflows/ci.yml
+[github-cd]: https://github.com/data-science-extensions/docstring-format-checker/actions/workflows/cd.yml
+[github-license]: https://github.com/data-science-extensions/docstring-format-checker/blob/main/LICENSE
+[codecov-repo]: https://codecov.io/gh/data-science-extensions/docstring-format-checker
+[pypi]: https://pypi.org/project/docstring-format-checker
+[docs]: https://data-science-extensions.com/docstring-format-checker
+[pip]: https://pypi.org/project/pip
+[pipenv]: https://github.com/pypa/pipenv
+[poetry]: https://python-poetry.org
+[uv]: https://docs.astral.sh/uv/
+[pep8]: https://peps.python.org/pep-0008/
+[unittest]: https://docs.python.org/3/library/unittest.html
+[codecov]: https://codecov.io/
+[pytest]: https://docs.pytest.org
+[mypy]: http://www.mypy-lang.org/
+[black]: https://black.readthedocs.io/

docstring_format_checker-0.1.0.dist-info/RECORD

@@ -0,0 +1,10 @@
+docstring_format_checker/__init__.py,sha256=b1b55d5d088d0f47c7ab9ab764e0ee082911aba152c1d372a2d1f6a96b343aff,552
+docstring_format_checker/cli.py,sha256=b1f06dccaf06bf41afbc85ec7580bce636db1d59002bd89c8e54b4a86bcb0cc7,23572
+docstring_format_checker/config.py,sha256=576af22f4792d5f2c1562cbf398c3e8313ad2ae860b498f96ad1fdbaa227cdcf,12086
+docstring_format_checker/core.py,sha256=12716f465f99d3fa9d39652f01095f047734347e13fe72ced07173e9266b84ed,26291
+docstring_format_checker/utils/__init__.py,sha256=e3b0c44298fc1c149afbf4c8996fb92427ae41e4649b934ca495991b7852b855,0
+docstring_format_checker/utils/exceptions.py,sha256=b6c5b6f0f8df41a13d3506e56595436838a3411e0ab01581e73b9ccab1b8df6e,804
+docstring_format_checker-0.1.0.dist-info/WHEEL,sha256=ab6157bc637547491fb4567cd7ddf26b04d63382916ca16c29a5c8e94c9c9ef7,79
+docstring_format_checker-0.1.0.dist-info/entry_points.txt,sha256=07f2adf44467d5d217e6106fc0a0de650a57aa8d5a09b461b2e17718e9b5a428,134
+docstring_format_checker-0.1.0.dist-info/METADATA,sha256=70dff3114e69a955b6533b41f3455e996e9e67147524cb1012c74ff888f8397a,14505
+docstring_format_checker-0.1.0.dist-info/RECORD,,

docstring_format_checker-0.1.0.dist-info/WHEEL

@@ -0,0 +1,4 @@
+Wheel-Version: 1.0
+Generator: uv 0.7.22
+Root-Is-Purelib: true
+Tag: py3-none-any

docstring_format_checker-0.1.0.dist-info/entry_points.txt

@@ -0,0 +1,4 @@
+[console_scripts]
+dfc = docstring_format_checker.cli:entry_point
+docstring-format-checker = docstring_format_checker.cli:entry_point
+