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:

1. In your terminal, run:

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

2. 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:

1. 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

2. Or, in your requirements.txt file, add:

   docstring-format-checker

   Then run:

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

3. Or just run this:

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

Using poetry:

1. In your pyproject.toml file, add:

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

   Then run:

   poetry sync
   poetry install

2. Or just run this:

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

Using uv:

1. In your pyproject.toml file, add:

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

   Then run:

   uv sync

2. Or run this:

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

3. 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

1. Clone the repository:

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

2. Set up development environment:

   uv sync --all-groups

3. Run tests:

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

4. Run CLI locally:

   uv run dfc --check examples/example_code.py

🧪 Build and Test

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

1. Write code in accordance with PEP8 requirements.
2. Write a UnitTest for each function or feature included.
3. Maintain CodeCoverage at 100%.
4. Ensure all UnitTests pass.
5. 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.