Skip to main content

docsig logo

License PyPI Jetbrains Plugin VS Code Extension Version CI Build Build CodeQL pre-commit.ci status codecov.io readthedocs.org python3.11 Black isort pylint Security Status

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 docsig

Usage

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, --disable LIST    comma separated list of rules to disable
  -t, --target LIST     comma separated list of rules to target
  -e, --exclude PATTERN
                        regular expression of files or dirs to exclude from checks
  -E, --excludes PATH [PATH ...]
                        path glob patterns to exclude from checks
  -i, --include-ignored
                        check files even if they match a gitignore pattern
  -s, --string STR      string to parse instead of files

Options 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.97.0, mccabe: 0.7.0, pycodestyle: 2.14.0, pyflakes: 3.4.0) CPython 3.11.14 on Darwin

And 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 configuration comes from flake8’s own ini files or commandline options; the plugin does not read pyproject.toml. 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 = true

API

>>> 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)
1

A full list of checks can be found here

Message Control

Documentation on message control

Classes

Documenting 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.97.0
    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.97.0
        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

Metadata

Release files for docsig 0.97.0

For a detailed explanation of source distributions (sdists) and built distributions (wheels), please see the package formats documentation.

Source distribution (sdist)

Source distribution for docsig 0.97.0
File Size Uploaded Provenance Actions
docsig-0.97.0.tar.gz 52.4 kB Without provenance Details for docsig-0.97.0.tar.gz

Built distribution (wheel)

Table of built distributions (wheels) for docsig 0.97.0
File Interpreter ABI Platform Actions
docsig-0.97.0-py3-none-any.whl Python 3 none any Details for docsig-0.97.0-py3-none-any.whl

Total release size: 110.6 kB

Release files / docsig-0.97.0.tar.gz

Download URL docsig-0.97.0.tar.gz
Size 52.4 kB
Tags Source
SHA-256 checksum
How to use checksums
975eff829928277e57e1a135ecae9093725ba402838cfa9b78ec6bbabc733459
BLAKE2b-256 checksum
How to use checksums
4d23e243424e24dea192a84bd50c2f809fcc80b96a2a717d0d7e125bf2ad8f32
Upload date
Uploaded using Trusted Publishing?
What is trusted publishing?
No
Uploaded via poetry/2.5.1 CPython/3.15.0 Darwin/25.6.0

Release files / docsig-0.97.0-py3-none-any.whl

Download URL docsig-0.97.0-py3-none-any.whl
Size 58.2 kB
Tags Python 3
SHA-256 checksum
How to use checksums
04ff8559ee7f40415728e47a097cedc3f18598632f472424406278a826cfbd70
BLAKE2b-256 checksum
How to use checksums
a32d06b20b2a6e8a81eb8f70744a5e29ec377e3af8c8dbaad6148add05e3075d
Upload date
Uploaded using Trusted Publishing?
What is trusted publishing?
No
Uploaded via poetry/2.5.1 CPython/3.15.0 Darwin/25.6.0

Security for docsig 0.97.0

Provenance

Provenance describes where a file came from. On PyPI, provenance is shared via attestations, which provide a verifiable record of the build or publishing details. View details, limitations and caveats.

No provenance found

None of the files in this release were uploaded with provenance metadata.

A note on package security

PyPI is a repository for distributing packages, not a service for auditing them. While third-party security researchers and our staff do their best to detect and remove malicious packages, PyPI cannot guarantee the quality, security or suitability of any given package.

To learn more about protecting yourself from malicious actors, visit our package security documentation.

Release history Release notifications | RSS feed

This release

0.97.0 This release

2 release files No provenance

Anthropic, PBC Visionary sponsor Bloomberg Visionary sponsor Hudson River Trading Visionary sponsor Meta Visionary sponsor NVIDIA Visionary sponsor Microsoft Sustainability sponsor Depot Continuous Integration AWS Cloud computing and Security Sponsor Datadog Monitoring Fastly CDN Google Download Analytics Sentry Error logging StatusPage Status page