René's URL Explorer Experiment

{"@context":"https://schema.org","@type":"DiscussionForumPosting","headline":"flake8-docstrings does not check all of our requirements","articleBody":"\u003c!--To help us understand and resolve your issue, please fill out the form to the best of your ability.--\u003e\r\n\u003c!--You can feel free to delete the sections that do not apply.--\u003e\r\n\r\n### Bug report\r\n\r\n**Bug Summary**\r\n\r\nStarted an issue about this because it became complicated enough that I need somewhere to track progress. \r\n\r\nBasically, 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`. \r\n\r\n\r\n**Current Behavior**\r\n\r\nThis section is historical artifact of how I figured out that the issue is that `flake8-docstrings` doesn't parse `flake8`'s `--select` option.\r\n\r\n\u003cstrike\u003e\r\n\r\nJust to prove that we're actually getting flake8-docstrings output\r\n```\r\n$ pip install flake8 pydocstyle\r\n```\r\nNow we make a file with a single docstring that has error D213.\r\n```\r\n$ cat test.py\r\n\"\"\"A test module.\"\"\"\r\n\r\n\r\ndef bad_doc():\r\n    \"\"\"This should be on a new line\r\n\r\n    also missing a period, for kicks.\r\n    \"\"\"\r\n    pass\r\n```\r\nThis won't work, because no flake8-docstrings yet\r\n```\r\n$ flake8 test.py\r\n$\r\n```\r\nso we install \r\n```\r\n$ pip install flake8-docstrings\r\n```\r\nin order to get \r\n```\r\n$ flake8 --isolated test.py\r\ntest.py:5:1: D400 First line should end with a period\r\ntest.py:5:1: D401 First line should be in imperative mood; try rephrasing\r\n```\r\nwhich matches the output of `pydocstyle`:\r\n```\r\n$ pydocstyle test.py\r\ntest.py:5 in public function `bad_doc`:\r\n        D400: First line should end with a period (not 'e')\r\ntest.py:5 in public function `bad_doc`:\r\n        D401: First line should be in imperative mood; try rephrasing (found 'This')\r\n```\r\n`pydocstyle` has an option to \"add\" an error to the `select` list:\r\n```\r\n$ pydocstyle --add-select=D213 test.py\r\ntest.py:5 in public function `bad_doc`:\r\n        D213: Multi-line docstring summary should start at the second line\r\ntest.py:5 in public function `bad_doc`:\r\n        D400: First line should end with a period (not 'e')\r\ntest.py:5 in public function `bad_doc`:\r\n        D401: First line should be in imperative mood; try rephrasing (found 'This')\r\n```\r\nSure enough, it sees our intentional error. \r\n\r\nHowever, 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:\r\n```\r\n$ flake8 --isolated --select=D213 test.py\r\n$\r\n```\r\n\r\nIt'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:\r\n```\r\n$ flake8 --isolated --ignore=D400 test.py\r\ntest.py:5:1: D401 First line should be in imperative mood; try rephrasing\r\n```\r\n\r\n\u003c/strike\u003e\r\n\r\n**Solution**\r\n\r\nTwo parts:\r\n1. 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.\r\n2. 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`.\r\n\r\n**Getting flake8-docstrings to parse --select**\r\nOpened an issue, https://gitlab.com/pycqa/flake8-docstrings/-/issues/43, PR incoming.\r\n\r\n**Getting flake8 to add --extend-select**\r\n\r\nApparently 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). \r\n\r\nDigging 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.\r\n\r\nIn the meantime, `flake8` claims to support using \"both select and ignore\", but as we've seen above ","author":{"url":"https://github.com/brunobeltran","@type":"Person","name":"brunobeltran"},"datePublished":"2020-04-15T01:14:51.000Z","interactionStatistic":{"@type":"InteractionCounter","interactionType":"https://schema.org/CommentAction","userInteractionCount":1},"url":"https://github.com/17141/matplotlib/issues/17141"}