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
• 📁 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 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:

[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, 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==0.*",
   ]
   

   Then run:

   poetry sync
   poetry install
   

2. Or just run this:

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

Using uv:

1. In your pyproject.toml file, add:

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

Then run:

uv sync

1. Or run this:

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

2. Or just run this:

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

Usage Examples

Basic Usage

# 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

# 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

# .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 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 is working as expected, please ensure that:

1. You write your code as per PEP8 requirements.
2. You write a UnitTest for each function/feature you include.
3. The CodeCoverage is 100%.
4. All UnitTests are passing.
5. MyPy is passing 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.