PyCQA / pydocstyle

docstring style checker
http://pydocstyle.org
MIT License
1.11k stars 188 forks source link

Configurable D105 - Ignore certain magic methods like __str__ and __repr__ #632

Open erikvanderwerf opened 1 year ago

erikvanderwerf commented 1 year ago

I did see the discussion on #60 and #480, and as far as I can tell there is not any way to selectively control a subset of magic methods that flag D105. This is something I would be interested in, since __str__/__repr__ are effectively boilerplate, but other magic methods might be more nuanced.

I could see this going a few different ways if this is accepted, and any other suggestions are welcome as well!

Ignore Categories of Magic

Less configurable, but it could lead to more concise, intention-oriented, configuration.

Referring to the data model, I could see common-case reductions of the space of ~90 magic methods in the data model to just ~15 "categories".

Category Magic Method(s)
async (or await) https://docs.python.org/3/reference/datamodel.html#awaitable-objects
attrs https://docs.python.org/3/reference/datamodel.html#customizing-attribute-access
bool __bool__
bytes __bytes__
class1 __del__
https://docs.python.org/3/reference/datamodel.html#customizing-class-creation
https://docs.python.org/3/reference/datamodel.html#customizing-instance-and-subclass-checks
comparisons https://docs.python.org/3/reference/datamodel.html#object.__lt__
containers https://docs.python.org/3/reference/datamodel.html#emulating-container-types
https://docs.python.org/3/reference/datamodel.html#asynchronous-iterators
context https://docs.python.org/3/reference/datamodel.html#with-statement-context-managers
https://docs.python.org/3/reference/datamodel.html#asynchronous-context-managers
descriptors https://docs.python.org/3/reference/datamodel.html#implementing-descriptors
equality __equals__
__hash__
format __format__
instance https://docs.python.org/3/reference/datamodel.html#customizing-instance-and-subclass-checks
numeric https://docs.python.org/3/reference/datamodel.html#emulating-numeric-types
strings __str__
__repr__

From parser.py at least __init__, __new__, and __call__ relate to a different lint, and are not considered here1.

  1. FYI, __init_subclass__(cls, /, **kwargs) is a variadic method that is not currently covered in the list, new in version 3.6. May file a PR for this.
[tool.pydocstyle]
ignore_magic = ["strings"]

Ignore Magic By Name

Ignores missing docstrings project-wide based on the method name. Fairly configurable, but could be verbose.

[tool.pydocstyle]
ignore_magic = ["__str__", "__repr__"]

Both ignore rules could be in effect simultaneously, since the names do not overlap.

Bonus: By Path

With either approach, an additional consideration could be made for matching parent paths to allow for more granular control.

[tool.pydocstyle]
ignore_magic = {
    "src/project/": ["strings"],
    "src/project/math/": ["numeric", "__len__"]
}

This is just an RFC for now. If a consensus is reached, then we can find a volunteer (maybe myself)! Thanks!