Check Python signature params for proper documentation
docsig is a Python documentation linter that ensures function and method signature parameters are properly documented in docstrings. It supports multiple docstring formats including reStructuredText (Sphinx), NumPy, and Google styles.
Maintain accurate and up-to-date Python documentation by automatically checking that all parameters in function signatures match their docstring documentation. Use docsig as a standalone tool, integrate it with flake8, or add it as a pre-commit hook to catch documentation issues before they reach your repository. docsig is also available as a plugin for PyCharm, VS Code, and Neovim, documented here
Installation
$ pip install docsigUsage
Commandline
usage: docsig [-h] [-V] [-l] [-n] [-v] [--check-class | --check-class-constructor]
[--check-dunders] [--check-nested] [--check-overridden]
[--check-property-returns] [--check-protected]
[--check-protected-class-methods] [--ignore-args] [--ignore-kwargs]
[--ignore-no-params] [-d LIST] [-t LIST] [-e PATTERN] [-E PATH [PATH ...]]
[-i] [-s STR]
[path ...]
Check signature params for proper documentation
positional arguments:
path directories or files to check
options:
-h, --help show this help message and exit
-V, --version show program's version number and exit
-l, --list-checks display a list of all checks and their messages
-n, --no-ansi disable ansi output
-v, --verbose increase output verbosity
--check-class check class docstrings
--check-class-constructor
check __init__ methods
--check-dunders check dunder methods
--check-nested check nested functions and classes
--check-overridden check overridden methods
--check-property-returns
check property return values
--check-protected check protected functions and classes
--check-protected-class-methods
check public methods belonging to protected classes
--ignore-args ignore args prefixed with an asterisk
--ignore-kwargs ignore kwargs prefixed with two asterisks
--ignore-no-params ignore docstrings where parameters are not documented
-d LIST, --disable LIST
comma separated list of rules to disable
-t LIST, --target LIST
comma separated list of rules to target
-e PATTERN, --exclude PATTERN
regular expression of files or dirs to exclude from checks
-E PATH [PATH ...], --excludes PATH [PATH ...]
path glob patterns to exclude from checks
-i, --include-ignored
check files even if they match a gitignore pattern
-s STR, --string STR string to parse instead of filesOptions can also be configured with the pyproject.toml file
[tool.docsig]
check-dunders = false
check-overridden = false
check-protected = false
disable = [
"SIG101",
"SIG102",
"SIG402",
]
target = [
"SIG202",
"SIG203",
"SIG201",
]Configuration options can be found here or see the full JSON schema
You can validate your docsig configuration with validate-pyproject
Flake8
docsig can also be used as a flake8 plugin. Install flake8 and ensure your installation has registered docsig
$ flake8 --version
7.3.0 (docsig: 0.91.4, mccabe: 0.7.0, pycodestyle: 2.14.0, pyflakes: 3.4.0) CPython 3.10.19 on DarwinAnd now use flake8 to lint your files
$ flake8 example.py
example.py:1:1: SIG202 includes parameters that do not exist (params-do-not-exist) 'function'With flake8 the pyproject.toml config will still be the base config, though the ini files flake8 gets its config from will override the pyproject.toml config. For flake8 all args and config options are prefixed with sig to avoid any potential conflicts with other plugins
[flake8]
sig-check-dunders = true
sig-check-overridden = true
sig-check-protected = trueAPI
>>> from docsig import docsig>>> string = '''
... def function(a, b, c) -> None:
... """Docstring summary.
...
... :param a: Description of a.
... :param b: Description of b.
... :param c: Description of c.
... """
... '''
>>> docsig(string=string, no_ansi=True)
0>>> string = '''
... def function(a, b) -> None:
... """Docstring summary.
...
... :param a: Description of a.
... :param b: Description of b.
... :param c: Description of c.
... """
... '''
>>> docsig(string=string, no_ansi=True)
2 in function
SIG202: includes parameters that do not exist (params-do-not-exist)
1A full list of checks can be found here
Message Control
Classes
pre-commit
docsig can be used as a pre-commit hook
It can be added to your .pre-commit-config.yaml as follows:
Standalone
repos:
- repo: https://github.com/jshwi/docsig
rev: v0.91.4
hooks:
- id: docsig
args:
- "--check-class"
- "--check-dunders"
- "--check-overridden"
- "--check-protected"or integrated with flake8
repos:
- repo: https://github.com/PyCQA/flake8
rev: "7.3.0"
hooks:
- id: flake8
additional_dependencies:
- docsig==0.91.4
args:
- "--sig-check-class"
- "--sig-check-dunders"
- "--sig-check-overridden"
- "--sig-check-protected"Versioning
docsig follows semantic versioning, and most releases are patches; read about the versioning policy here
Contributing
If you are interested in contributing to docsig, please read about contributing here
1 maintainer
Download files
Download the file for your platform. If you're not sure which to choose, learn more about installing packages.
Source Distribution
Built Distribution
Filter files by name, interpreter, ABI, and platform.
If you're not sure about the file name format, learn more about wheel file names.
Copy a direct link to the current filters
File details
Details for the file docsig-0.91.4.tar.gz.
File metadata
- Download URL: docsig-0.91.4.tar.gz
- Upload date:
- Size: 47.7 kB
- Tags: Source
- Uploaded using Trusted Publishing? No
- Uploaded via:
poetry/2.4.1 CPython/3.10.19 Darwin/25.5.0
File hashes
| Algorithm | Hash digest | |
|---|---|---|
| SHA256 |
c22c154c824b6f763834aee9e38fda85b4ca03f3e8030cee89ba83e2f57cb08e
|
|
| MD5 |
27772141b7e74536f0eea30877f46a6b
|
|
| BLAKE2b-256 |
77bf327ccafa9b9defb1c46baaf1194a352116fcac4b95fa897df0bb25913f7f
|
File details
Details for the file docsig-0.91.4-py3-none-any.whl.
File metadata
- Download URL: docsig-0.91.4-py3-none-any.whl
- Upload date:
- Size: 54.1 kB
- Tags: Python 3
- Uploaded using Trusted Publishing? No
- Uploaded via:
poetry/2.4.1 CPython/3.10.19 Darwin/25.5.0
File hashes
| Algorithm | Hash digest | |
|---|---|---|
| SHA256 |
96aaa38c3d446affbfb5eff67449983e5958c8fdcf79d362e37157c67358d68f
|
|
| MD5 |
2ad700473dea71efe96a92366fbdd4e4
|
|
| BLAKE2b-256 |
664872e640ca88abcf88143508eaa93de206029c124d4e2bc8818b31f9bda36d
|
