pydocstyle

Analyze a Python script or all the Python scripts in a specific directory

$ pydocstyle [file.py|path/to/directory]

$ pydocstyle [[-e|--explain]] [file.py|path/to/directory]

$ pydocstyle [[-d|--debug]] [file.py|path/to/directory]

$ pydocstyle --count [file.py|path/to/directory]

$ pydocstyle --config [path/to/config_file] [file.py|path/to/directory]

$ pydocstyle --ignore [D101,D2,D107,...] [file.py|path/to/directory]

$ pydocstyle --convention [pep257|numpy|google] [file.py|path/to/directory]

pydocstyle [OPTIONS] [PATHS...]

--version, -v
    Show program's version number and exit.

--help, -h
    Show help message and exit.

--quiet, -q
    Suppress file names in output, print only error codes.

--select=CODES, -s CODES
    Specify specific error codes to report.

--ignore=CODES, -i CODES
    Specify specific error codes to ignore.

--add-select=CODES
    Add error codes to report to existing selections.

--add-ignore=CODES
    Add error codes to ignore to existing ignores.

--convention=NAME
    Choose a docstring convention (e.g., pep257, numpy).

--config=PATH
    Specify an alternative configuration file path.

--count
    Print the total number of errors found.

--explain=CODE
    Show a detailed explanation for an error code.

--show-source
    Display the source code line for each error.

--match=PATTERN
    Check files whose base names match the pattern (default: *.py).

--match-dir=PATTERN
    Check directories whose base names match the pattern (default: .*).

--exclude=PATTERN
    Exclude files or directories matching the pattern.

--ignore-decorators=PATTERN
    Ignore functions/methods decorated by a matching pattern.

PATHS...
    One or more files or directories to check. If omitted, checks the current directory.

pydocstyle is a static analysis tool for checking Python code against PEP 257, the Python Docstring Conventions. It helps developers ensure their docstrings adhere to a consistent style and structure, improving code readability and maintainability. The tool scans Python files and reports violations such as missing docstrings, incorrect formatting, or non-standard content. While it primarily focuses on PEP 257, it also supports conventions like NumPy-style docstrings. By integrating pydocstyle into development workflows, teams can automate the enforcement of docstring standards, making documentation more reliable and easier to understand.

pydocstyle strictly enforces PEP 257 by default, which may not align perfectly with all project docstring styles. Users often need to configure it with specific select or ignore codes to fit their needs. It only checks docstring conventions and does not perform general Python code style or syntax checks. Large codebases might require fine-tuning of configuration to avoid excessive noise.

pydocstyle can be configured via pyproject.toml (recommended), setup.cfg, .pydocstylerc, or .pydocstylerc.ini files. These files allow users to define default options like ignored error codes, selected conventions, and file/directory patterns.

The command returns a non-zero exit code if any docstring style violations are found, making it suitable for integration into CI/CD pipelines. An exit code of 0 indicates no errors.

pydocstyle was originally developed as pep257. It was later renamed to pydocstyle to avoid confusion with PEP 257 itself and to better reflect its broader capabilities beyond just the PEP 257 standard, such as support for NumPy docstring conventions. The renaming aimed to signify its evolution into a more flexible and comprehensive docstring linter for Python.

flake8(1), pycodestyle(1), pylint(1)