Use pip or easy_install:
pip install pydocstyle
Alternatively, you can use
pydocstyle.py source file
directly - it is self-contained.
Command Line Interface¶
Usage: pydocstyle [options] [<file|dir>...] Options: --version show program's version number and exit -h, --help show this help message and exit -e, --explain show explanation of each error -s, --source show source for each error -d, --debug print debug information -v, --verbose print status information --count print total number of errors to stdout --config=<path> use given config file and disable config discovery --match=<pattern> check only files that exactly match <pattern> regular expression; default is --match='(?!test_).*\.py' which matches files that don't start with 'test_' but end with '.py' --match-dir=<pattern> search only dirs that exactly match <pattern> regular expression; default is --match-dir='[^\.].*', which matches all dirs that don't start with a dot --ignore-decorators=<decorators> ignore any functions or methods that are decorated by a function with a name fitting the <decorators> regular expression; default is --ignore-decorators='' which does not ignore any decorated functions. Note: When using --match, --match-dir or --ignore-decorators consider whether you should use a single quote (') or a double quote ("), depending on your OS, Shell, etc. Error Check Options: Only one of --select, --ignore or --convention can be specified. If none is specified, defaults to `--convention=pep257`. These three options select the "basic list" of error codes to check. If you wish to change that list (for example, if you selected a known convention but wish to ignore a specific error from it or add a new one) you can use `--add-[ignore/select]` in order to do so. --select=<codes> choose the basic list of checked errors by specifying which errors to check for (with a list of comma- separated error codes or prefixes). for example: --select=D101,D2 --ignore=<codes> choose the basic list of checked errors by specifying which errors to ignore out of all of the available error codes (with a list of comma-separated error codes or prefixes). for example: --ignore=D101,D2 --convention=<name> choose the basic list of checked errors by specifying an existing convention. Possible conventions: pep257, numpy, google. --add-select=<codes> add extra error codes to check to the basic list of errors previously set by --select, --ignore or --convention. --add-ignore=<codes> ignore extra error codes by removing them from the basic list previously set by --select, --ignore or --convention.
When using any of the
--add-ignore command line flags, it is possible to pass a prefix for an
error code. It will be expanded so that any code beginning with that prefix
will match. For example, running the command
will ignore all docstring content issues as their error codes beginning with
“D4” (i.e. D400, D401, D402, D403, and D404).
|0||Success - no violations|
|1||Some code violations were found|
|2||Illegal usage - see error message|
pydocstyle supports ini-like and toml configuration files.
In order for
pydocstyle to use a configuration file automatically, it must
be named one of the following options.
When searching for a configuration file,
pydocstyle looks for one of the
file specified above in that exact order. ini-like configuration files must
[pydocstyle] section while toml configuration files must have a
[tool.pydocstyle] section. If a configuration file was not found,
pydocstyle keeps looking for one up the directory tree until one is found
or uses the default configuration.
toml configuration file support is only enabled if the
package is installed. You can ensure that this is the case by installing
pydocstyle[toml] optional dependency.
For backwards compatibility purposes, pydocstyle supports configuration
.pep257, as well as section header
these are considered deprecated and support will be removed in the next
Not all configuration options are available in the configuration files. Available options are:
See the Usage section for more information.
By default, when finding a configuration file,
pydocstyle tries to inherit
the parent directory’s configuration and merge them to the local ones.
The merge process is as follows:
- If one of
conventionwas specified in the child configuration - Ignores the parent configuration and set the new error codes to check. Otherwise, simply copies the parent checked error codes.
add-selectwere specified, adds or removes the specified error codes from the checked error codes list.
match-dirwere specified - use them. Otherwise, use the parent’s.
In order to disable this (useful for configuration files located in your repo’s
root), simply add
inherit=false to your configuration file.
If any of
convention were specified in
the CLI, the configuration files will take no part in choosing which error
codes will be checked.
match-dir will still take effect.
[pydocstyle] inherit = false ignore = D100,D203,D405 match = .*\.py
pydocstyle supports inline commenting to skip specific checks on
specific functions or methods. The supported comments that can be added are:
"# noqa"skips all checks.
"# noqa: D102,D203"can be used to skip specific checks. Note that this is compatible with skips from flake8, e.g.
# noqa: D102,E501,D203.
For example, this will skip the check for a period at the end of a function docstring:
>>> def bad_function(): # noqa: D400 ... """Omit a period in the docstring as an exception""" ... pass
Usage with the pre-commit git hooks framework¶
pydocstyle can be included as a hook for pre-commit. The easiest way to get
started is to add this configuration to your
- repo: https://github.com/pycqa/pydocstyle rev: 6.1.0 # pick a git hash / tag to point to hooks: - id: pydocstyle
See the pre-commit docs for how to customize this configuration.
Checked-in python files will be passed as positional arguments so no need to use
You can also use command line arguments instead of configuration files
to achieve the same effect with less files.
- id: pydocstyle args: - --ignore=D100,D203,D405 # or multiline - |- --select= D101, D2