`docstring-format-checker`

📝 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
📚 Flexible section ordering - Support for unordered "floating" sections
📁 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🔗

# 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 --example=config

🔗 Key URLs🔗

For reference, these URLs 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/toolboxes/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. The order attribute is optional; sections without an order (like "deprecation warning") can appear anywhere in the docstring.

You can utilise a layout in separate blocks like this:

[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

# Unordered section - can appear anywhere
[[tool.dfc.sections]]
name = "deprecation warning"
type = "free_text"
admonition = "deprecation"
prefix = "!!!"
required = false

[[tool.dfc.sections]]
order = 3
name = "returns"
type = "list_name_and_type"
required = false

Or like this in a single block:

[tool.dfc]
# or [tool.docstring-format-checker]
allow_undefined_sections = false
require_docstrings = true
check_private = true
validate_param_types = true
optional_style = "validate"  # "silent", "validate", or "strict"
sections = [
    { order = 1, name = "summary",  type = "free_text",          required = true, admonition = "note", prefix = "!!!" },
    { order = 2, name = "details",  type = "free_text",          required = false, admonition = "abstract", prefix = "???+" },
    { order = 3, name = "params",   type = "list_name_and_type", required = false },
    { order = 4, name = "raises",   type = "list_type",          required = false },
    { order = 5, name = "returns",  type = "list_name_and_type", required = false },
    { order = 6, name = "yields",   type = "list_type",          required = false },
    { order = 7, name = "examples", type = "free_text",          required = false, admonition = "example", prefix = "???+" },
    { order = 8, name = "notes",    type = "free_text",          required = false, admonition = "note", prefix = "???" },
]

📥 Installation🔗

You can install and use this package multiple ways by using any of your preferred methods: pip, pipenv, poetry, or uv.

Using `pip`:🔗

In your terminal, run:

python3 -m pip install --upgrade pip
python3 -m pip install docstring-format-checker

Or, in your requirements.txt file, add:

docstring-format-checker

Then run:

python3 -m pip install --upgrade pip
python3 -m pip install --requirement=requirements.txt

Using `pipenv`:🔗

Install using environment variables:

In your Pipfile file, add:

[[source]]
url = "https://pypi.org/simple"
verify_ssl = false
name = "pypi"

[packages]
docstring-format-checker = "*"

Then run:

python3 -m pip install pipenv
python3 -m pipenv install --verbose --skip-lock --categories=root index=pypi docstring-format-checker

Or, in your requirements.txt file, add:

docstring-format-checker

Then run:

python3 -m pipenv install --verbose --skip-lock --requirements=requirements.txt

Or just run this:

python3 -m pipenv install --verbose --skip-lock docstring-format-checker

Using `poetry`:🔗

In your pyproject.toml file, add:

[project]
dependencies = [
    "docstring-format-checker==1.*",
]

Then run:

poetry sync
poetry install

Or just run this:

poetry add "docstring-format-checker==1.*"
poetry sync
poetry install

Using `uv`:🔗

In your pyproject.toml file, add:

[project]
dependencies = [
    "docstring-format-checker==1.*",
]

Then run:

uv sync

Or run this:

uv add "docstring-format-checker==1.*"
uv sync

Or just run this:

uv pip install "docstring-format-checker==1.*"

💡 Usage Examples🔗

# Check a single Python file
dfc --check src/my_module.py

# Check multiple Python files
dfc file1.py file2.py

# Check entire directory recursively
dfc --check src/

# Check with table output format
dfc --output=table src/

# Generate example configuration file
dfc --example=config > pyproject.toml

Advanced Configuration🔗

# Use custom config file location
dfc --config=custom_config.toml src/

# Exclude specific files using glob patterns
dfc src/ --exclude "**/test_*.py"

# Stop on first failure (CI environments)
dfc --check src/

# Suppress non-error output
dfc --quiet src/

Integration with CI/CD🔗

# .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/

Integration with Pre-commit🔗

# .pre-commit-config.yaml
repos:
  - repo: https://github.com/data-science-extensions/docstring-format-checker
    rev: "v1.11.3"
    hooks:
    -   id: docstring-format-checker
        name: Docstring Format Checker
        entry: dfc --check

📋 Example Output🔗

Standard List Output🔗

The option output=list is the default:

dfc --check src/models/user.py

Or you can declare it explicitly:

dfc --check --output=list src/models/user.py

Which returns:

src/models/user.py
  Line 12 - function 'create_user':
    - Missing required section: 'params'
  Line 45 - function 'delete_user':
    - Missing required section: 'returns'

Found 2 error(s) in 2 functions over 1 file

Table Output Format🔗

dfc --check --output=table src/models/user.py

┏━━━━━━━━━━━━━━━━━━━━┳━━━━━━┳━━━━━━━━━━━━━┳━━━━━━━━━━┳━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━┓
┃ File               ┃ Line ┃ Item        ┃ Type     ┃ Error                            ┃
┡━━━━━━━━━━━━━━━━━━━━╇━━━━━━╇━━━━━━━━━━━━━╇━━━━━━━━━━╇━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━┩
│ src/models/user.py │   12 │ create_user │ function │ - Missing required section:      │
│                    │      │             │          │ 'params'.                        │
│                    │   45 │ delete_user │ function │ - Missing required section:      │
│                    │      │             │          │ 'returns'.                       │
└────────────────────┴──────┴─────────────┴──────────┴──────────────────────────────────┘

Found 2 error(s) in 2 functions over 1 file

🏗️ 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 file or Contributing page.

🛠️ Development🔗

Clone the repository:

git clone https://github.com/data-science-extensions/docstring-format-checker.git
cd docstring-format-checker

Set up development environment:
```
uv sync --all-groups
```

Run tests:

uv run pytest --config-file=pyproject.toml --cov-report=term-missing

Run CLI locally:

uv run dfc --check examples/example_code.py

🧪 Build and Test🔗

To ensure that the package works as expected, ensure that:

Write code in accordance with PEP8 requirements.
Write a UnitTest for each function or feature included.
Maintain CodeCoverage at 100%.
Ensure all UnitTests pass.
Ensure MyPy passes 100%.

Testing🔗

Run them all together:

uv run pytest --config-file=pyproject.toml

Or run them individually:

Tests with Coverage:

uv run pytest --config-file=pyproject.toml --cov-report=term-missing

Type Checking:
```
uv run mypy src/
```
Code Formatting:
```
uv run black --check src/
```
Linting:
```
uv run ruff check src/
```

📄 License🔗

This project is licensed under the MIT License - see the LICENSE file for details.

docstring-format-checker

📝 Introduction🔗

🚀 Quick Start🔗

🔗 Key URLs🔗

📂 Section Types🔗

⚙️ Configuration🔗

📥 Installation🔗

Using pip:🔗

Using pipenv:🔗

Using poetry:🔗

Using uv:🔗

💡 Usage Examples🔗

Advanced Configuration🔗

Integration with CI/CD🔗

Integration with Pre-commit🔗

📋 Example Output🔗

Standard List Output🔗

Table Output Format🔗

🏗️ Architecture🔗

🤝 Contribution🔗

🛠️ Development🔗

🧪 Build and Test🔗

Testing🔗

📄 License🔗

`docstring-format-checker`

Using `pip`:🔗

Using `pipenv`:🔗

Using `poetry`:🔗

Using `uv`:🔗