Bug report

Bug Summary

Started an issue about this because it became complicated enough that I need somewhere to track progress.

Basically, we need to add rule "D213" to our list of errors to be checked in :/.flake8. However, flake8-docstrings does not respect extra rules added by the select= rule in flake8.

Current Behavior

This section is historical artifact of how I figured out that the issue is that flake8-docstrings doesn't parse flake8's --select option.

Just to prove that we're actually getting flake8-docstrings output

$ pip install flake8 pydocstyle

Now we make a file with a single docstring that has error D213.

$ cat test.py
"""A test module."""


def bad_doc():
    """This should be on a new line

    also missing a period, for kicks.
    """
    pass

This won't work, because no flake8-docstrings yet

$ flake8 test.py
$

so we install

$ pip install flake8-docstrings

in order to get

$ flake8 --isolated test.py
test.py:5:1: D400 First line should end with a period
test.py:5:1: D401 First line should be in imperative mood; try rephrasing

which matches the output of pydocstyle:

$ pydocstyle test.py
test.py:5 in public function `bad_doc`:
        D400: First line should end with a period (not 'e')
test.py:5 in public function `bad_doc`:
        D401: First line should be in imperative mood; try rephrasing (found 'This')

pydocstyle has an option to "add" an error to the select list:

$ pydocstyle --add-select=D213 test.py
test.py:5 in public function `bad_doc`:
        D213: Multi-line docstring summary should start at the second line
test.py:5 in public function `bad_doc`:
        D400: First line should end with a period (not 'e')
test.py:5 in public function `bad_doc`:
        D401: First line should be in imperative mood; try rephrasing (found 'This')

Sure enough, it sees our intentional error.

However, flake8 does not seem to forward its --select option to flake8-docstrings's checker. In fact, using --select seems to overwrite --docstring-convention's error list completely:

$ flake8 --isolated --select=D213 test.py
$

It's not that flake8 doesn't forward parameters to flake8-docstring at all, --ignore works (and we currently use it in our .flake8 config file:

$ flake8 --isolated --ignore=D400 test.py
test.py:5:1: D401 First line should be in imperative mood; try rephrasing

Solution

Two parts:

1. If we get flake8-docstrings to parse the --select (and, if it gets added --extend-select) option(s), then we can just change our .flake8 file to select all the errors in pydocstyle.conventions['numpy'] that we want to use. (Currently, we do the opposite, and blacklist the ones we don't want, but there's not reason why we need to do it this way.
2. If we get flake8 to add a --extend-select option, then we can probably also convince flake8-docstrings to parse it. Then we can add just a couple of options to an extend-select= section of our .flake8 config file instead instead of having to manually whitelist the bulk of docstring-convention=numpy.

Getting flake8-docstrings to parse --select
Opened an issue, https://gitlab.com/pycqa/flake8-docstrings/-/issues/43, PR incoming.

Getting flake8 to add --extend-select

Apparently the discussion about adding --extend-select/--extend-ignore options to flake8 goes way back. In fact, the flake8-docstrings people had decided (as of two years ago) not to add a add_select option to flake8-docstrings itself, in favor of waiting for flake8 to add it instead (https://gitlab.com/pycqa/flake8-docstrings/-/issues/15).

Digging around seems to suggest that at some point, flake8 had a --extend-default-select option. It doesn't exist anymore, so I guess I'll have to figure out why it was removed before submitting an issue/PR.

In the meantime, flake8 claims to support using "both select and ignore", but as we've seen above