| Name | darglint2 JSON |
| Version |
1.8.2
JSON |
| download |
| home_page | |
| Summary | A utility for ensuring Google-style docstrings stay up to date with the source code. |
| upload_time | 2023-03-11 10:56:31 |
| maintainer | |
| docs_url | None |
| author | terrencepreilly |
| requires_python | >=3.6,<4.0 |
| license | MIT |
| keywords |
documentation
linter
development
|
| VCS |
|
| bugtrack_url |
|
| requirements |
No requirements were recorded.
|
| Travis-CI |
No Travis.
|
| coveralls test coverage |
No coveralls.
|
# Darglint2
A functional docstring linter which checks whether a docstring's
description matches the actual function/method implementation.
*Darglint2* expects docstrings to be formatted using the
[Google Python Style Guide](https://google.github.io/styleguide/pyguide.html),
or [Sphinx Style Guide](https://pythonhosted.org/an_example_pypi_project/sphinx.html#function-definitions),
or [Numpy Style Guide](https://numpydoc.readthedocs.io/en/latest/format.html).
Feel free to submit an issue/pull request if you spot a problem or
would like a feature in *darglint2*.
**Table of Contents**:
- [Project Status](#project-status)
- [Installation](#installation)
- [Configuration](#configuration)
- [Usage](#usage)
- [Scope](#scope)
- [Sphinx](#sphinx)
- [Numpy](#numpy)
- [Integrations](#integrations)
- [Flake8](#flake8)
- [Roadmap](#roadmap)
- [Contribution](#development-and-contributions)
## Project Status
This is a renamed fork of the original
[darglint](https://github.com/terrencepreilly/darglint) by
[@terrencepreilly](https://github.com/terrencepreilly), and I'm maintaining it
and accepting bugfixes.
## Installation
To install *darglint2*, use pip.
```bash
pip install darglint2
```
Or, clone the repository, `cd` to the directory, and
```bash
pip install .
```
## Configuration
*darglint2* can be configured using a configuration file. The configuration
file must be named either *.darglint2*, *.darglint*, *setup.cfg*, or *tox.ini*. It must
also have a section starting with the section header, `[darglint2]`.
Finally, the configuration file must be located either in the directory
*darglint2* is called from, or from a parent directory of that working
directory.
Currently, the configuration file allows us to ignore errors, to specify
message templates, to specify the strictness of checks and to ignore common
exceptions.
### Error Configuration
If we would like to ignore `ExcessRaiseError`s (because we know that
an underlying function will raise an exception), then we would add its
error code to a file named *.darglint2*:
```ini
[darglint2]
ignore=DAR402
```
We can ignore multiple errors by using a comma-separated list:
```ini
[darglint2]
ignore=DAR402,DAR103
```
Instead of specifying error codes to ignore in general one can also specify a
regex to exclude certain function names from tests. For example, the following
configuration would disable linting on all private methods.
```ini
[darglint2]
ignore_regex=^_(.*)
```
### Message Template Configuration
If we would like to specify a message template, we may do so as
follows:
```ini
[darglint2]
message_template={msg_id}@{path}:{line}
```
Which will produce a message such as `DAR102@driver.py:72`.
Finally, we can specify the docstring style type using `docstring_style`
("google" by default):
```ini
[darglint2]
docstring_style=sphinx
```
### Strictness Configuration
Strictness determines how lax darglint2 will be when checking docstrings.
There are three levels of strictness available:
- short: One-line descriptions are acceptable; anything
more and the docstring will be fully checked.
- long: One-line descriptions and descriptions without
arguments/returns/yields/etc. sections will be allowed. Anything more,
and the docstring will be fully checked.
- full: (Default) Docstrings will be fully checked.
For example, if we have the following function:
```python
def double(x):
# <docstring>
return x * 2
```
Then the following table describes which errors will be raised for
each of the docstrings (rows) when checked against each of the
configurations (columns):
```
┌──────────────────────────────┬──────────────────┬────────────────┬──────────────────┐
│ Docstring │ short │ long │ full │
├──────────────────────────────┼──────────────────┼────────────────┼──────────────────┤
│ """Doubles the argument.""" │ None │ None │ Missing argument │
│ │ │ │ Missing return │
│ │ │ │ │
│ │ │ │ │
├──────────────────────────────┼──────────────────┼────────────────┼──────────────────┤
│ """Doubles the argument. │ Missing argument │ None │ Missing argument │
│ │ Missing return │ │ Missing return │
│ Not very pythonic. │ │ │ │
│ │ │ │ │
│ """ │ │ │ │
│ │ │ │ │
├──────────────────────────────┼──────────────────┼────────────────┼──────────────────┤
│ """Doubles the argument. │ Missing return │ Missing return │ Missing return │
│ │ │ │ │
│ Args: │ │ │ │
│ x: The number to double. │ │ │ │
│ │ │ │ │
│ """ │ │ │ │
└──────────────────────────────┴──────────────────┴────────────────┴──────────────────┘
```
In short, if you want to be able to have single-line docstrings, and check
all other docstrings against their described parameters, you would specify
```ini
[darglint2]
strictness=short
```
In your configuration file.
### Ignoring common exceptions
We can specify a list of exceptions that don't need to be documented in the
raises section of a docstring. For example,
```ini
[darglint2]
ignore_raise=ValueError,MyCustomError
```
### Logging
When *darglint2* fails unexpectedly, you can try to gather more
information when submitting a bug by running with logging.
For example,
```bash
darglint2 --log-level=INFO unexpected_failures.py
```
*Darglint2* accepts the levels, `DEBUG`, `INFO`, `WARNING`, `ERROR`, and
`CRITICAL`.
## Usage
### Command Line use
Given a python source file, `serializers.py`, you would check the docstrings
as follows:
```bash
darglint2 serializers.py
```
You can give an optional verbosity setting to *darglint2*. For example,
```bash
darglint2 -v 2 *.py
```
Would give a description of the error along with information as to this
specific instance. The default verbosity is 1, which gives the filename,
function name, line number, error code, and some general hints.
To use an arbitrary error format, you can pass a message template, which
is a python format string. For example, if we pass the message
template
```bash
darglint2 -m "{path}:{line} -> {msg_id}" darglint2/driver.py
```
Then we would get back error messages like
```bash
darglint2/driver.py :61 -> DAR101
```
The following attributes can be passed to the format string:
- *line*: The line number,
- *msg*: The error message,
- *msg_id*: The error code,
- *obj*: The function/method name,
- *path*: The relative file path.
The message template can also be specified in the configuration file
as the value `message_template`.
*darglint2* is particularly useful when combined with the utility, `find`.
This allows us to check all of the files in our project at once. For example,
when eating my own dogfood (as I tend to do), I invoke *darglint2* as follows:
```bash
find . -name "*.py" | xargs darglint2
```
Where I'm searching all files ending in ".py" recursively from the
current directory, and calling *darglint2* on each one in turn.
### Ignoring Errors in a Docstring
You can ignore specific errors in a particular docstring. The syntax
is much like that of *pycodestyle*, etc. It generally takes the from
of:
```python
# noqa: <error> <argument>
```
Where `<error>` is the particular error to ignore (`DAR402`, or `DAR201`
for example), and `<argument>` is what (if anything) the ignore
statement refers to (if nothing, then it is not specified).
Let us say that we want to ignore a missing return statement
in the following docstring:
```python
def we_dont_want_a_returns_section():
"""Return the value, 3.
# noqa: DAR201
"""
return 3
```
We put the `noqa` anywhere in the top level of the docstring.
However, this won't work if we are missing something more specific,
like a parameter. We may not want to ignore all missing parameters,
either, just one particular one. For example, we may be writing a
function that takes a class instance as self. (Say, in a bound *celery*
task.) Then we would do something like:
```python
def a_bound_function(self, arg1):
"""Do something interesting.
Args:
arg1: The first argument.
# noqa: DAR101 arg1
"""
arg1.execute(self)
```
So, the argument comes to the right of the error.
We may also want to mark excess documentation as being okay. For example,
we may not want to explicitly catch and raise a `ZeroDivisionError`. We
could do the following:
```python
def always_raises_exception(x):
"""Raise a zero division error or type error.o
Args:
x: The argument which could be a number or could not be.
Raises:
ZeroDivisionError: If x is a number. # noqa: DAR402
TypeError: If x is not a number. # noqa: DAR402
"""
x / 0
```
So, in this case, the argument for `noqa` is really all the way to
the left. (Or whatever description we are parsing.) We could also
have put it on its own line, as `# noqa: DAR402 ZeroDivisionError`.
### Type Annotations
Darglint2 parses type annotations in docstrings, and can, optionally,
compare the documented type to the actual type annotation. This can
be useful when migrating a codebase to use type annotations.
In order to make these comparisons, Darglint2 only accepts types
accepted by Python (see [PEP 484](https://www.python.org/dev/peps/pep-0484/).)
That is, it does not accept parentheses in type signatures. (If
parentheses are used in the type signature, Darglint2 will mark that
argument as missing. See Issue #90.)
### Error Codes
- *DAR001*: The docstring was not parsed correctly due to a syntax error.
- *DAR002*: An argument/exception lacks a description
- *DAR003*: A line is under-indented or over-indented.
- *DAR004*: The docstring contains an extra newline where it shouldn't.
- *DAR005*: The item contains a type section (parentheses), but no type.
- *DAR101*: The docstring is missing a parameter in the definition.
- *DAR102*: The docstring contains a parameter not in function.
- *DAR103*: The docstring parameter type doesn't match function.
- *DAR104*: (disabled) The docstring parameter has no type specified
- *DAR105*: The docstring parameter type is malformed.
- *DAR201*: The docstring is missing a return from definition.
- *DAR202*: The docstring has a return not in definition.
- *DAR203*: The docstring parameter type doesn't match function.
- *DAR301*: The docstring is missing a yield present in definition.
- *DAR302*: The docstring has a yield not in definition.
- *DAR401*: The docstring is missing an exception raised.
- *DAR402*: The docstring describes an exception not explicitly raised.
- *DAR501*: The docstring describes a variable which is not defined.
The number in the hundreds narrows the error by location in the docstring:
- 000: Syntax, formatting, and style
- 100: Args section
- 200: Returns section
- 300: Yields section
- 400: Raises section
- 500: Variables section
You can enable disabled-by-default exceptions in the configuration file
using the `enable` option. It accepts a comma-separated list of error
codes.
```ini
[darglint2]
enable=DAR104
```
## Scope
Darglint2's primary focus is to identify incorrect and missing documentationd
of a function's signature. Checking style is a stretch goal, and is supported
on a best-effort basis. Darglint2 does not check stylistic preferences expressed
by tools in the Python Code Quality Authority (through tools such as `pydocstyle`).
So when using Darglint2, it may be a good idea to also use `pydocstyle`, if you
want to enforce style. (For example, `pydocstyle` requires the short summary
to be separated from other sections by a line break. Darglint2 makes no such check.)
## Sphinx
Darglint2 can handle sphinx-style docstrings, but imposes some restrictions
on top of the Sphinx style. For example, all fields (such as `:returns:`)
must be the last items in the docstring. They must be together, and all
indents should be four spaces. These restrictions may be loosened at a
later date.
To analyze Sphinx-style docstrings, pass the style flag to the command:
```bash
darglint2 -s sphinx example.py
darglint2 --docstring-style sphinx example.py
```
Alternatively, you can specify the style in the configuration file using
the setting, "docstring\_style":
```ini
[darglint2]
docstring_style=sphinx
```
## Numpy
Darglint2 now has an initial implementation for Numpy-style docstrings.
Similarly to Sphinx-style docstrings, you can pass a style flag to the
command:
```bash
darglint2 -s numpy example.py
darglint2 --docstring-style numpy example.py
```
Or set it in a configuration file:
```ini
[darglint2]
docstring_style=numpy
```
The numpy parser and error reporter are not yet fully stabilized.
Add issues or suggestions to the tracking bug, Issue #69.
## Integrations
### Flake8
Darglint2 can be used in conjunction with Flake8 as a plugin. The only
setup necessary is to install Flake8 and Darglint2 in the same environment.
Darglint2 will pull its configuration from Flake8. So, if you would like to
lint Sphinx-style comments, then you should have `docstring_style=sphinx` in a
Flake8 configuration file in the project directory. The settings would
be entered under the flake8 configuration, not a separate configuration
for Darglint2. E.g.:
```ini
[flake8]
strictness=short
docstring_style=sphinx
```
To see which options are exposed through Flake8, you can check the Flake8
tool:
```bash
flake8 --help | grep --before-context=2 Darglint2
```
### SublimeLinter
A plugin for SublimeLinter can be found [here](https://github.com/raddessi/SublimeLinter-contrib-darglint).
Note that it was built for the original `darglint`, not `darglint2`, and its
compatibility with `darglint2` is yet to be verified.
### Pre-commit
Download [pre-commit](https://pre-commit.com/) and
[install](https://pre-commit.com/#install) it. Once it is installed, add this
to `.pre-commit-config.yaml` in your repository:
```yaml
repos:
- repo: https://github.com/akaihola/darglint2
rev: master
hooks:
- id: darglint2
```
Then run `pre-commit install` and you're ready to go. Before commiting,
`darglint2` will be run on the staged files. If it finds any errors, the user
is notified and the commit is aborted. Store necessary configuration (such as
error formatting) in `.darglint2`, `.darglint`, `setup.cfg` or `tox.ini`.
## Roadmap
Below are some of the features or efforts from the original `darglint` project
at the time of forking in February 2023. Where a milestone or
issue is associated with the idea, it will be mentioned. Some of these
ideas were moonshots and may not get implemented. They are ordered
roughly according to priority/feasibility stated by the original author.
- [ ] Expose command-line options through sphinx.
- [ ] Robust logging for errors caused/encountered by *darglint2*.
- [ ] Check class docstrings (See
[darglint#25](https://github.com/terrencepreilly/darglint/issues/25)).
- [ ] Autoformatting docstrings. (See
[darglint milestone #3](https://github.com/terrencepreilly/darglint/milestone/3)).
- [ ] Optional aggressive style checking through command line flag.
- [ ] ALE support.
- [ ] Syntastic support. (Syntastic is not accepting new checkers until
their next API stabilizes, so this may take some time.)
## Development and Contributions
### Development Setup
Install `darglint2`. First, clone the repository:
```bash
git clone https://github.com/akaihola/darglint2.git
```
`cd` into the directory, create a virtual environment (optional), then setup:
```bash
cd darglint2/
virtualenv -p python3.6 .env
source .env/bin/activate
pip install -e .
```
You can install dependencies using
```bash
pip install poetry
poetry install
```
You can run the tests using
```bash
python setup.py test
```
Or, install `pytest` manually, `cd` to the project's root directory,
and run
```bash
pytest
```
This project tries to conform by the styles imposed by `pycodestyle`
and `pydocstyle`, as well as by `darglint2` itself.
A dockerfile exists for testing with Python3.4. Although it's not
officially supported (only 3.6+), it's nice to try to make minor
version numbers support it. You would build the dockerfile and
test using something like
```bash
pushd docker-build
docker build -t darglint2-34 -f Dockerfile.test34 .
popd
docker run -it --rm -v $(pwd):/code darglint2-34 pytest
```
### Contribution
If you would like to tackle an issue or feature, email me or comment on the
issue to make sure it isn't already being worked on. Contributions will
be accepted through pull requests. New features should include unit tests,
and, of course, properly formatted documentation.
Also, check out the wiki prior to updating the grammar. It includes a
description of darglint2's parsing pipline.
Raw data
{
"_id": null,
"home_page": "",
"name": "darglint2",
"maintainer": "",
"docs_url": null,
"requires_python": ">=3.6,<4.0",
"maintainer_email": "",
"keywords": "documentation,linter,development",
"author": "terrencepreilly",
"author_email": "terrencepreilly@gmail.com",
"download_url": "https://files.pythonhosted.org/packages/6c/7a/22f05360e1532aae0b172d3e2a075297a4d61b1d9a7577bfe2e54d91f3e3/darglint2-1.8.2.tar.gz",
"platform": null,
"description": "# Darglint2\n\nA functional docstring linter which checks whether a docstring's\ndescription matches the actual function/method implementation.\n*Darglint2* expects docstrings to be formatted using the\n[Google Python Style Guide](https://google.github.io/styleguide/pyguide.html),\nor [Sphinx Style Guide](https://pythonhosted.org/an_example_pypi_project/sphinx.html#function-definitions),\nor [Numpy Style Guide](https://numpydoc.readthedocs.io/en/latest/format.html).\n\nFeel free to submit an issue/pull request if you spot a problem or\nwould like a feature in *darglint2*.\n\n**Table of Contents**:\n\n- [Project Status](#project-status)\n- [Installation](#installation)\n- [Configuration](#configuration)\n- [Usage](#usage)\n- [Scope](#scope)\n- [Sphinx](#sphinx)\n- [Numpy](#numpy)\n- [Integrations](#integrations)\n- [Flake8](#flake8)\n- [Roadmap](#roadmap)\n- [Contribution](#development-and-contributions)\n\n\n## Project Status\n\nThis is a renamed fork of the original\n[darglint](https://github.com/terrencepreilly/darglint) by\n[@terrencepreilly](https://github.com/terrencepreilly), and I'm maintaining it\nand accepting bugfixes.\n\n\n## Installation\n\nTo install *darglint2*, use pip.\n\n```bash\npip install darglint2\n```\n\nOr, clone the repository, `cd` to the directory, and\n\n```bash\npip install .\n```\n\n## Configuration\n\n*darglint2* can be configured using a configuration file. The configuration\nfile must be named either *.darglint2*, *.darglint*, *setup.cfg*, or *tox.ini*. It must\nalso have a section starting with the section header, `[darglint2]`.\nFinally, the configuration file must be located either in the directory\n*darglint2* is called from, or from a parent directory of that working\ndirectory.\n\nCurrently, the configuration file allows us to ignore errors, to specify\nmessage templates, to specify the strictness of checks and to ignore common\nexceptions.\n\n### Error Configuration\n\nIf we would like to ignore `ExcessRaiseError`s (because we know that\nan underlying function will raise an exception), then we would add its\nerror code to a file named *.darglint2*:\n\n```ini\n[darglint2]\nignore=DAR402\n```\n\nWe can ignore multiple errors by using a comma-separated list:\n\n```ini\n[darglint2]\nignore=DAR402,DAR103\n```\n\nInstead of specifying error codes to ignore in general one can also specify a\nregex to exclude certain function names from tests. For example, the following \nconfiguration would disable linting on all private methods.\n```ini\n[darglint2]\nignore_regex=^_(.*)\n```\n\n### Message Template Configuration\n\nIf we would like to specify a message template, we may do so as\nfollows:\n\n```ini\n[darglint2]\nmessage_template={msg_id}@{path}:{line}\n```\n\nWhich will produce a message such as `DAR102@driver.py:72`.\n\nFinally, we can specify the docstring style type using `docstring_style`\n(\"google\" by default):\n\n```ini\n[darglint2]\ndocstring_style=sphinx\n```\n\n### Strictness Configuration\n\nStrictness determines how lax darglint2 will be when checking docstrings.\nThere are three levels of strictness available:\n\n- short: One-line descriptions are acceptable; anything\nmore and the docstring will be fully checked.\n\n- long: One-line descriptions and descriptions without\narguments/returns/yields/etc. sections will be allowed. Anything more,\nand the docstring will be fully checked.\n\n- full: (Default) Docstrings will be fully checked.\n\nFor example, if we have the following function:\n\n```python\ndef double(x):\n # <docstring>\n return x * 2\n```\n\nThen the following table describes which errors will be raised for\neach of the docstrings (rows) when checked against each of the\nconfigurations (columns):\n\n```\n\u250c\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u252c\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u252c\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u252c\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2510\n\u2502 Docstring \u2502 short \u2502 long \u2502 full \u2502\n\u251c\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u253c\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u253c\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u253c\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2524\n\u2502 \"\"\"Doubles the argument.\"\"\" \u2502 None \u2502 None \u2502 Missing argument \u2502\n\u2502 \u2502 \u2502 \u2502 Missing return \u2502\n\u2502 \u2502 \u2502 \u2502 \u2502\n\u2502 \u2502 \u2502 \u2502 \u2502\n\u251c\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u253c\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u253c\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u253c\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2524\n\u2502 \"\"\"Doubles the argument. \u2502 Missing argument \u2502 None \u2502 Missing argument \u2502\n\u2502 \u2502 Missing return \u2502 \u2502 Missing return \u2502\n\u2502 Not very pythonic. \u2502 \u2502 \u2502 \u2502\n\u2502 \u2502 \u2502 \u2502 \u2502\n\u2502 \"\"\" \u2502 \u2502 \u2502 \u2502\n\u2502 \u2502 \u2502 \u2502 \u2502\n\u251c\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u253c\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u253c\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u253c\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2524\n\u2502 \"\"\"Doubles the argument. \u2502 Missing return \u2502 Missing return \u2502 Missing return \u2502\n\u2502 \u2502 \u2502 \u2502 \u2502\n\u2502 Args: \u2502 \u2502 \u2502 \u2502\n\u2502 x: The number to double. \u2502 \u2502 \u2502 \u2502\n\u2502 \u2502 \u2502 \u2502 \u2502\n\u2502 \"\"\" \u2502 \u2502 \u2502 \u2502\n\u2514\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2534\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2534\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2534\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2518\n```\n\nIn short, if you want to be able to have single-line docstrings, and check\nall other docstrings against their described parameters, you would specify\n\n```ini\n[darglint2]\nstrictness=short\n```\n\nIn your configuration file.\n\n### Ignoring common exceptions\n\nWe can specify a list of exceptions that don't need to be documented in the\nraises section of a docstring. For example,\n\n```ini\n[darglint2]\nignore_raise=ValueError,MyCustomError\n```\n\n### Logging\n\nWhen *darglint2* fails unexpectedly, you can try to gather more\ninformation when submitting a bug by running with logging.\nFor example,\n\n```bash\ndarglint2 --log-level=INFO unexpected_failures.py\n```\n\n*Darglint2* accepts the levels, `DEBUG`, `INFO`, `WARNING`, `ERROR`, and\n`CRITICAL`.\n\n\n## Usage\n\n\n### Command Line use\n\nGiven a python source file, `serializers.py`, you would check the docstrings\nas follows:\n\n```bash\ndarglint2 serializers.py\n```\n\nYou can give an optional verbosity setting to *darglint2*. For example,\n\n```bash\ndarglint2 -v 2 *.py\n```\n\nWould give a description of the error along with information as to this\nspecific instance. The default verbosity is 1, which gives the filename,\nfunction name, line number, error code, and some general hints.\n\nTo use an arbitrary error format, you can pass a message template, which\nis a python format string. For example, if we pass the message\ntemplate\n\n```bash\ndarglint2 -m \"{path}:{line} -> {msg_id}\" darglint2/driver.py\n```\n\nThen we would get back error messages like\n\n```bash\ndarglint2/driver.py :61 -> DAR101\n```\n\nThe following attributes can be passed to the format string:\n- *line*: The line number,\n- *msg*: The error message,\n- *msg_id*: The error code,\n- *obj*: The function/method name,\n- *path*: The relative file path.\n\nThe message template can also be specified in the configuration file\nas the value `message_template`.\n\n*darglint2* is particularly useful when combined with the utility, `find`.\nThis allows us to check all of the files in our project at once. For example,\nwhen eating my own dogfood (as I tend to do), I invoke *darglint2* as follows:\n\n```bash\nfind . -name \"*.py\" | xargs darglint2\n```\n\nWhere I'm searching all files ending in \".py\" recursively from the\ncurrent directory, and calling *darglint2* on each one in turn.\n\n### Ignoring Errors in a Docstring\n\nYou can ignore specific errors in a particular docstring. The syntax\nis much like that of *pycodestyle*, etc. It generally takes the from\nof:\n\n```python\n# noqa: <error> <argument>\n```\n\nWhere `<error>` is the particular error to ignore (`DAR402`, or `DAR201`\nfor example), and `<argument>` is what (if anything) the ignore\nstatement refers to (if nothing, then it is not specified).\n\nLet us say that we want to ignore a missing return statement\nin the following docstring:\n\n```python\ndef we_dont_want_a_returns_section():\n \"\"\"Return the value, 3.\n\n # noqa: DAR201\n\n \"\"\"\n return 3\n```\n\nWe put the `noqa` anywhere in the top level of the docstring.\nHowever, this won't work if we are missing something more specific,\nlike a parameter. We may not want to ignore all missing parameters,\neither, just one particular one. For example, we may be writing a\nfunction that takes a class instance as self. (Say, in a bound *celery*\ntask.) Then we would do something like:\n\n```python\ndef a_bound_function(self, arg1):\n \"\"\"Do something interesting.\n\n Args:\n arg1: The first argument.\n\n # noqa: DAR101 arg1\n\n \"\"\"\n arg1.execute(self)\n```\n\nSo, the argument comes to the right of the error.\n\nWe may also want to mark excess documentation as being okay. For example,\nwe may not want to explicitly catch and raise a `ZeroDivisionError`. We\ncould do the following:\n\n```python\ndef always_raises_exception(x):\n \"\"\"Raise a zero division error or type error.o\n\n Args:\n x: The argument which could be a number or could not be.\n\n Raises:\n ZeroDivisionError: If x is a number. # noqa: DAR402\n TypeError: If x is not a number. # noqa: DAR402\n\n \"\"\"\n x / 0\n```\n\nSo, in this case, the argument for `noqa` is really all the way to\nthe left. (Or whatever description we are parsing.) We could also\nhave put it on its own line, as `# noqa: DAR402 ZeroDivisionError`.\n\n### Type Annotations\n\nDarglint2 parses type annotations in docstrings, and can, optionally,\ncompare the documented type to the actual type annotation. This can\nbe useful when migrating a codebase to use type annotations.\n\nIn order to make these comparisons, Darglint2 only accepts types\naccepted by Python (see [PEP 484](https://www.python.org/dev/peps/pep-0484/).)\nThat is, it does not accept parentheses in type signatures. (If\nparentheses are used in the type signature, Darglint2 will mark that\nargument as missing. See Issue #90.)\n\n\n### Error Codes\n\n- *DAR001*: The docstring was not parsed correctly due to a syntax error.\n- *DAR002*: An argument/exception lacks a description\n- *DAR003*: A line is under-indented or over-indented.\n- *DAR004*: The docstring contains an extra newline where it shouldn't.\n- *DAR005*: The item contains a type section (parentheses), but no type.\n- *DAR101*: The docstring is missing a parameter in the definition.\n- *DAR102*: The docstring contains a parameter not in function.\n- *DAR103*: The docstring parameter type doesn't match function.\n- *DAR104*: (disabled) The docstring parameter has no type specified \n- *DAR105*: The docstring parameter type is malformed.\n- *DAR201*: The docstring is missing a return from definition.\n- *DAR202*: The docstring has a return not in definition.\n- *DAR203*: The docstring parameter type doesn't match function.\n- *DAR301*: The docstring is missing a yield present in definition.\n- *DAR302*: The docstring has a yield not in definition.\n- *DAR401*: The docstring is missing an exception raised.\n- *DAR402*: The docstring describes an exception not explicitly raised.\n- *DAR501*: The docstring describes a variable which is not defined.\n\nThe number in the hundreds narrows the error by location in the docstring:\n\n- 000: Syntax, formatting, and style\n- 100: Args section\n- 200: Returns section\n- 300: Yields section\n- 400: Raises section\n- 500: Variables section\n\nYou can enable disabled-by-default exceptions in the configuration file\nusing the `enable` option. It accepts a comma-separated list of error\ncodes.\n\n```ini\n[darglint2]\nenable=DAR104\n```\n\n## Scope\n\nDarglint2's primary focus is to identify incorrect and missing documentationd\nof a function's signature. Checking style is a stretch goal, and is supported\non a best-effort basis. Darglint2 does not check stylistic preferences expressed\nby tools in the Python Code Quality Authority (through tools such as `pydocstyle`).\nSo when using Darglint2, it may be a good idea to also use `pydocstyle`, if you\nwant to enforce style. (For example, `pydocstyle` requires the short summary\nto be separated from other sections by a line break. Darglint2 makes no such check.)\n\n## Sphinx\n\nDarglint2 can handle sphinx-style docstrings, but imposes some restrictions\non top of the Sphinx style. For example, all fields (such as `:returns:`)\nmust be the last items in the docstring. They must be together, and all\nindents should be four spaces. These restrictions may be loosened at a\nlater date.\n\nTo analyze Sphinx-style docstrings, pass the style flag to the command:\n\n```bash\ndarglint2 -s sphinx example.py\ndarglint2 --docstring-style sphinx example.py\n```\n\nAlternatively, you can specify the style in the configuration file using\nthe setting, \"docstring\\_style\":\n\n```ini\n[darglint2]\ndocstring_style=sphinx\n```\n\n## Numpy\n\nDarglint2 now has an initial implementation for Numpy-style docstrings.\nSimilarly to Sphinx-style docstrings, you can pass a style flag to the\ncommand:\n\n```bash\ndarglint2 -s numpy example.py\ndarglint2 --docstring-style numpy example.py\n```\n\nOr set it in a configuration file:\n\n```ini\n[darglint2]\ndocstring_style=numpy\n```\n\nThe numpy parser and error reporter are not yet fully stabilized.\nAdd issues or suggestions to the tracking bug, Issue #69.\n\n## Integrations\n\n### Flake8\n\nDarglint2 can be used in conjunction with Flake8 as a plugin. The only\nsetup necessary is to install Flake8 and Darglint2 in the same environment.\nDarglint2 will pull its configuration from Flake8. So, if you would like to\nlint Sphinx-style comments, then you should have `docstring_style=sphinx` in a\nFlake8 configuration file in the project directory. The settings would\nbe entered under the flake8 configuration, not a separate configuration\nfor Darglint2. E.g.:\n\n```ini\n[flake8]\nstrictness=short\ndocstring_style=sphinx\n```\n\nTo see which options are exposed through Flake8, you can check the Flake8\ntool:\n\n```bash\nflake8 --help | grep --before-context=2 Darglint2\n```\n\n### SublimeLinter\n\nA plugin for SublimeLinter can be found [here](https://github.com/raddessi/SublimeLinter-contrib-darglint).\nNote that it was built for the original `darglint`, not `darglint2`, and its\ncompatibility with `darglint2` is yet to be verified.\n\n### Pre-commit\n\nDownload [pre-commit](https://pre-commit.com/) and\n[install](https://pre-commit.com/#install) it. Once it is installed, add this\nto `.pre-commit-config.yaml` in your repository:\n\n```yaml\nrepos:\n- repo: https://github.com/akaihola/darglint2\n rev: master\n hooks:\n - id: darglint2\n```\n\nThen run `pre-commit install` and you're ready to go. Before commiting,\n`darglint2` will be run on the staged files. If it finds any errors, the user\nis notified and the commit is aborted. Store necessary configuration (such as\nerror formatting) in `.darglint2`, `.darglint`, `setup.cfg` or `tox.ini`.\n\n\n## Roadmap\n\nBelow are some of the features or efforts from the original `darglint` project\nat the time of forking in February 2023. Where a milestone or\nissue is associated with the idea, it will be mentioned. Some of these\nideas were moonshots and may not get implemented. They are ordered\nroughly according to priority/feasibility stated by the original author.\n\n- [ ] Expose command-line options through sphinx.\n- [ ] Robust logging for errors caused/encountered by *darglint2*.\n- [ ] Check class docstrings (See\n [darglint#25](https://github.com/terrencepreilly/darglint/issues/25)).\n- [ ] Autoformatting docstrings. (See\n [darglint milestone #3](https://github.com/terrencepreilly/darglint/milestone/3)).\n- [ ] Optional aggressive style checking through command line flag.\n- [ ] ALE support.\n- [ ] Syntastic support. (Syntastic is not accepting new checkers until\ntheir next API stabilizes, so this may take some time.)\n\n\n## Development and Contributions\n\n### Development Setup\n\nInstall `darglint2`. First, clone the repository:\n\n```bash\ngit clone https://github.com/akaihola/darglint2.git\n```\n\n`cd` into the directory, create a virtual environment (optional), then setup:\n\n```bash\ncd darglint2/\nvirtualenv -p python3.6 .env\nsource .env/bin/activate\npip install -e .\n```\n\nYou can install dependencies using\n\n```bash\npip install poetry\npoetry install\n```\n\nYou can run the tests using\n\n```bash\npython setup.py test\n```\n\nOr, install `pytest` manually, `cd` to the project's root directory,\nand run\n\n```bash\npytest\n```\n\nThis project tries to conform by the styles imposed by `pycodestyle`\nand `pydocstyle`, as well as by `darglint2` itself.\n\n\nA dockerfile exists for testing with Python3.4. Although it's not\nofficially supported (only 3.6+), it's nice to try to make minor\nversion numbers support it. You would build the dockerfile and\ntest using something like\n\n```bash\npushd docker-build\ndocker build -t darglint2-34 -f Dockerfile.test34 .\npopd\ndocker run -it --rm -v $(pwd):/code darglint2-34 pytest\n```\n\n### Contribution\n\nIf you would like to tackle an issue or feature, email me or comment on the\nissue to make sure it isn't already being worked on. Contributions will\nbe accepted through pull requests. New features should include unit tests,\nand, of course, properly formatted documentation.\n\nAlso, check out the wiki prior to updating the grammar. It includes a\ndescription of darglint2's parsing pipline.\n",
"bugtrack_url": null,
"license": "MIT",
"summary": "A utility for ensuring Google-style docstrings stay up to date with the source code.",
"version": "1.8.2",
"split_keywords": [
"documentation",
"linter",
"development"
],
"urls": [
{
"comment_text": "",
"digests": {
"blake2b_256": "7653fa729269c8b509589aadb4b6247ec9a780b1c491067ac48de67b9d31c1c9",
"md5": "0acb5868f1e12d5d49ee0d503ded5861",
"sha256": "8f950c9b5fab25dd54bf537bef1569c267073e5828cb5ab76428876df6d947af"
},
"downloads": -1,
"filename": "darglint2-1.8.2-py3-none-any.whl",
"has_sig": false,
"md5_digest": "0acb5868f1e12d5d49ee0d503ded5861",
"packagetype": "bdist_wheel",
"python_version": "py3",
"requires_python": ">=3.6,<4.0",
"size": 121217,
"upload_time": "2023-03-11T10:56:29",
"upload_time_iso_8601": "2023-03-11T10:56:29.339783Z",
"url": "https://files.pythonhosted.org/packages/76/53/fa729269c8b509589aadb4b6247ec9a780b1c491067ac48de67b9d31c1c9/darglint2-1.8.2-py3-none-any.whl",
"yanked": false,
"yanked_reason": null
},
{
"comment_text": "",
"digests": {
"blake2b_256": "6c7a22f05360e1532aae0b172d3e2a075297a4d61b1d9a7577bfe2e54d91f3e3",
"md5": "0096209978b6ca7914059872d570f4c7",
"sha256": "11e0fc9c999bf09e192f42b72d202d177cb82da258eba387b24c2f0f5943650f"
},
"downloads": -1,
"filename": "darglint2-1.8.2.tar.gz",
"has_sig": false,
"md5_digest": "0096209978b6ca7914059872d570f4c7",
"packagetype": "sdist",
"python_version": "source",
"requires_python": ">=3.6,<4.0",
"size": 72146,
"upload_time": "2023-03-11T10:56:31",
"upload_time_iso_8601": "2023-03-11T10:56:31.956059Z",
"url": "https://files.pythonhosted.org/packages/6c/7a/22f05360e1532aae0b172d3e2a075297a4d61b1d9a7577bfe2e54d91f3e3/darglint2-1.8.2.tar.gz",
"yanked": false,
"yanked_reason": null
}
],
"upload_time": "2023-03-11 10:56:31",
"github": false,
"gitlab": false,
"bitbucket": false,
"lcname": "darglint2"
}
