Docformatter

A comprehensive Python docstring formatter that automatically formats docstrings to follow PEP 257 conventions. Docformatter handles multi-line docstring formatting, triple quote consistency, blank line management, and trailing whitespace removal while maintaining compatibility with Black formatter when using the --black option.

Package Information

• Package Name: docformatter
• Language: Python
• Installation: pip install docformatter
• Optional Installation: pip install docformatter[tomli] (for Python < 3.11 with pyproject.toml support)

Core Imports

import docformatter

For programmatic usage:

from docformatter import Formatter, Configurater, FormatResult

Access to utility functions:

from docformatter import (
    find_shortest_indentation,
    normalize_summary,
    split_summary_and_description,
    # And other string/syntax functions
)

Basic Usage

Command-Line Usage

# Format files in-place
docformatter --in-place file.py

# Format recursively with Black compatibility
docformatter --black --in-place --recursive .

# Check formatting without making changes
docformatter --check --diff file.py

# Format with custom line length
docformatter --wrap-summaries 88 --wrap-descriptions 88 file.py

Programmatic Usage

import sys
from docformatter import Formatter, Configurater

# Configure docformatter
args = ['--in-place', 'example.py']
configurator = Configurater(args)
configurator.do_parse_arguments()

# Create formatter instance
formatter = Formatter(
    configurator.args,
    stderror=sys.stderr,
    stdin=sys.stdin,
    stdout=sys.stdout
)

# Format files
result = formatter.do_format_files()
print(f"Formatting completed with exit code: {result}")

Architecture

Docformatter uses a modular architecture with distinct responsibilities:

• Formatter: Core docstring formatting engine that processes Python source files
• Configurater: Command-line and configuration file management
• Encoder: File encoding detection and line ending handling
• String Functions: Text manipulation utilities for docstring processing
• Syntax Functions: Advanced docstring syntax analysis and formatting rules
• Utility Functions: File discovery and range checking helpers

The formatting process tokenizes Python source code, identifies docstring locations, applies PEP 257 formatting rules, and reconstructs the source while preserving all non-docstring code.

Capabilities

Core Formatting

Main docstring formatting functionality including the Formatter class for processing files and individual docstrings, with support for various formatting options and compatibility modes.

class Formatter:
    def __init__(self, args, stderror, stdin, stdout): ...
    def do_format_files(self) -> int: ...
    def do_format_standard_in(self, parser): ...

class FormatResult:
    ok = 0
    error = 1
    interrupted = 2
    check_failed = 3

Core Formatting

Configuration Management

Configuration handling for command-line arguments and configuration files, supporting pyproject.toml, setup.cfg, and tox.ini configuration sources.

class Configurater:
    def __init__(self, args: List[Union[bool, int, str]]): ...
    def do_parse_arguments(self) -> None: ...
    
    parser: argparse.ArgumentParser
    args: argparse.Namespace
    flargs_dct: Dict[str, Union[bool, float, int, str]]
    configuration_file_lst: List[str]

Configuration Management

String Processing

Text manipulation utilities for docstring processing including indentation detection, line normalization, summary formatting, and text splitting operations.

def find_shortest_indentation(lines: List[str]) -> str: ...
def normalize_summary(summary: str, noncap: Optional[List[str]] = None) -> str: ...
def split_summary_and_description(contents): ...
def normalize_line(line: str, newline: str) -> str: ...
def split_first_sentence(text): ...

String Processing

Syntax Analysis

Advanced docstring syntax analysis and formatting for field lists, code blocks, URLs, and various docstring styles including Sphinx, Epytext, Google, and NumPy formats.

def do_find_field_lists(text: str, style: str) -> List[Tuple[int, int]]: ...
def wrap_description(text, indentation, wrap_length, force_wrap, strict, rest_sections, style="sphinx"): ...
def is_some_sort_of_list(text, strict=True): ...
def do_wrap_field_lists(text: str, field_idx: List[Tuple[int, int]], lines: List[str], text_idx: int, indentation: str, wrap_length: int) -> Tuple[List[str], int]: ...

Syntax Analysis

File I/O and Encoding

File encoding detection, line ending handling, and file opening utilities for robust text file processing across different encodings and platforms.

class Encoder:
    def __init__(self): ...
    def do_detect_encoding(self, filename) -> None: ...
    def do_find_newline(self, source: List[str]) -> str: ...
    def do_open_with_encoding(self, filename, mode: str = "r"): ...
    
    CR: str
    LF: str  
    CRLF: str
    DEFAULT_ENCODING: str

File I/O and Encoding

Configuration Options

Docformatter supports extensive configuration through command-line arguments and configuration files:

Format Control

• --black: Black formatter compatibility mode
• --wrap-summaries LENGTH: Summary line wrapping length
• --wrap-descriptions LENGTH: Description wrapping length
• --force-wrap: Force wrapping even if messy
• --make-summary-multi-line: Convert single-line to multi-line
• --close-quotes-on-newline: Close quotes positioning

Content Control

• --blank: Add blank line after description
• --pre-summary-newline: Add newline before summary
• --pre-summary-space: Add space after opening quotes
• --non-cap WORDS: Words not to capitalize in summary

Processing Control

• --in-place: Modify files in place
• --check: Check formatting without changes
• --diff: Show differences
• --recursive: Process directories recursively
• --exclude PATTERNS: Exclude files/directories

Style Control

• --style STYLE: Docstring style (sphinx, epytext)
• --non-strict: Relaxed reST syntax checking
• --range START END: Process specific line ranges
• --docstring-length MIN MAX: Process specific docstring lengths

Version Information

__version__: str  # "1.7.7"

Error Handling

Docformatter handles various error conditions gracefully:

• Encoding Errors: Automatic encoding detection with fallback to latin-1
• Syntax Errors: Skips malformed Python files with error reporting
• File Access: Handles permission and file not found errors
• Keyboard Interrupt: Clean exit with interrupted status code
• Configuration Errors: Clear error messages for invalid arguments

Integration Features

• Pre-commit Hooks: Native pre-commit hook support via .pre-commit-hooks.yaml
• CI/CD Integration: Check mode returns appropriate exit codes for automation
• Black Compatibility: --black option ensures compatibility with Black formatter
• Configuration Files: Support for pyproject.toml, setup.cfg, and tox.ini
• Multiple Python Versions: Compatible with Python 3.9-3.12 and PyPy