D203 and D213 are not required by PEP 257

I tried codacy with some of my python projects and got many D203 and D213 issues (“1 blank line required before class docstring (found 0) (D203)” and " Multi-line docstring summary should start at the second line (D213)". In the description of these issues it says “pep257 is a static analysis tool for checking compliance with Python PEP 257”. But then I went and looked at what PEP 257 says and I was unable to find these requirements.

In the case of D203 the most related that I found in PEP 257 is “Insert a blank line after all docstrings (one-line or multi-line) that document a class – generally speaking, the class’s methods are separated from each other by a single blank line, and the docstring needs to be offset from the first method by a blank line.” Nothing saying that D203 is required.

In the case of D213 it is more clear, PEP 257 “The summary line may be on the same line as the opening quotes or on the next line” so actually it is clearly stated that this is okay contradicting D213.

I think that only the patterns that are strictly PEP 257 should be grouped together. Additional requirements should be under a different name. It is very misleading to say that this is PEP 257 if they are not.

Hello @mauvilsa, and welcome to the Codacy Community! :wave:

The issues that you mention are reported by Prospector, which in turn runs the tool pep257, now renamed to pydocstyle.

However, and as you have noticed:

pydocstyle supports most of PEP 257 out of the box, but it should not be considered a reference implementation.

You can see here which rules pydocstyle uses by default, and the D203 and D213 are indeed there:

https://pep257.readthedocs.io/en/latest/error_codes.html

If you want to change the rules that pydocstyle uses when Codacy analyzes your repositories, you can do it by adding a configuration file to your repositories:

http://www.pydocstyle.org/en/stable/usage.html#configuration-files

Please let us know if this helps and if you need any help with this setup.

1 Like

Thank you for the response! If the rename means that in the issue in the future this kind of issues will be described as “pydocstyle” instead of “pip257” then it is all good. How it is right now is very confusing. Also good to know that with a config file it can be chosen which rules to apply.

1 Like

Though in the pydocstyle repo it says

"Default Checks

Not all error codes are checked for by default. The default behavior is to check only error codes that are part of the [PEP257] official convention."

If their intention is that the default is to be pep257, then this is not correct. That is an issue in that repository, so I will create a ticket there.

Do let us know if you create the issue for pydocstyle - I’d like to subscribe the issue to get notified when there is activity.

Yes, the way Prospector works on Codacy is different from the other tools, and at least another user has provided feedback on it recently. Your feedback is valuable to help us prioritize the internal issue that we have already created to review this experience on Codacy. :+1:

1 Like

My previous comment was incorrect. It was taken from the pep257 readthedocs link you sent, but that is the documentation before the fork/rename. In the latest version of pydocstyle this is fixed, see pydocstyle/error_codes.rst at master · PyCQA/pydocstyle · GitHub and Error Codes — pydocstyle 6.0.0 documentation.

Interestingly the three named conventions pep257, numpy and google skip the checks that I was mentioning: D203 and D213. Does this mean that currently codacy is not using the forked/renamed package? Or is it that neither of the three named conventions are used and all checks are enabled?

1 Like

You are indeed right and I apologize for misleading you by providing the link for the outdated pep257 tool documentation!

Codacy is using the latest version of Prospector 1.3.1, which in turn is using the latest version of pep257.

Interestingly, Prospector doesn’t run pep257 by default, as seen here:

http://prospector.landscape.io/en/master/supported_tools.html#id6

However, from what I could test, when you do run the pep257 tool on Prospector it seems that it uses all available checks and not just the ones that pep257 would use by default when running in “standalone” mode.

The easiest way to get around this is to use a Prospector configuration file to disable the checks that you’re not interested in. For example, create a .prospector.yaml file on the root of your repository with the following disabled checks to match the PEP 257 convention:

pep257:
  disable:
    - D203
    - D212
    - D213
    - D214
    - D215
    - D404
    - D405
    - D406
    - D407
    - D408
    - D409
    - D410
    - D411
    - D413
    - D415
    - D416
    - D417

Either way, we recognize this is not the best user experience since Codacy only lets you toggle the tools included on Prospector and not the actual checks or code patterns used by each tool. We intend to allow configuring the individual checks for the tools included in Prospector directly using the Codacy UI, also providing visibility over which checks are enabled or not at each time.

Please let us know if these solutions work for you.

1 Like