pep257

A Python static analysis tool for checking docstring conventions and style compliance with PEP 257. The tool analyzes Python source code to identify missing or improperly formatted docstrings and provides configurable checking frameworks that can be extended with custom validation rules.

Package Information

• Package Name: pep257
• Language: Python
• Installation: pip install pep257
• Python Compatibility: 2.6, 2.7, 3.2+, PyPy

Core Imports

import pep257

Common usage patterns:

from pep257 import check, PEP257Checker

Basic Usage

import pep257

# Check files for PEP 257 compliance
errors = list(pep257.check(['my_module.py']))
for error in errors:
    print(error)

# Check with specific error code selection
errors = list(pep257.check(['my_module.py'], select=['D100', 'D101']))

# Check while ignoring specific error codes  
errors = list(pep257.check(['my_module.py'], ignore=['D203']))

Command-line usage:

# Basic usage
pep257 my_module.py

# With options
pep257 --explain --source my_module.py
pep257 --select=D100,D101 my_module.py
pep257 --ignore=D203 my_project/

Architecture

pep257 follows a modular architecture with distinct responsibilities:

• Parser System: Tokenizes and parses Python source code into an AST-like structure with Definition objects (Module, Class, Function, Method)
• Error Registry: Hierarchical error classification system with error groups (D1xx: Missing Docstrings, D2xx: Whitespace Issues, D3xx: Quote Issues, D4xx: Content Issues)
• Configuration System: Multi-level configuration parsing supporting CLI options, config files (setup.cfg, tox.ini, .pep257), and inheritance
• Checker Engine: PEP257Checker class that applies validation rules to parsed definitions and generates error reports

Capabilities

Error Checking and Validation

Main API for checking Python files against PEP 257 docstring standards. Provides the primary check() function and PEP257Checker class for programmatic validation.

def check(filenames, select=None, ignore=None):
    """Generate PEP 257 errors that exist in filenames iterable."""

class PEP257Checker:
    def check_source(self, source, filename):
        """Check source code string for docstring violations."""

Error Checking and Validation

Configuration System

Comprehensive configuration parsing system supporting CLI arguments and configuration files with inheritance. Handles error code selection, file matching patterns, and runtime options.

class ConfigurationParser:
    def parse(self):
        """Parse configuration from CLI and files."""
    
    def get_files_to_check(self):
        """Generate files and error codes to check."""

class RunConfiguration:
    """Configuration for runtime behavior."""

class CheckConfiguration:
    """Configuration for error checking."""

Configuration System

AST Parsing and Code Analysis

Parser system that converts Python source code into structured Definition objects representing modules, classes, functions, and methods with docstring extraction.

class Parser:
    def __call__(self, filelike, filename):
        """Parse Python source into Definition tree."""

class Definition:
    """Base class for all code definitions."""

class Module(Definition):
    """Represents a Python module."""

class Function(Definition):
    """Represents a function definition."""

class Class(Definition):
    """Represents a class definition."""

AST Parsing and Code Analysis

Error Categories

D1xx: Missing Docstrings

• D100: Missing docstring in public module
• D101: Missing docstring in public class
• D102: Missing docstring in public method
• D103: Missing docstring in public function
• D104: Missing docstring in public package
• D105: Missing docstring in magic method

D2xx: Whitespace Issues

• D200-D211: Various whitespace and formatting issues in docstrings

D3xx: Quote Issues

• D300-D302: Docstring quote style and encoding issues

D4xx: Content Issues

• D400-D402: Docstring content and style problems

Constants

__version__ = "0.7.0"
__all__ = ("check", "collect")  # Note: 'collect' function not implemented

# Return codes
NO_VIOLATIONS_RETURN_CODE = 0
VIOLATIONS_RETURN_CODE = 1
INVALID_OPTIONS_RETURN_CODE = 2

Exceptions

class AllError(Exception):
    """Exception for __all__ parsing errors."""

class IllegalConfiguration(Exception):
    """Exception for illegal configuration options."""