Document how to test plugins

[asottile]

In GitLab by @stephenfin on May 23, 2019, 03:07

I'm trying to migrate hacking from flake8 2.x to 3.x and finding it extremely difficult to do so because the internals of the flake8 have changed so drastically between these versions (plus hacking does some stuff that's too smart for its own good, IMO). The flake8 documentation provides some introductory text on plugins, including a guide on writing a "formatting type" plugin (though it doesn't explain what a formatting plugin actually is...) but there's nothing about testing this or even what type of class or function the entrypoints should point to. The biggest issue I have is that I want to run flake8 in it entirety (i.e. with both the standard checks and my plugin enabled) on a test string, but there doesn't appear to be anyway to do this.

Would it be possible to get a small worked example that demonstrates:

• What the entrypoint should look like (i.e. if it can be a Python function, a class, or both)
• How you can test a string against only a single check
• How you can test a string against flake8's standard checks (without having to resort to a subprocess call)

I'll happily submit a documentation PR based on this example, if it would be helpful.

[asottile]

In GitLab by @asottile on May 23, 2019, 07:34

sure! Unfortunately with flake8 3.x running a string in process isn't possible/easy any more -- the api moved to being file based and doesn't really have much flexibility there (I'm looking to improve this in the future, but it's not yet at the top of the list -- I myself have worked around this in a few projects with subprocess yesqa, cheetah_lint.

So the unfortunate answer for now is (2) and (3) have to happen by subprocess to have the full access to the different options a user would (there's the legacy_api, but it isn't fully featured, and is still file-based)

As for (1), there's a couple things that work for plugins (I assume you're writing a linter?) -- the "Receiving Information" doc hints at the things you can implement for a plugin but doesn't provide an example (I would greatly appreciate some improvement here 🙏 -- I found myself looking at other flake8 plugins and less-so the docs when I wrote flake8-typing-imports recently 😬). Most of the plugins out there that I've found use the class-based plugin style, the only example I know of for the line / token based style is pycodestyle itself

[asottile]

In GitLab by @rmorshea on Jul 17, 2020, 23:41

@asottile an example in the documentation would definitely be helpful. I wanted to try the function based approach but quickly got confused and reverted to classes, which at least have public examples.