{"id":5694,"library":"pydocstyle","title":"Pydocstyle","description":"Pydocstyle is a static analysis tool designed to check Python code for compliance with docstring conventions, primarily PEP 257. It supports various docstring formats, including Google and NumPy styles. The project is currently at version 6.3.0, but it is officially deprecated and no longer actively maintained, with the recommendation to migrate to Ruff for docstring linting.","status":"deprecated","version":"6.3.0","language":"en","source_language":"en","source_url":"https://github.com/PyCQA/pydocstyle","tags":["linter","code quality","docstrings","style checker","deprecated"],"install":[{"cmd":"pip install pydocstyle","lang":"bash","label":"Install stable version"}],"dependencies":[{"reason":"Runtime dependency for the library.","package":"python","optional":false},{"reason":"Required for parsing TOML configuration files (e.g., pyproject.toml). Install with `pip install pydocstyle[toml]`.","package":"toml","optional":true}],"imports":[{"note":"Pydocstyle is primarily a command-line tool. Programmatic usage often involves internal APIs like `pydocstyle.run_check` for checking files directly or `pydocstyle.checker.Checker` for more fine-grained control. The most common use case is via the CLI.","symbol":"run_check","correct":"import pydocstyle\n# errors = pydocstyle.run_check(paths=['your_file.py'])"}],"quickstart":{"code":"import os\n\ndef my_function():\n    \"\"\"This is a sample function.\n\n    It returns a string.\n    \"\"\"\n    return \"Hello\"\n\n# Save this to a file, e.g., `example.py`\n# Then run from the command line:\n# pydocstyle example.py\n# You can also customize checks:\n# pydocstyle --ignore=D100,D104 example.py","lang":"python","description":"Pydocstyle is typically used as a command-line tool. Create a Python file (e.g., `example.py`) with docstrings, then run pydocstyle against it. The `--ignore` or `--select` options allow for fine-grained control over which docstring style errors are reported."},"warnings":[{"fix":"Migrate your project's docstring linting to Ruff. Consult the Ruff documentation for migration instructions.","message":"The Pydocstyle project is officially deprecated and no longer actively maintained. Users are strongly recommended to migrate to Ruff, which offers full parity with pydocstyle and active development.","severity":"breaking","affected_versions":"All versions, especially 6.3.0 onwards as it's the last release."},{"fix":"Use configuration files like `setup.cfg`, `tox.ini`, `.pydocstyle`, `.pydocstylerc`, or `pyproject.toml` with `[pydocstyle]` or `[tool.pydocstyle]` sections.","message":"Configuration files named `.pep257` and section headers `[pep257]` are deprecated for backwards compatibility. Support for these will be removed in a future major version, which is unlikely to happen given the project's deprecation.","severity":"deprecated","affected_versions":"<6.0.0 (renamed from pep257 to pydocstyle), 6.x.x"},{"fix":"Carefully review results when using Google or NumPy conventions. You may need to manually ignore specific errors (`--ignore`) or explicitly select convention checks (`--convention=numpy` or `--convention=google`) to align with your project's chosen style.","message":"When using Google or NumPy docstring conventions, pydocstyle might incorrectly default to checking for one style over the other if section names (e.g., 'Returns', 'Yields') overlap. This can lead to false positives or missed errors.","severity":"gotcha","affected_versions":"All 6.x.x versions using Google or NumPy conventions."},{"fix":"Install pydocstyle with the `toml` extra: `pip install pydocstyle[toml]`.","message":"Support for TOML configuration files (e.g., `pyproject.toml`) is only enabled if the `toml` Python package is installed. If it's missing, pydocstyle will not recognize your TOML configuration.","severity":"gotcha","affected_versions":"All 6.x.x versions when using TOML configs."}],"env_vars":null,"last_verified":"2026-04-09T00:00:00.000Z","next_check":"2026-07-08T00:00:00.000Z"}