Implement rules in `darglint`

[edgarrmondragon]

This might be superseded by #12434

---

https://pypi.org/project/darglint/

Darglint'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. Darglint does not check stylistic preferences expressed
by tools in the Python Code Quality Authority (through tools such as pydocstyle).
So when using Darglint, 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. Darglint makes no such check.)

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.

[charliermarsh]

Cool, I've never used but looks useful. Would this be an impactful plugin for you? Would it unblock any Ruff adoption? :)

[edgarrmondragon]

Hey @charliermarsh, yeah. I maintain a few packages with public APIs that would benefit from contributors being informed about documentation for arguments or exceptions raised being missing.

A number of features would make Ruff a nice replacement for flake8: speed, compatibility with the rest of the Python ecosystem, pyproject.toml support.

[lsorber]

FWIW, darglint is the main blocker [1] for us to migrate Poetry Cookiecutter [2] from flake8 to ruff.

[1] superlinear-ai/substrate#125
[2] https://github.com/radix-ai/poetry-cookiecutter

[charliermarsh]

👍 Helpful to hear! darglint is probably the most popular unimplemented plugin. I'd like to get around to it soon. If there's a subset of rules that are most impactful, that'd be helpful to know too for prioritization.

[edgarrmondragon]

If there's a subset of rules that are most impactful, that'd be helpful to know too for prioritization.

For me personally, they're probably DAR101, DAR102, DAR201, DAR202 and to a lesser extent DAR301, DAR302, DAR401 and DAR402

[strickvl]

For me, I use darglint together with pydocstyle since they don't do quite the same thing. Having darglint absorbed into the ruff world would be really great.

[erwann-met]

We just discovered ruff in my team. It's amazing, and I'd like to thank you for all the great work!

We used to run flake8 along with darglint. Unfortunately since ruff does not yet implement darglint rules we still have to keep darglint alongside ruff which is a shame given how slow darglint is.

Reimplementing darglint within ruff is definitely the feature we are most looking forward to!

For us the most important rules are probably those related to the parameters (and returns) and their types: DAR101, DAR102, DAR103, DAR201, DAR202, DAR203 and DAR501. I hope this helps!

We understand that maintaining an open-source project can be a lot of work and we want to express our appreciation for all the effort that goes into it. We were wondering if there's any update on when this issue might be addressed? Any information would be greatly appreciated. Thank you!

[charliermarsh]

Very helpful, thank you! It's not something I've started working on actively (and would make for a good contribution if there are any eager contributors reading this :)), but that set of rules at least is probably not too much work to support, and this issue has a lot of thumbs-up votes so I'll try to get to it soon-ish. I'll post here when I'm able to take it on.