DOCSEARCHbyAlgolia
Submit Docs

pydocstyle Documentation

repository·master·Indexed 22 days ago

https://github.com/pycqa/pydocstyle

pydocstyle is a static analysis tool used to check Python code for compliance with docstring conventions, specifically supporting most of PEP 257, as well as NumPy and Google style guides. It provides a CLI for checking files and directories, supports configuration via files like pyproject.toml or setup.cfg, and can be integrated into pre-commit workflows. Note that the project is officially deprecated in favor of Ruff.

Tokens
7.5K
Snippets
23
Records
38
Agent score
76%

What's inside pydocstyle

  1. What is pydocstyle

    master
    pydocstyle is a static analysis tool used to check compliance with Python docstring conventions. It supports most of the PEP 257 guidelines out of the box, though it is not a formal reference implementation. It is compatible with Python versions 3.7 through 3.11 (Python 3.6 compatibility is attempted but not tested).

  3. How publicity affects D1xx error reporting

    master

    The determination of whether a construct is public directly controls whether D1xx errors (missing docstrings) are reported:

    • Private Constructs: If a construct is determined to be private, pydocstyle will not report any D1xx errors for it or any of its children. For example, a method named bar inside a private class _Foo will not trigger a D102 error even if it lacks a docstring.
    • Docstring Content: While docstrings are optional for private constructs, if you do include a docstring in a private construct, pydocstyle may still report other non-D1xx errors based on your style guide requirements.

  4. How publicity is determined for D1xx errors

    master

    The D1xx group of errors (missing docstrings in public constructs) depends on whether a construct is considered public. A construct is public only if it meets both of the following criteria:

    1. Its immediate parent is public.
    2. Its name does not start with a single or double underscore (e.g., _name or __name).

    Special Cases & Rules:

    • Dunder Names: Names that both start and end with a double underscore are considered public (e.g., __init__.py).
    • Recursion: Publicity is recursive. For a construct to be public, all of its ancestors must be public. If a parent is private, all its descendants are automatically considered private.
    • Module Parents: For modules, the parent is determined by checking upward through the directory structure until a directory in sys.path is reached. This prevents the full filesystem path from affecting publicity.
    • The __all__ Variable: If a module defines __all__ as a literal list or tuple, only the top-level constructs listed in __all__ are considered public. Note that pydocstyle does not execute the module, so it only recognizes literal definitions of __all__ and not mutations made at runtime.

  5. Understand configuration inheritance

    master

    By default, pydocstyle merges configuration from parent directories into the local configuration.

    Merge Logic:

    • select, ignore, or convention: If specified in the child config, the parent's settings for these keys are ignored and replaced by the child's settings. If not specified in the child, the parent's settings are inherited.
    • add_select or add_ignore: These are additive; they add or remove error codes from the list inherited from the parent.
    • match or match_dir: If specified in the child, they are used; otherwise, the parent's values are used.

    Disabling Inheritance: To prevent pydocstyle from looking at parent directories (common for configuration files located at the repository root), add inherit = false to your configuration file.

    CLI Override: If you provide select, ignore, or convention via the Command Line Interface (CLI), the configuration file settings for these specific keys will be ignored. However, match and match-dir from the config file will still be applied.

    [pydocstyle]
inherit = false

  6. Migrate from pydocstyle to Ruff

    master

    The pydocstyle project is officially deprecated and no longer actively maintained. It is highly recommended to switch to Ruff, which offers full parity with pydocstyle, better support for the latest Python versions, and ongoing development.

    Ruff Repository: https://github.com/astral-sh/ruff

  7. Skip specific pydocstyle checks using inline comments

    master

    You can skip pydocstyle checks for specific functions or methods by adding inline comments. This is useful for handling exceptions where a docstring does not follow the standard style rules.

    • To skip all checks: Use # noqa.
    • To skip specific checks: Use # noqa: <ERROR_CODE>,<ERROR_CODE>. This syntax is compatible with flake8 skip patterns (e.g., # noqa: D102,E501,D203).
    >>> def bad_function():  # noqa: D400
...     """Omit a period in the docstring as an exception"""
...     pass

  9. Configure pydocstyle arguments in pre-commit

    master

    You can customize pydocstyle behavior within your .pre-commit-config.yaml by using the args key. This allows you to pass flags like --ignore or --select directly through the pre-commit hook.

    Note that you can use either single-line or multiline YAML syntax for the arguments list.

    -   id: pydocstyle
    args:
    - --ignore=D100,D203,D405
    # or multiline
    - |-
            --select=
            D101,
            D2

  10. Configure pydocstyle using configuration files

    master

    pydocstyle automatically detects configuration files. It searches for files in the following order and continues searching up the directory tree until one is found:

    1. setup.cfg
    2. tox.ini
    3. .pydocstyle
    4. .pydocstyle.ini
    5. .pydocstylerc
    6. .pydocstylerc.ini
    7. pyproject.toml

    Section Requirements:

    • For ini-like files (e.g., setup.cfg, .pydocstyle), use the [pydocstyle] section.
    • For toml files (e.g., pyproject.toml), use the [tool.pydocstyle] section.

    Note on TOML support: To use pyproject.toml, you must have the toml Python package installed. You can install it via the optional dependency:

    pip install "pydocstyle[toml]"

    Deprecation Warning: Using files named .pep257 or the [pep257] section is deprecated and will be removed in the next major version.

    # Example setup.cfg
[pydocstyle]
inherit = false
ignore = D100,D203,D405
match = .*\.py

  12. Integrate pydocstyle with pre-commit

    master

    You can use pydocstyle as a hook in your pre-commit workflow. When configured this way, pre-commit passes checked-in Python files as positional arguments to pydocstyle, so you do not need to manually specify --match=*.py.

    To add it, include the following configuration in your .pre-commit-config.yaml file, replacing |version| with a specific git hash or tag.

    -   repo: https://github.com/pycqa/pydocstyle
    rev: |version|
    hooks:
    -   id: pydocstyle