ruff icon indicating copy to clipboard operation
ruff copied to clipboard

Add new configuration setting `lint.pydocstyle.allow-missing-docstring-nested-class-names`

Open CarrotManMatt opened this issue 1 year ago • 2 comments

This setting would be used by linting rule D106. It would be of type list[str] representing the names of public nested classes that are allowed to not contain a docstring. The format would be similar to lint.pylint.allow-dunder-method-names.

The major example for the usefulness of this rule would be for creating certain classes within the Django web framework, that require a nested Meta class. Models, ModelForms, some generic class-based-Views and ModelAdmin classes all require a Meta class to define certain functionality. It is superfluous to include a docstring for every definition of the Meta class as they all serve a similar purpose, and are used only by the Django runtime in the background. They should not be accessed by any project-code.

When a developer doesn't want to include docstrings purposefully for a specific nested-class name (see the example above) it is annoying to have to use the # noqa: D106 assertion on every line that the class name is used. This rule would prevent the repeated use of this ignore statement.

CarrotManMatt avatar Apr 30 '24 11:04 CarrotManMatt

Thanks for opening this. I wonder if we could do better once we have a multifile analysis and maintain such a non-configurable allow list. But maybe that's too opinionated?

MichaReiser avatar Apr 30 '24 13:04 MichaReiser