Implement pydoclint

[augustelalande]

This issue tracks the implementation of pydoclint. Following discussion in #11471 it was decided to prefer pydoclint over darglint for implementation in ruff, since they cover mostly the same ruleset, and pydoclint is still actively developed (unlike darglint). This issue should then supersede #458.

Rules

• DOC101 Docstring contains fewer arguments than in function signature
• DOC102 Docstring contains more arguments than in function signature
• DOC103 Docstring arguments are different from function arguments
• DOC104 Arguments are the same in the docstring and the function signature, but are in a different order
• DOC105 Argument names match, but type hints do not match
• DOC106 The option --arg-type-hints-in-signature is True but there are no argument type hints in the signature (covered by ANN)
• DOC107 The option --arg-type-hints-in-signature is True but not all args in the signature have type hints (covered by ANN)
• DOC108 The option --arg-type-hints-in-signature is False but there are argument type hints in the signature (covered by ANN)
• DOC109 The option --arg-type-hints-in-docstring is True but there are no type hints in the docstring arg list
• DOC110 The option --arg-type-hints-in-docstring is True but not all args in the docstring arg list have type hints
• DOC111 The option --arg-type-hints-in-docstring is False but there are type hints in the docstring arg list
• DOC201 Function/method does not have a return section in docstring
• DOC202 Function/method has a return section in docstring, but there are no return statements or annotations
• DOC203 Return type(s) in the docstring not consistent with the return annotation
• DOC301 __init__() should not have a docstring; please combine it with the docstring of the class
• DOC302 The class docstring does not need a "Returns" section, because __init__() cannot return anything
• DOC303 The __init__() docstring does not need a "Returns" section, because it cannot return anything
• DOC304 Class docstring has an argument/parameter section; please put it in the __init__() docstring
• DOC305 Class docstring has a "Raises" section; please put it in the __init__() docstring
• DOC306 The class docstring does not need a "Yields" section, because __init__() cannot yield anything
• DOC307 The __init__() docstring does not need a "Yields" section, because __init__() cannot yield anything
• DOC401 (Deprecated; this violation code no longer appears)
• DOC402 Function/method has "yield" statements, but the docstring does not have a "Yields" section
• DOC403 Function/method has a "Yields" section in the docstring, but there are no "yield" statements, or the return annotation is not a Generator/Iterator/Iterable
• DOC404 The types in the docstring's Yields section and the return annotation in the signature are not consistent
• DOC501 Function/method has "raise" statements, but the docstring does not have a "Raises" section
• DOC502 Function/method has a "Raises" section in the docstring, but there are not "raise" statements in the body
• DOC601 Class docstring contains fewer class attributes than actual class attributes
• DOC602 Class docstring contains more class attributes than in actual class attributes
• DOC603 Class docstring attributes are different from actual class attributes
• DOC604 Attributes are the same in docstring and class def, but are in a different order
• DOC605 Attribute names match, but type hints in these attributes do not match

Style support

• Support google style docstrings.
• Support numpy style docstrings.
• Support sphinx style docstrings.

[sbrugman]

I would like to enforce a certain style docstrings. I do not think it is contained in the existing rules here or in darglint. Suggesting it to be DOC901.

In theory this case could be covered by the full set of rules if you enable all:
it requires docstrings to be present, and then if we use another style these parameters will not be picked up.
However, I would like to make docstrings optional, and only enforce correctness and completeness then.

[tjkuson]

Does the Astral team have an opinion on the implementation of DOC109, DOC110, and DOC111? Separating DOC109 and DOC110 seems inconsistent with how D417 works. Seeing as DOC111 is just the inverse behaviour, my intuition is that it would make the most sense for these to be consolidated into one configurable rule.

[ddelange]

That config also overlaps with the strikethrough rules covered by ANN. We currently ignore ANN because we run mypy. When the function is fully typehinted, the docstring doesn't need any types, sphinx will still render the docstring including arg and return types for example.

[Ben-Epstein]

Does anyone know if other linting tools already implemented by ruff support the DOC6xx set of rules? I'm a bit surprised but I couldn't find them in pydocstyle, pylint, or flake8.

[KyleKing]

I really like these rules as well!

However, it would be great if the rules only applied to public functions and methods as indicated by a _ prefix for private.

For example, I wouldn't want to waste time adding a complete and correct docstring when the function is private and ignored by most documentation generators.

def _escape(text: str) -> str:
    """Hypothetical function that does some internal business logic."""
    if "&&" in text:
        raise CustomError()
    return text.replace(";", "\;")

I believe a workaround today would be to move any private functions into a file prefixed by _ and use a file pattern ignore (e.g. _*), but it would be nice to avoid extra refactoring and file-splitting. (For completeness, other workarounds are to remove the docstring and convert to a comment for private functions or to add a bunch of noqa ignores)

[augustelalande]

@KyleKing

However, it would be great if the rules only applied to public functions and methods as indicated by a _ prefix for private.

This makes sense to me. We should add a configuration option, to optionally allow/disallow the DOC rules on private functions.

Unfortunatelly, I won't be able to get to this any time soon. If you're up to it, feel free to open a PR.

[tjkuson]

@KyleKing

However, it would be great if the rules only applied to public functions and methods as indicated by a _ prefix for private.

This makes sense to me. We should add a configuration option, to optionally allow/disallow the DOC rules on private functions.

Unfortunatelly, I won't be able to get to this any time soon. If you're up to it, feel free to open a PR.

I can work on that (and ignore nested functions as well).

[ddelange]

regarding nested functions, private functions etc, here's a nice source of configs (from interrogate, a docstring coverage tool):

ignore-init-method = false
ignore-init-module = false
ignore-magic = false
ignore-semiprivate = false
ignore-private = false
ignore-property-decorators = false
ignore-module = false
ignore-nested-functions = false
ignore-nested-classes = false
ignore-setters = false
ignore-overloaded-functions = false

source

[ddelange]

And personally I'd love an ignore-oneline-docstrings option (darglint's strictness=short).

[tjkuson]

And personally I'd love an ignore-oneline-docstrings option (darglint's strictness=short).

That particular configuration is likely blocked by #5860 – we'd need a member of the Astral team to decide what level of docstring configuration they'd like and how (e.g., if the configuration would apply to a subset of docstring diagnostics, or all of them).

EDIT: I should probably elaborate. The proposal to restrict docstring diagnostics based on docstring complexity (what you describe) is distinct to what I linked (which is a proposal to limited based on function complexity). However, they face overlapping design challenges, so it might make sense to link them.

[tjkuson]

DOC303 is covered by DOC202

[Apakottur]

Pydoclint introduced DOC503 for checking exceptions a few weeks ago. It's covered by DOC501/DOC502 in Ruff (which are still in preview), but perhaps worth adding to the list in this issue as completed?

[ssbarnea]

@Apakottur Yeah, and I already raised jsh9/pydoclint#171 about it. Apparently ruff is not affected by it.

[jsh9]

@KyleKing

However, it would be great if the rules only applied to public functions and methods as indicated by a _ prefix for private.

This makes sense to me. We should add a configuration option, to optionally allow/disallow the DOC rules on private functions.
Unfortunatelly, I won't be able to get to this any time soon. If you're up to it, feel free to open a PR.

I can work on that (and ignore nested functions as well).

Hi @KyleKing @augustelalande @tjkuson and @ddelange :

I'm the author of pydoclint. Maybe I can share some thoughts behind why pydoclint does not support omitting private functions/methods.

Suppose a linter only checks certain functions in a repo and omits other functions, we may end up with a repo with mixed docstring styles as well as some other implications. For example:

• Public functions have nicely written docstrings, and private functions have incorrect docstrings
• Public functions have Google style docstrings (as enforced by a linter), while private functions' docstrings are in all sorts of styles
• If we change some functions from public to private, their docstrings suddenly become unchecked
• If we change some functions from private to public, we could have a surge of violations due to months of being omitted

That's why I didn't design such an exception in pydoclint. That said, there are indeed ways to "be lazy" in pydoclint:

• Don't write any docstring, then pydoclint has nothing to check. (pydoclint defers to other linters such as pydocstyle to enforce the existence of docstrings.)
• Write "one line" docstrings (without Args, Returns, Yields, etc. sections)
  • This is controlled by pydoclint's --skip-checking-short-docstrings option (which is True by default)

[jsh9]

I would like to enforce a certain style docstrings. I do not think it is contained in the existing rules here or in darglint. Suggesting it to be DOC901.

In theory this case could be covered by the full set of rules if you enable all: it requires docstrings to be present, and then if we use another style these parameters will not be picked up. However, I would like to make docstrings optional, and only enforce correctness and completeness then.

Hi @sbrugman ,

I'm the author of pydoclint. In the latest version of pydoclint (0.6.0), I added a new violation code (DOC003) to perform a docstring style mismatch check: for example, if you specify --style=google, but your functions' docstring are written in another style, you'll see DOC003.

More details (including caveats) are here: https://jsh9.github.io/pydoclint/style_mismatch.html

The authors of Ruff are welcome to add this new code in Ruff's roadmap.