pydocformatter 0.2.0

A Python annotation formatter for line-wrapping and formatting python comments and docstrings

pydocformatter

pydocformatter is a fork of pyformatter, and provides Python formatting tools that automatically format your docstrings and comments according to configurable style guidelines. It consists of two formatters:

• pydocfmt: Formats Python docstrings with support for Google-style docstrings
• pycommentfmt: Formats Python comments to ensure proper line length and readability

---

Key Features

pydocfmt

• Google-style docstring formatting: Complete support for Google docstring conventions
• Multi-line summary handling: Intelligently formats long summaries that span multiple lines
• Smart section parsing: Properly handles Args, Returns, Raises, Examples, and other sections
• Code block preservation: Maintains formatting within Examples sections with automatic fencing
• Type annotation support: Handles parameter type annotations gracefully
• Blank line management: Ensures proper spacing between summary, description, and sections

pycommentfmt

• Intelligent comment wrapping: Respects line length while preserving meaning
• Inline vs block comment handling: Different formatting strategies for different comment types
• Special comment preservation: Maintains pylint, mypy, and other tool directives
• Smart spacing: Ensures consistent spacing between code and comments

Key Improvements over pyformatter

• Project architecture updates and bug fixes

---

Table of Contents

• Key Features
• Installation
• Quick Start
• Command Line Usage
  • pydocfmt
  • pycommentfmt
• Configuration
• Examples
• Integration
  • Pre-commit
  • Editor Integration
• Security
• Contributing
• License

---

Installation

Install pydocformatter via pip:

pip install pydocformatter

Or install from source:

git clone https://github.com/pallgeuer/pydocformatter.git
cd pydocformatter
pip install -e .

---

Quick Start

Format all Python files in your project:

# Format docstrings
pydocfmt src/

# Format comments  
pycommentfmt src/

# Check formatting without making changes
pydocfmt --check src/
pycommentfmt --check src/

---

Command Line Usage

pydocfmt

Format Python docstrings with intelligent Google-style docstring support.

pydocfmt [OPTIONS] [FILES/DIRECTORIES]

Options:

• --line-length INTEGER: Maximum line length for docstrings (default: 88)
• --check: Check if files are formatted correctly without modifying them
• --include TEXT: Regex pattern for files to include
• --exclude TEXT: Regex pattern for files to exclude
• --help: Show help message and exit

Examples:

# Format specific files
pydocfmt myfile.py another_file.py

# Format entire directory
pydocfmt src/

# Check formatting without changes
pydocfmt --check src/

# Custom line length
pydocfmt --line-length 100 src/

# Include/exclude patterns
pydocfmt --include ".*\.py$" --exclude "test_.*\.py$" src/

pycommentfmt

Format Python comments to ensure proper line length and readability.

pycommentfmt [OPTIONS] [FILES/DIRECTORIES]

Options:

• --line-length INTEGER: Maximum line length for comments (default: 88)
• --check: Check if files are formatted correctly without modifying them
• --include TEXT: Regex pattern for files to include
• --exclude TEXT: Regex pattern for files to exclude
• --help: Show help message and exit

Examples:

# Format specific files
pycommentfmt myfile.py

# Format entire directory
pycommentfmt src/

# Check formatting without changes
pycommentfmt --check src/

# Custom line length
pycommentfmt --line-length 79 src/

---

Configuration

pydocformatter can be configured via pyproject.toml:

[tool.pydocfmt]
line_length = 88
exclude = '(^|/)(\.github|\.eggs|\.git|\.hg|\.mypy_cache|\.tox|\.venv|htmlcov|__pycache__|_build|buck-out|build|dist|tests/data)(/|$)'

[tool.pycommentfmt]
line_length = 88
exclude = '(^|/)(\.github|\.eggs|\.git|\.hg|\.mypy_cache|\.tox|\.venv|htmlcov|__pycache__|_build|buck-out|build|dist|tests/data)(/|$)'

Configuration Options:

• line_length: Maximum line length (default: 88)
• exclude: Regex pattern for files/directories to exclude

---

Examples

Before and After: pydocfmt

Before:

def calculate_mean(numbers):
    """Calculate the arithmetic mean of a list of numbers.
    
    This function calculates the arithmetic mean of a list of numbers and returns the result as a float value."""
    return sum(numbers) / len(numbers)

After:

def calculate_mean(numbers):
    """Calculate the arithmetic mean of a list of numbers.
    
    This function calculates the arithmetic mean of a list of numbers and returns the
    result as a float value.
    """
    return sum(numbers) / len(numbers)

Before and After: pycommentfmt

Before:

# This is a very long comment that exceeds the line length limit and should be wrapped to multiple lines for better readability
x = 42

After:

# This is a very long comment that exceeds the line length limit and should be
# wrapped to multiple lines for better readability
x = 42

---

Integration

Pre-commit

Add pydocformatter to your .pre-commit-config.yaml:

repos:
  - repo: https://github.com/pallgeuer/pydocformatter
    rev: v0.2.0  # Use the ref you want to point at
    hooks:
      - id: pydocfmt
        args: [--line-length=88]
      - id: pycommentfmt
        args: [--line-length=88]

Available hooks:

• pydocfmt: Format docstrings (modifies files)
• pydocfmt-check: Check docstring formatting (read-only)
• pycommentfmt: Format comments (modifies files)
• pycommentfmt-check: Check comment formatting (read-only)

Common configurations:

# Basic usage
- id: pydocfmt
- id: pycommentfmt

# Custom line length
- id: pydocfmt
  args: [--line-length=100]

# Check only (for CI)
- id: pydocfmt-check
- id: pycommentfmt-check

# With file exclusions
- id: pydocfmt
  args: [--exclude=tests/.*]

Editor Integration

pydocformatter works great with:

• VS Code: Use with the Python extension
• PyCharm: Configure as an external tool
• Vim/Neovim: Integrate with formatting plugins

---

Why pydocformatter?

• Uncompromising: Consistent formatting across your entire codebase
• Fast: Efficiently processes large codebases
• Configurable: Adapt to your team's style preferences
• Reliable: Extensively tested with comprehensive test suite
• Simple: Easy to integrate into existing workflows

---

Security

For general security best practices when using pydocformatter:

• Always review changes made by pydocformatter before committing
• Keep pydocformatter updated to the latest version
• When processing untrusted code, consider running pydocformatter in an isolated environment

---

Contributing

Contributions are welcome! We appreciate bug reports, feature requests, documentation improvements, and code contributions.

For detailed information on how to contribute, please see our Contributing Guide.

Quick Start for Contributors:

1. Fork the repository and clone your fork
2. Set up the development environment: pip install -e . --dependency-groups dev
3. Install pre-commit hooks: pre-commit install
4. Make your changes and add tests
5. Run the test suite: python -m unittest discover -s tests -v
6. Submit a pull request

For bug reports and feature requests, please open an issue.

---

License

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

---

Acknowledgments

Inspired by the excellent work of:

• pyformatter - Forked
• Black - The uncompromising Python code formatter
• isort - A Python utility to sort imports
• docformatter - Formats docstrings to follow conventions

---