pydoclint

library0.8.3pypypiunverified

PyDocLint is a fast Python docstring linter that verifies whether a function's docstring sections (arguments, returns, yields, and raises) accurately match its signature and implementation. It currently supports NumPy, Google, and Sphinx docstring styles, running significantly faster than older alternatives. The library is actively maintained with frequent releases, and its current version is 0.8.3.

testing web-framework

pip install pydoclint

github ↗package ↗

INSTALL

IMPORT

SIG · PYDOCLINT

pydoclint

testingpythonv0.8.3

harness data pending

Install & Compatibility

Where this runs

No compatibility data collected yet for this library.

Code

Verified usage

To get started, install pydoclint and run it as a command-line tool on your Python files or directories. Configuration can be managed via a `pyproject.toml` file or command-line arguments.

# my_module.py def my_function(arg1: int, arg2: str) -> None: """ A sample function. Parameters ---------- arg1 : int The first argument. arg2 : str The second argument. """ print(f'{arg1}, {arg2}') # pyproject.toml [tool.pydoclint] style = "numpy" check-arg-order = true # Terminal # Run pydoclint on a file or folder pydoclint my_module.py # Or with a config file pydoclint --config=pyproject.toml my_module.py # Or as a pre-commit hook (add to .pre-commit-config.yaml) # - repo: https://github.com/jsh9/pydoclint # rev: <latest_tag> # e.g., 0.8.3 # hooks: # - id: pydoclint # args: ["--config=pyproject.toml"]

pydoclint --version

Debug

Known issues

breakingPython 3.9 support was dropped in version 0.7.4. Users on older Python versions will need to upgrade their Python environment to at least 3.10 to use pydoclint 0.7.4 and newer.

fix

Upgrade Python to 3.10 or higher, or pin pydoclint to a version older than 0.7.4.

affects: >=0.7.4

gotchaConfiguration file validation was enhanced in version 0.7.4. Previously, malformed `pyproject.toml` or other config files might have been silently ignored or partially applied. Now, invalid configurations might lead to errors.

fix

Review `pyproject.toml` or other config files against the official documentation to ensure correct syntax and options.

affects: >=0.7.4

gotchaEarlier versions (prior to approximately 0.7.0) primarily supported NumPy-style docstrings, with Google and Sphinx style support added later. Users expecting full support for Google or Sphinx styles should ensure they are on a recent version.

fix

Upgrade pydoclint to the latest version (0.7.0 or newer) for comprehensive Google and Sphinx docstring style support.

affects: <0.7.0

gotchaPyDocLint performs static analysis and expects exact matches for type hints between docstrings and function signatures. It does not recognize conventions like 'int, optional' for `Optional[int]`, requiring verbatim matching. Also, non-standard Pythonic naming (e.g., renaming `classmethod`) might lead to unexpected linting results.

fix

Ensure type hints in docstrings precisely mirror those in function signatures. Adhere to standard Python naming conventions for methods and parameters.

affects: all

Errors

Common errors & fixes

DOC103: Docstring arguments are different from function arguments.

This error occurs when the arguments listed in the function's docstring do not exactly match the arguments in the function's signature, or when there are subtle formatting issues (e.g., missing a space after an argument name and colon in NumPy style, or missing a preceding summary in Google style).

fix

Ensure that argument names, their order, and their presence in the docstring's argument section precisely reflect the function's signature. For NumPy style, ensure a space exists after the argument name and before the colon (e.g., `arg : type`). For Google style, ensure the 'Args:' section is preceded by a summary if one is used.

DOC101: Docstring contains fewer arguments than in function signature.

This violation indicates that the function's docstring is missing documentation for one or more arguments present in the function's definition.

fix

Add documentation for all missing arguments in the function's docstring to match the function signature.

ImportError: cannot import name 'DocstringAttr' from 'docstring_parser.common'

This Python import error typically arises from a version incompatibility or conflict with the `docstring-parser` library, which `pydoclint` depends on, usually after an upgrade.

fix

Try reinstalling `pydoclint` and its dependencies to ensure compatible versions are used, or explicitly upgrade/downgrade `docstring-parser` to a version known to be compatible with your `pydoclint` version (e.g., `pip install --upgrade pydoclint` or `pip install docstring-parser==<compatible_version>`).

'pydoclint' is not recognized as an internal or external command

This common operating system error means the `pydoclint` executable cannot be found in the system's PATH environment variable, usually because it was not installed correctly or the installation directory is not on the PATH.

fix

Ensure `pydoclint` is installed in your Python environment (`pip install pydoclint`). If it is, verify that the Python scripts directory (e.g., `Scripts` on Windows, `bin` on Linux/macOS within your virtual environment) is included in your system's PATH. Activating your virtual environment before running the command often resolves this.

Upgrade

Version history

0.8.3latest on PyPI · released Nov 26, 2025

Audit

Dependencies

pythonrequiredRequires Python 3.10 or newer.

flake8optionalRequired if using pydoclint as a Flake8 plugin.

Agent activity

6 hits · last 30 days

node

Resources

githubhttps://github.com/jsh9/pydoclint ↗

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