pydocstyle

pydocstyle is a command-line static analysis tool that checks Python docstrings for compliance with documentation conventions, most notably PEP 257. It reports missing docstrings, malformed summaries, incorrect quoting, and other style issues so teams can keep their inline documentation consistent and complete.

pydocstyle supports multiple convention profiles (PEP 257, NumPy, and Google), configurable rule selection, and per-file ignores. Note that the project is now officially deprecated, with its maintainers recommending Ruff as a modern, actively developed replacement that offers full parity with pydocstyle’s checks.

What You Get

• A pydocstyle CLI that lints docstrings across a codebase
• Convention profiles for PEP 257, NumPy, and Google docstring styles
• A catalog of numbered D-code violations you can select or ignore
• Configuration via pyproject.toml, setup.cfg, or CLI flags
• An importable checker API for embedding docstring analysis

Common Use Cases

• Enforcing consistent docstring style across a Python project
• Failing CI when public functions lack documentation
• Adopting a specific convention such as NumPy or Google docstrings
• Auditing an existing codebase for undocumented APIs

Under The Hood

Architecture - pydocstyle parses source with its own parser.py into definitions (modules, classes, functions), then checker.py runs each registered check against their docstrings, emitting violations.py D-code errors. config.py resolves convention profiles and per-file inheritance of settings, cli.py drives the command-line entry point, and wordlists.py plus snowballstemmer support imperative-mood and spelling-related checks.

Tech Stack - Pure Python supporting Python >= 3.6, packaged with Poetry. Its only required runtime dependency is snowballstemmer, with optional tomli for TOML config on older interpreters, keeping the install lightweight.

Code Quality - The codebase is small, well-organized by concern (parser, checker, config, violations), and historically well tested. However, the project is officially deprecated and no longer actively maintained, which is reflected in its low development-activity health score.

API Design - As a CLI the developer experience is straightforward: run pydocstyle over a path, pick a convention, and select or ignore specific D codes. Configuration through pyproject.toml/setup.cfg is familiar to Python developers. The importable checker allows programmatic use, though most users invoke it as a linter in pre-commit or CI.