pydocstyle
pydocstyle copied to clipboard
PyCQA
Provide `flake8` Plugin
I was thinking that we should provide our own plugin to flake8 instead of flake8-docstrings. It would solve issues like #207 where we break flake8-docstrings by accident.
Also, there is an issue that bothers me with the current flake8 plugin - it ignores pydocstyle configuration files. While other projects might use configuration files as just a handy way of typing less, in pydocstyle the configuration files allow for flexible styles over different directories in a project. I personally don't use flake8 over pydocstyle at work because of this issue.
There is an issue of how error selection might work in conjunction with flake8. If a pydocstyle config file specifies ignore=D100, would the plugin simply not yield D100 errors? What happens when flake8 is run with select=D100? It would not have any effect. Another option is using the configuration files' selection unless flake8 is used with pydocstyle error selection. Yet another way is to treat flake8's selections as add-* so that it amends the selection in the configuration files instead of replacing or masking them.
@sigmavirus24 Any thoughts? I'm currently leaning toward the last one - i.e., pydocstyle config file is read, then amended by flake8 CLI (or config files).
So I'd rather just improve flake8-docstrings. That said, I'd rather not have to start parsing and configuring pycodestyle. Flake8 is moving towards allowing per-directory configuration settings, but I haven't had time for that, nor have I figured out how that would look in an ini file.
It think it would just be plain easier to implement the plugin in pydocstyle, since we'd have all the internal API to work with. Is there a particular reason you want to stay with flake8-docstrings?
Also, regarding configuration files in flake8, tag me if there's a discussion - working on a huge project at work, I think pydocstyle got it right as we use a lot of different configuration files and it works really well.
When I teach Python code quality, I like to encourage people to use the underlying linting tools directly, such as pyflakes, pycodestyle, and pydocstyle, but also other similar tools, so that they understand which tool is doing the 'work' (and where to look for existing bugs). I prefer that each is configured in its own section or own file, again to re-enforce that connection between the error and the tool and its configuration.
I also teach and encourage using flake8, but only after they have first played with the actual tools doing the linting. It is then a bit annoying that the configuration must be moved to where flake8 can find it. Maybe this too can be solved in flake8 v3?
Also for pywikibot, flake8-docstrings has been frequently broken due to incompatibilities. Not just the recent breakage - there was also https://phabricator.wikimedia.org/T119790 and I think there was one other problem that I cant find quickly. I suspect that these problems will be less frequent if the plugin is maintained by the same team as the tool.
Also, regarding configuration files in flake8, tag me if there's a discussion - working on a huge project at work, I think pydocstyle got it right as we use a lot of different configuration files and it works really well.
There is no way for Flake8 to read other project's config files. This is by design. The less surface area there is for users to break things, the simpler we can keep Flake8. If pydocstyle implements its own plugin that reads its own configuration file(s) and then accepts configuration from Flake8, I think some people will be incredibly confused.
I find myself getting confused even though I've submitted PRs for pydocstyle and written plugins for flake8 that there's this extra package I need to couple both together, ie. flake8-docstrings.
My IDE is Syntastic which also couples both pydocstyle and flake8 together - so it was a bit of a head scratcher for a few minutes earlier today when I couldn't work out why I wasn't seeing docstring warnings.
What I hate most about automated tests is when a dependency of those tests updates and suddenly my tests are failing for something completely unrelated to what I am working on. The tests run fine locally with previously installed libs, but then fail on the CI server which does a fresh install of everything. As long as the flake8 plugin is separate from pydocstring, this can happen. In that delay between when pydocstring updates and when flake8-docstrings updates, I could encounter one of those errors (most recent being here). The only way to avoid that is to either maintain the flake8 plugin as part of pydocstyle or to run it separately from flake8.
Regardless of the apparent config file dilemma, my vote is for the plugin to be maintained as part of pydocstring. Its unfortunate that this has been delayed a year by a minor issue, when the bigger issue is so easily solvable.
@waylan in any case, it is recommend to pin your dependecies in your requirements.txt file. This way, your builds will never be affected by these dependency breaks and your builds will be deterministic.
I think pydocstyle should ship its own flake8 plugin because:
- ~~the code needed is minimal (see my PR)~~
- ~~flake8-docstring seems unmaintained~~,
- ~~does not work with pydocstyle-4.0.0~~
- ignores pydocstyle config requiring configuration via flake8 instead, and
- does not support all config options
Regarding configuration, I'd see it as a feature that the flake8 plugin by default uses pydocstyle's native configuration with inheritance. The plugin is activated by --select D on flake8's end.
I'd see it as an additional step to support overriding pydocstyle's configuration through flake8 configuration and/or cli options. However, I don't see the need for that (yet). If we want to go down that road, we might be able to add flake8 options based on pydocstyles OptionParser.
Please let me know what you think and what would be needed to get this integrated.
I was wrong regarding the minimal code needed. see https://github.com/PyCQA/pydocstyle/pull/389#issuecomment-517018628
Just stumbled on this issue after submitting https://gitlab.com/pycqa/flake8-docstrings/merge_requests/20 to get flake8-docstrings to allow setting the docstring convention.
Regarding https://github.com/PyCQA/pydocstyle/issues/219#issuecomment-517000505 I would say @chaoflow's bullet points boil down not liking the different configuration model.
Personally as a flake8 user (and author of a couple of plugins for it), I like the fact that I can have just one configuration file.
@chaoflow also, flake8-docstrings is maintained and is now working with pydocstyle 4.0. It's possible to have the existing plugin support more of the config options that make sense (as @peterjc is demonstrating).
I'd argue, further, that people continue to add plugins to flake8 (I just saw flake8-black) to avoid having config file proliferation. It only furthers my statements up-thread that most people don't want 16 config files. This is actually a motivation behind the pyproject.toml movement.
Oh and given how much documentation has had to be written about how Flake8's configuration parsing works, I doubt that pydocstyle doing it's own hoop jumping would help anyone as it would add a whole new layer of plugins doing weird things that no one actually thinks is reasonable given the body of documentation around how Flake8 already does config. So many people depend on that behaviour that inventing your own is a recipe for disaster in my opinion.
Since it was mentioned, disclosure:flake8-black is one my flake8 plugins: https://github.com/peterjc/flake8-black
This one is interesting from a flake8 plugin configuration point of view. There is a strong steer from the black authors not to use any configuration at all, although they do offer a handful of options (in part to help with legacy code bases). I was initially hoping not to have any settings for the plugin at all. Driven by user input, we've gone down the route of having the plugin look at the black configuration file (pyproject.toml). But personally, I use black without making any configuration changes.
@sigmavirus24 Glad to see that the plugin is maintained and a new release is available! Thank you.
@peterjc I do see the beauty of having one config file for several (similar) tools. I also think there should be a way to configure pydocstyle so that running it directly does not differ from running it via flake8.
I think on this issue two aspects got mixed:
- Necessity of having the plugin code maintained separately
- Different means of configuration for pydocstyle standalone and as flake8 plugin
What are the advantages of having the plugin code (roughly 100 lines) in a separate package instead of being provided by pydocstyle?
Regarding configuration, I currently don't see a good solution or what would justify having two different means of configuration. Both tools agree that config can be read from setup.cfg. However, they are using different sections. Would this be different when using pyproject.toml?
It would not be different with pyproject.toml. Tools are supposed to have different sections, e.g.,,
[tool:pydocstyle]
...
[tool:flake8]
...
(or maybe it's . instead of :, I don't remember). It would not get better. pydocstyle almost certainly doesn't want to read our config section and vice-versa. Flake8's options and syntax differ from pydocstyle's. Either way you have to duplicate configuration if you're running them separately.
However, one could make pydocstyle exclusively a plugin and not run standalone. In that case, it would obviate the need for a config section at all because it would register configuration options with whatever it plugs into.
I like this idea, however based on the download statisitcs, the flake8-docstrings plugin has a little under half the users of pydocstyle itself:
https://pypistats.org/packages/flake8-docstrings https://pypistats.org/packages/pydocstyle
Perhaps people like me who ignore the pydocstyle command line and configuration are just a sizeable minority?
Still, having the pydocstyle team more involved in flake8-docstrings the plugin's maintenance would be good.
How about including testing of the latest flake8 and flake8-docstrings plugin as part of the pydocstyle continuous integration to catch any accidental breakage?
I think everyone would benefit if pydocstyle would become a flake8, effectively retiring the flake8-docstrings plugin. Everyone would benefit from this, especially as we would reduce the maintenance chore caused by having yet-another-repository to maintain.
