{"id":13667289,"url":"https://github.com/jsh9/pydoclint","last_synced_at":"2025-12-27T04:58:28.378Z","repository":{"id":165025266,"uuid":"639678591","full_name":"jsh9/pydoclint","owner":"jsh9","description":"A Python docstring linter that checks arguments, returns, yields, and raises sections","archived":false,"fork":false,"pushed_at":"2025-04-16T07:41:51.000Z","size":607,"stargazers_count":176,"open_issues_count":17,"forks_count":18,"subscribers_count":2,"default_branch":"main","last_synced_at":"2025-04-16T08:38:18.528Z","etag":null,"topics":["docstring","docstring-checker","documantation","documentation-tool","flake8","flake8-extension","flake8-extensions","flake8-plugin","flake8-plugins","linter","python-documentation"],"latest_commit_sha":null,"homepage":"https://pypi.org/project/pydoclint/","language":"Python","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"mit","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/jsh9.png","metadata":{"files":{"readme":"README.md","changelog":"CHANGELOG.md","contributing":null,"funding":null,"license":"LICENSE","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null}},"created_at":"2023-05-12T01:39:32.000Z","updated_at":"2025-04-16T07:41:16.000Z","dependencies_parsed_at":"2023-07-21T13:17:42.239Z","dependency_job_id":"49dd1231-7c0b-4268-8a33-b8080769eee8","html_url":"https://github.com/jsh9/pydoclint","commit_stats":null,"previous_names":[],"tags_count":67,"template":false,"template_full_name":null,"repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/jsh9%2Fpydoclint","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/jsh9%2Fpydoclint/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/jsh9%2Fpydoclint/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/jsh9%2Fpydoclint/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/jsh9","download_url":"https://codeload.github.com/jsh9/pydoclint/tar.gz/refs/heads/main","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":251008822,"owners_count":21522183,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2022-07-04T15:15:14.044Z","host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":["docstring","docstring-checker","documantation","documentation-tool","flake8","flake8-extension","flake8-extensions","flake8-plugin","flake8-plugins","linter","python-documentation"],"created_at":"2024-08-02T07:00:34.506Z","updated_at":"2025-12-27T04:58:28.371Z","avatar_url":"https://github.com/jsh9.png","language":"Python","funding_links":[],"categories":["Python","Docstrings"],"sub_categories":[],"readme":"# pydoclint\n\n[![Downloads](https://static.pepy.tech/badge/pydoclint)](https://pepy.tech/project/pydoclint)\n[![Downloads](https://static.pepy.tech/badge/pydoclint/month)](https://pepy.tech/project/pydoclint)\n[![Downloads](https://static.pepy.tech/badge/pydoclint/week)](https://pepy.tech/project/pydoclint)\n\n_Pydoclint_ is a Python docstring linter to check whether a docstring's\nsections (arguments, returns, raises, ...) match the function signature or\nfunction implementation.\n\nIt runs really fast. In fact, it can be thousands of times faster than\n[darglint](https://github.com/terrencepreilly/darglint) (or its maintained fork\n[darglint2](https://github.com/akaihola/darglint2)).\n\nHere is a comparison of linting time on some famous Python projects:\n\n|                                                              | pydoclint | darglint                          |\n| ------------------------------------------------------------ | --------- | --------------------------------- |\n| [numpy](https://github.com/numpy/numpy)                      | 2.0 sec   | 49 min 9 sec (1,475x slower)      |\n| [scikit-learn](https://github.com/scikit-learn/scikit-learn) | 2.4 sec   | 3 hr 5 min 33 sec (4,639x slower) |\n\nAdditionally, _pydoclint_ can detect quite a few style violations that darglint\ncannot.\n\nCurrently, _pydoclint_ supports three docstring styles:\n[numpy](https://numpydoc.readthedocs.io/en/latest/format.html),\n[Google](https://www.sphinx-doc.org/en/master/usage/extensions/example_google.html),\nand\n[Sphinx](https://sphinx-rtd-tutorial.readthedocs.io/en/latest/docstrings.html),\nwith some\n[minor style deviations](https://jsh9.github.io/pydoclint/style_deviations.html).\n\nAnother note: this linter and [pydocstyle](https://github.com/PyCQA/pydocstyle)\nserves complementary purposes. It is recommended that you use both together.\n\nThe full documentation of _pydoclint_ (including this README) can be found\nhere: [https://jsh9.github.io/pydoclint](https://jsh9.github.io/pydoclint)\n\nThe corresponding Github repository of _pydoclint_ is:\n[https://github.com/jsh9/pydoclint](https://github.com/jsh9/pydoclint)\n\n\u003c!--TOC--\u003e\n\n______________________________________________________________________\n\n**Table of Contents**\n\n- [1. Installation](#1-installation)\n- [2. Usage](#2-usage)\n  - [2.1. As a native command line tool](#21-as-a-native-command-line-tool)\n  - [2.2. As a _flake8_ plugin](#22-as-a-flake8-plugin)\n  - [2.3. Native vs _flake8_](#23-native-vs-flake8)\n  - [2.4. As a pre-commit hook](#24-as-a-pre-commit-hook)\n    - [2.4.1. Native mode](#241-native-mode)\n    - [2.4.2. As a _flake8_ plugin](#242-as-a-flake8-plugin)\n  - [2.5. How to configure _pydoclint_](#25-how-to-configure-pydoclint)\n  - [2.6. How to ignore certain violations](#26-how-to-ignore-certain-violations)\n  - [2.7. Additional tips, tricks, and pitfalls](#27-additional-tips-tricks-and-pitfalls)\n    - [2.7.1. How to _not_ document certain functions?](#271-how-to-not-document-certain-functions)\n    - [2.7.2. How to gradually adopt _pydoclint_?](#272-how-to-gradually-adopt-pydoclint)\n    - [2.7.3. Pitfall: default values of arguments](#273-pitfall-default-values-of-arguments)\n- [3. Style violation codes](#3-style-violation-codes)\n- [4. Additional notes for users](#4-additional-notes-for-users)\n- [5. Notes for developers](#5-notes-for-developers)\n\n______________________________________________________________________\n\n\u003c!--TOC--\u003e\n\n## 1. Installation\n\nTo install only the native _pydoclint_ tooling, run this command:\n\n```\npip install pydoclint\n```\n\nTo use _pydoclint_ as a _flake8_ plugin, please run this command, which will\nalso install _flake8_ to the current Python environment:\n\n```\npip install pydoclint[flake8]\n```\n\nNote that _pydoclint_ currently only supports Python 3.8 and above. (Python 3.7\nsupport may be added if there are interests and requests.)\n\n## 2. Usage\n\n### 2.1. As a native command line tool\n\n```\npydoclint \u003cFILE_OR_FOLDER\u003e\n```\n\nReplace `\u003cFILE_OR_FOLDER\u003e` with the file/folder names you want, such as `.`.\n\n### 2.2. As a _flake8_ plugin\n\nOnce you install _pydoclint_ you will have also installed _flake8_. Then you\ncan run:\n\n```\nflake8 --select=DOC \u003cFILE_OR_FOLDER\u003e\n```\n\nIf you don't include `--select=DOC` in your command, _flake8_ will also run\nother built-in _flake8_ linters on your code.\n\n### 2.3. Native vs _flake8_\n\nShould you use _pydoclint_ as a native command line tool or a _flake8_ plugin?\nHere's comparison:\n\n|                 | Pros                                                                | Cons                                                          |\n| --------------- | ------------------------------------------------------------------- | ------------------------------------------------------------- |\n| Native tool     | Slightly faster; supports \"baseline\" [\\*]; supports inline `# noqa` | Project-wide omission support coming soon [\\*\\*]              |\n| _flake8_ plugin | Supports inline or project-wide omission                            | Slightly slower because other flake8 plugins are run together |\n\n\\*) \"Baseline\" allows you to log the current violation state of your existing\nproject, making adoption of _pydoclint_ much easier.\n\n\\*\\*) Configuration-file / CLI-based suppression controls are planned for a\nfuture release.\n\n\u003e **Tip:** In native mode you can suppress DOC violations inline with\n\u003e `# noqa: DOCxxx`. Use the `--native-mode-noqa-location` option (valid values:\n\u003e \"docstring\" or \"definition\") to decide whether the comment lives on the\n\u003e definition line or at the end of the docstring (after the triple quotes).\n\n### 2.4. As a pre-commit hook\n\n_pydoclint_ can be use as a [pre-commit hook](https://pre-commit.com/), both in\nthe \"native\" mode or as a _flake8_ plugin.\n\nTo use it, put the following in your `.pre-commit-config.yaml` file:\n\n#### 2.4.1. Native mode\n\n```yaml\n- repo: https://github.com/jsh9/pydoclint\n  rev: \u003clatest_tag\u003e\n  hooks:\n    - id: pydoclint\n      args: [--style=google, --check-return-types=False]\n```\n\n(Replace `\u003clatest_tag\u003e` with the latest release tag in\nhttps://github.com/jsh9/pydoclint/releases)\n\n#### 2.4.2. As a _flake8_ plugin\n\n```yaml\n- repo: https://github.com/jsh9/pydoclint\n  rev: \u003clatest_tag\u003e\n  hooks:\n    - id: pydoclint-flake8\n      args: [--style=google, --check-return-types=False]\n```\n\n### 2.5. How to configure _pydoclint_\n\n_pydoclint_ offers many\n[configuration options](https://jsh9.github.io/pydoclint/config_options.html)\nfor you to tune it according to your team's style convention and preference.\nInline suppression is already available; broader suppression toggles via config\nfiles and CLI flags will arrive shortly.\n\nPlease read this page for instructions on configuring _pydoclint_:\n[How to configure _pydoclint_](https://jsh9.github.io/pydoclint/how_to_config.html)\n\n### 2.6. How to ignore certain violations\n\nPlease read this page:\n[How to ignore certain violations](https://jsh9.github.io/pydoclint/how_to_ignore.html)\n\n### 2.7. Additional tips, tricks, and pitfalls\n\n#### 2.7.1. How to _not_ document certain functions?\n\nIf you don't write any docstring for a function, _pydoclint_ will not check it.\n\nAlso, if you write a docstring with only a description (without the argument\nsection, the return section, etc.), _pydoclint_ will not check this docstring,\nbecause the `--skip-checking-short-docstrings` is `True` by default. (You can\nset it to `False`.)\n\n#### 2.7.2. How to gradually adopt _pydoclint_?\n\n_pydoclint_ provides a \"baseline\" feature that allows you to log the current\nviolation state of your existing project. You'll only need to fix new style\nviolations, and you can fix the \"baseline\" violations later.\n\nYou can use \"baseline\" with these 3 config options:\n\n- `--baseline`\n- `--generate-baseline`\n- `--auto-regenerate-baseline`\n\nFor more details, please read the\n[documentations on these options](https://jsh9.github.io/pydoclint/config_options.html#18---baseline).\n\n#### 2.7.3. Pitfall: default values of arguments\n\n_pydoclint_ does not like adding default values of arguments in the docstring,\neven if this style is allowed in the numpy docstring style guide.\n\nFor more rationale, please read\n[this page](https://jsh9.github.io/pydoclint/notes_for_users.html#3-notes-on-writing-type-hints).\n\n## 3. Style violation codes\n\n_pydoclint_ currently has 7 categories of style violation codes:\n\n- `DOC0xx`: Docstring parsing issues\n- `DOC1xx`: Violations about input arguments\n- `DOC2xx`: Violations about return argument(s)\n- `DOC3xx`: Violations about class docstring and class constructor\n- `DOC4xx`: Violations about \"yield\" statements\n- `DOC5xx`: Violations about \"raise\" and \"assert\" statements\n- `DOC6xx`: Violations about class attributes\n\nFor detailed explanations of each violation code, please read this page:\n[_pydoclint_ style violation codes](https://jsh9.github.io/pydoclint/violation_codes.html).\n\n## 4. Additional notes for users\n\nHere are some additional notes to help you use _pydoclint_ more easily:\n\n- [Notes for users](https://jsh9.github.io/pydoclint/notes_for_users.html)\n  - (Contains frequently encountered issues)\n- [Checking class attributes](https://jsh9.github.io/pydoclint/checking_class_attributes.html)\n- [Notes on `Generator` vs `Iterator`](https://jsh9.github.io/pydoclint/notes_generator_vs_iterator.html)\n- [More about docstring style mismatch (`DOC003`)](https://jsh9.github.io/pydoclint/style_mismatch.html)\n\nIf you'd like to use _pydoclint_ for your project, it is recommended that you\nread these additional notes\n[here](https://jsh9.github.io/pydoclint/notes_for_users.html).\n\nSpecifically, there is a section in the additional notes on how to easily adopt\n_pydoclint_ for existing legacy projects.\n\n## 5. Notes for developers\n\nIf you'd like to contribute to the code base of _pydoclint_, thank you!\n\n[This guide](https://jsh9.github.io/pydoclint/notes_for_developers.html) can\nhopefully help you get familiar with the code base faster.\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fjsh9%2Fpydoclint","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fjsh9%2Fpydoclint","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fjsh9%2Fpydoclint/lists"}