pydoctest

0.2.1 verified Fri May 01 auth: no python

pydoctest is a tool to validate that Python docstrings (reStructuredText, Google, or NumPy style) match the actual function and method signatures. It checks type annotations in docstrings against the real types, flagging mismatches. Current version 0.2.1, supports Python >=3.6, and is in active maintenance mode with periodic updates.

pip install pydoctest

Common errors

error pydoctest.exceptions.ValidationError: No parser found for file ↓

cause The file has a docstring style that pydoctest does not recognize.

fix

Ensure docstrings are in reStructuredText, Google, or NumPy style. If custom, provide a custom parser.

error TypeError: 'NoneType' object is not iterable ↓

cause Occurs when run() is called with no files matching the include_paths pattern.

fix

Verify that include_paths point to existing Python files with .py extension.

Warnings

gotcha Supports only reStructuredText, Google, and NumPy styles. Other docstring formats will be ignored or cause false negatives. ↓

fix Use one of the supported styles; check documentation for style detection.

breaking Version 0.1.18 removed support for the '(..., optional)' syntax in Google-style docstrings. Now you must use Optional[X] in both signature and docstring. ↓

fix Update docstrings to use Optional[X] explicitly instead of '(optional)' marker.

deprecated The 'exclude' parameter in run() is deprecated in favor of 'exclude_paths' since 0.1.17. ↓

fix Use exclude_paths instead of exclude in function calls and CLI.

Imports

pydoctest
wrong
```
from pydoctest import pydoctest
```
correct
```
import pydoctest
```
pydoctest is the top-level module, not a submodule.

Quickstart

Basic usage: call pydoctest.run() to validate all Python files in cwd, or specify paths.

import pydoctest

# Run on current directory recursively
result = pydoctest.run()
print(result)
# Or run on specific file
result = pydoctest.run(include_paths=['example.py'])
print(result)