| Name | pydoclint JSON |
| Version |
0.5.18
JSON |
| download |
| home_page | https://github.com/jsh9/pydoclint |
| Summary | A Python docstring linter that checks arguments, returns, yields, and raises sections |
| upload_time | 2025-01-12 21:53:17 |
| maintainer | None |
| docs_url | None |
| author | None |
| requires_python | >=3.9 |
| license | MIT |
| keywords |
|
| VCS |
 |
| bugtrack_url |
|
| requirements |
No requirements were recorded.
|
| Travis-CI |
No Travis.
|
| coveralls test coverage |
No coveralls.
|
# pydoclint
_Pydoclint_ is a Python docstring linter to check whether a docstring's
sections (arguments, returns, raises, ...) match the function signature or
function implementation.
It runs really fast. In fact, it can be thousands of times faster than
[darglint](https://github.com/terrencepreilly/darglint) (or its maintained fork
[darglint2](https://github.com/akaihola/darglint2)).
Here is a comparison of linting time on some famous Python projects:
| | pydoclint | darglint |
| ------------------------------------------------------------ | --------- | --------------------------------- |
| [numpy](https://github.com/numpy/numpy) | 2.0 sec | 49 min 9 sec (1,475x slower) |
| [scikit-learn](https://github.com/scikit-learn/scikit-learn) | 2.4 sec | 3 hr 5 min 33 sec (4,639x slower) |
Additionally, _pydoclint_ can detect some quite a few style violations that
darglint cannot.
Currently, _pydoclint_ supports three docstring styles:
[numpy](https://numpydoc.readthedocs.io/en/latest/format.html),
[Google](https://www.sphinx-doc.org/en/master/usage/extensions/example_google.html),
and
[Sphinx](https://sphinx-rtd-tutorial.readthedocs.io/en/latest/docstrings.html).
Another note: this linter and [pydocstyle](https://github.com/PyCQA/pydocstyle)
serves complementary purposes. It is recommended that you use both together.
The full documentation of _pydoclint_ (including this README) can be found
here: [https://jsh9.github.io/pydoclint](https://jsh9.github.io/pydoclint)
The corresponding Github repository of _pydoclint_ is:
[https://github.com/jsh9/pydoclint](https://github.com/jsh9/pydoclint)
---
**Table of Contents**
<!--TOC-->
- [1. Installation](#1-installation)
- [2. Usage](#2-usage)
- [2.1. As a native command line tool](#21-as-a-native-command-line-tool)
- [2.2. As a _flake8_ plugin](#22-as-a-flake8-plugin)
- [2.3. Native vs _flake8_](#23-native-vs-flake8)
- [2.4. As a pre-commit hook](#24-as-a-pre-commit-hook)
- [2.4.1. Native mode](#241-native-mode)
- [2.4.2. As a _flake8_ plugin](#242-as-a-flake8-plugin)
- [2.5. How to configure _pydoclint_](#25-how-to-configure-pydoclint)
- [2.6. How to ignore certain violations in _flake8_ mode](#26-how-to-ignore-certain-violations-in-flake8-mode)
- [2.7. Additional tips, tricks, and pitfalls](#27-additional-tips-tricks-and-pitfalls)
- [2.7.1. How to _not_ document certain functions?](#271-how-to-not-document-certain-functions)
- [2.7.2. How to gradually adopt _pydoclint_?](#272-how-to-gradually-adopt-pydoclint)
- [2.7.3. Pitfall: default values of arguments](#273-pitfall-default-values-of-arguments)
- [3. Style violation codes](#3-style-violation-codes)
- [4. Additional notes for users](#4-additional-notes-for-users)
- [5. Notes for developers](#5-notes-for-developers)
<!--TOC-->
## 1. Installation
To install only the native _pydoclint_ tooling, run this command:
```
pip install pydoclint
```
To use _pydoclint_ as a _flake8_ plugin, please run this command, which will
also install _flake8_ to the current Python environment:
```
pip install pydoclint[flake8]
```
Note that _pydoclint_ currently only supports Python 3.8 and above. (Python 3.7
support may be added if there are interests and requests.)
## 2. Usage
### 2.1. As a native command line tool
```
pydoclint <FILE_OR_FOLDER>
```
Replace `<FILE_OR_FOLDER>` with the file/folder names you want, such as `.`.
### 2.2. As a _flake8_ plugin
Once you install _pydoclint_ you will have also installed _flake8_. Then you
can run:
```
flake8 --select=DOC <FILE_OR_FOLDER>
```
If you don't include `--select=DOC` in your command, _flake8_ will also run
other built-in _flake8_ linters on your code.
### 2.3. Native vs _flake8_
Should you use _pydoclint_ as a native command line tool or a _flake8_ plugin?
Here's comparison:
| | Pros | Cons |
| --------------- | ---------------------------------------- | ------------------------------------------------------------- |
| Native tool | Slightly faster; supports "baseline" [*] | No inline or project-wide omission support right now [**] |
| _flake8_ plugin | Supports inline or project-wide omission | Slightly slower because other flake8 plugins are run together |
\*) "Baseline" allows you to log the current violation state of your existing
project, making adoption of _pydoclint_ much easier.
\*\*) This feature may be added in the near future
### 2.4. As a pre-commit hook
_pydoclint_ can be use as a [pre-commit hook](https://pre-commit.com/), both in
the "native" mode or as a _flake8_ plugin.
To use it, put the following in your `.pre-commit-config.yaml` file:
#### 2.4.1. Native mode
```yaml
- repo: https://github.com/jsh9/pydoclint
rev: <latest_tag>
hooks:
- id: pydoclint
args: [--style=google, --check-return-types=False]
```
(Replace `<latest_tag>` with the latest release tag in
https://github.com/jsh9/pydoclint/releases)
#### 2.4.2. As a _flake8_ plugin
```yaml
- repo: https://github.com/jsh9/pydoclint
rev: <latest_tag>
hooks:
- id: pydoclint-flake8
args: [--style=google, --check-return-types=False]
```
### 2.5. How to configure _pydoclint_
_pydoclint_ offers many
[configuration options](https://jsh9.github.io/pydoclint/config_options.html)
for you to tune it according to your team's style convention and preference.
Please read this page for instructions on configuring _pydoclint_:
[How to configure _pydoclint_](https://jsh9.github.io/pydoclint/how_to_config.html)
### 2.6. How to ignore certain violations in _flake8_ mode
Please read this page:
[How to ignore certain violations](https://jsh9.github.io/pydoclint/how_to_ignore.html)
### 2.7. Additional tips, tricks, and pitfalls
#### 2.7.1. How to _not_ document certain functions?
If you don't write any docstring for a function, _pydoclint_ will not check it.
Also, if you write a docstring with only a description (without the argument
section, the return section, etc.), _pydoclint_ will not check this docstring,
because the `--skip-checking-short-docstrings` is `True` by default. (You can
set it to `False`.)
#### 2.7.2. How to gradually adopt _pydoclint_?
_pydoclint_ provides a "baseline" feature that allows you to log the current
violation state of your existing project. You'll only need to fix new style
violations, and you can fix the "baseline" violations later.
You can use "baseline" with these 3 config options:
- `--baseline`
- `--generate-baseline`
- `--auto-regenerate-baseline`
For more details, please read the
[documentations on these options](https://jsh9.github.io/pydoclint/config_options.html#18---baseline).
#### 2.7.3. Pitfall: default values of arguments
_pydoclint_ does not like adding default values of arguments in the docstring,
even if this style is allowed in the numpy docstring style guide.
For more rationale, please read
[this page](https://jsh9.github.io/pydoclint/notes_for_users.html#3-notes-on-writing-type-hints).
## 3. Style violation codes
_pydoclint_ currently has 7 categories of style violation codes:
- `DOC0xx`: Docstring parsing issues
- `DOC1xx`: Violations about input arguments
- `DOC2xx`: Violations about return argument(s)
- `DOC3xx`: Violations about class docstring and class constructor
- `DOC4xx`: Violations about "yield" statements
- `DOC5xx`: Violations about "raise" statements
- `DOC6xx`: Violations about class attributes
For detailed explanations of each violation code, please read this page:
[_pydoclint_ style violation codes](https://jsh9.github.io/pydoclint/violation_codes.html).
## 4. Additional notes for users
If you'd like to use _pydoclint_ for your project, it is recommended that you
read these additional notes
[here](https://jsh9.github.io/pydoclint/notes_for_users.html).
Specifically, there is a section in the additional notes on how to easily adopt
_pydoclint_ for existing legacy projects.
## 5. Notes for developers
If you'd like to contribute to the code base of _pydoclint_, thank you!
[This guide](https://jsh9.github.io/pydoclint/notes_for_developers.html) can
hopefully help you get familiar with the code base faster.
Raw data
{
"_id": null,
"home_page": "https://github.com/jsh9/pydoclint",
"name": "pydoclint",
"maintainer": null,
"docs_url": null,
"requires_python": ">=3.9",
"maintainer_email": null,
"keywords": null,
"author": null,
"author_email": null,
"download_url": "https://files.pythonhosted.org/packages/d1/44/ea2781da97a5d049bf967964b9c522646956006ba87619af4abf4a37837b/pydoclint-0.5.18.tar.gz",
"platform": null,
"description": "# 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 some quite a few style violations that\ndarglint cannot.\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).\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---\n\n**Table of Contents**\n\n<!--TOC-->\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 in _flake8_ mode](#26-how-to-ignore-certain-violations-in-flake8-mode)\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<!--TOC-->\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 <FILE_OR_FOLDER>\n```\n\nReplace `<FILE_OR_FOLDER>` 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 <FILE_OR_FOLDER>\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\" [*] | No inline or project-wide omission support right now [**] |\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\\*\\*) This feature may be added in the near future\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: <latest_tag>\n hooks:\n - id: pydoclint\n args: [--style=google, --check-return-types=False]\n```\n\n(Replace `<latest_tag>` 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: <latest_tag>\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.\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 in _flake8_ mode\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\" 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\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",
"bugtrack_url": null,
"license": "MIT",
"summary": "A Python docstring linter that checks arguments, returns, yields, and raises sections",
"version": "0.5.18",
"project_urls": {
"Homepage": "https://github.com/jsh9/pydoclint"
},
"split_keywords": [],
"urls": [
{
"comment_text": "",
"digests": {
"blake2b_256": "7ca44dcd334b477680e94b5a0a4e516927da64418930294dc92fa5c6a551aa23",
"md5": "dab656f1758ca4a477410aeca288e7b8",
"sha256": "0c99479bb085399d034881773649402fb08cdccd0d6827b4f0b98aa7e032c329"
},
"downloads": -1,
"filename": "pydoclint-0.5.18-py2.py3-none-any.whl",
"has_sig": false,
"md5_digest": "dab656f1758ca4a477410aeca288e7b8",
"packagetype": "bdist_wheel",
"python_version": "py2.py3",
"requires_python": ">=3.9",
"size": 45614,
"upload_time": "2025-01-12T21:53:15",
"upload_time_iso_8601": "2025-01-12T21:53:15.864854Z",
"url": "https://files.pythonhosted.org/packages/7c/a4/4dcd334b477680e94b5a0a4e516927da64418930294dc92fa5c6a551aa23/pydoclint-0.5.18-py2.py3-none-any.whl",
"yanked": false,
"yanked_reason": null
},
{
"comment_text": "",
"digests": {
"blake2b_256": "d144ea2781da97a5d049bf967964b9c522646956006ba87619af4abf4a37837b",
"md5": "56cfec312703ce6394f66cc83431e3c8",
"sha256": "c2c937dadace598b15b45a60c230d2e1ca6ccea8fe2db083143b6524f281b5c2"
},
"downloads": -1,
"filename": "pydoclint-0.5.18.tar.gz",
"has_sig": false,
"md5_digest": "56cfec312703ce6394f66cc83431e3c8",
"packagetype": "sdist",
"python_version": "source",
"requires_python": ">=3.9",
"size": 50780,
"upload_time": "2025-01-12T21:53:17",
"upload_time_iso_8601": "2025-01-12T21:53:17.149632Z",
"url": "https://files.pythonhosted.org/packages/d1/44/ea2781da97a5d049bf967964b9c522646956006ba87619af4abf4a37837b/pydoclint-0.5.18.tar.gz",
"yanked": false,
"yanked_reason": null
}
],
"upload_time": "2025-01-12 21:53:17",
"github": true,
"gitlab": false,
"bitbucket": false,
"codeberg": false,
"github_user": "jsh9",
"github_project": "pydoclint",
"travis_ci": false,
"coveralls": false,
"github_actions": true,
"tox": true,
"lcname": "pydoclint"
}
