pydoctest

library0.2.1pypypi✓ verified 88d ago

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.

testing

pip install pydoctest

github ↗package ↗

INSTALL

IMPORT

SIG · PYDOCTEST

pydoctest

testingpythonv0.2.1

Install

1.6s avg

Import

—

Disk

16MB

Pass rate

10/ 10

Env Coverage10 / 10

glibc

3.9–3.13

musl

3.9–3.13

Install & Compatibility

Where this runs

tested against v0.2.1 · pip install

no network on importno background threads

Install × environment matrix

Each cell = how many times install + import succeeded across repeated harness runs. Partial = flaky.
glibc = Debian/Ubuntu slim · musl = Alpine Linux

musl

py 3.10–3.95 runs

installs and imports cleanly · install 0.0s · import 0.000s · 18.3MB

glibc

py 3.10–3.95 runs

installs and imports cleanly · install 1.6s · import 0.000s · 19MB

16MB installed

● package 16MB

Code

Verified usage

Verified import paths — ran on the pinned version, not inferred.

pydoctest

✓ import pydoctest

✗ from pydoctest import pydoctest

pydoctest is the top-level module, not a submodule.

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)

pydoctest --version

Debug

Known issues

gotchaSupports 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.

affects: all

breakingVersion 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.

affects: >=0.1.18

deprecatedThe '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.

affects: >=0.1.17

Errors

Common errors & fixes

pydoctest.exceptions.ValidationError: No parser found for file

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.

TypeError: 'NoneType' object is not iterable

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.

Upgrade

Version history

0.2.1latest on PyPI · released Aug 28, 2024

Audit

Dependencies

No dependency data recorded yet.

Agent activity

12 hits · last 30 days

node

OpenAI (training)

Resources

githubhttps://github.com/jepperaskdk/pydoctest ↗

packagehttps://pypi.org/project/pydoctest/ ↗