Flake8 is like lint and LEGO® bricks. A great combination.
You know the fuzzies that inevitably get intermixed with the bricks over time?
Those are not what I am writing about.
With Flake8, you build the linting solution you desire, installing and configuring plugins accordingly.
This article chronicles the ever-evolving list of Flake8 tools and plugins I use to help keep Python code well-formed.
What Flake8 plugins or other tools do you use for linting Python? Comments are welcome.
Chances are your package manager has Flake8 available (as in
dnf install python3-flake8 or
apt install flake8 or
brew install flake8), or you could do something bold like
sudo python3 -m pip install flake8.
However, I strongly recommend installing Flake8 (or any Python packages) in a virtual environment instead. Feel free to read my article on Python virtual environments for an overview. (No need to read it all; just the
virtualenv or Poetry parts are an adequate introduction).
If you know that you want the same Flake8 available system-wide, not just in some virtual environments, then installing it with your package manager makes sense, or use pipx by installing pipx first, then using
pipx install flake8. This will work fine on Windows, as well. You can also use pipx to install Flake8 plugins as in
pipx install flake8-bugbear. Again, not recommended, but I trust you know what you are doing.
If you have used
virtualenv to create a new virtual environment, then activate it first, then:
pip install flake8
If you would like to install all the plugins discussed in this article, you could instead:
pip install darglint flake8 flake8-bandit flake8-bugbear flake8-builtins flake8-comprehensions flake8-docstrings flake8-eradicate flake8-isort flake8-pytest-style flake8-spellcheck flakehell pep8-naming
Or you can download my
requirements-flake8.txt file and
pip install -r requirements-flake8.txt
Or you could use Poetry instead:
poetry new --src lintingproject
poetry add darglint flake8 flake8-bandit flake8-bugbear flake8-builtins flake8-comprehensions flake8-docstrings flake8-eradicate flake8-isort flake8-pytest-style flake8-spellcheck flakehell pep8-naming
But I think that installing them all may be a bit ambitious. Why not instead review the list below, suggest some of your own, and we can all judiciously select the plugins that suit us? Brick by brick.
To make Flake8 lint your code, run it from the command line, specifying the module, like this:
or the whole package directory, like this:
Using Poetry, you would try something like this:
poetry run flake8 ./src/lintingproject
Add some plugins to make it more interesting...
FlakeHell is not a Flake8 plugin, per se. It is a tool, a wrapper around Flake8. I like to use it because I can then configure Flake8 using a single centralized
pyproject.toml file, and because FlakeHell has pretty output.
See my write-up about FlakeHell if you are interested.
To run Flakehell, try something like
flakehell lint ./src/lintingproject/
Honestly, I am not sure why FlakeHell isn't more popular. Feel free to comment about why you hate, love, or ignore this tool.
A longstanding and popular Flake8 plugin, flake8-bugbear brings together a variety of linting opinions sure to cause you constructive discomfort.
For instance, it will warn (with code
B006) if you set default function parameters that are mutable, as in
def my_function(param1=[1,2,3]) instead of
def my_function(param1=(1,2,3)) (lists are mutable, tuples are not).
See the list of warnings provided by this Swiss-army knife of plugins.
For example, it will warn if appropriate upper/lowercase guidelines are not followed, and if an instance method does not have
self as the first argument (shame on you for using
s, for instance). For the most part, this plugin makes me pay attention to case.
See the error codes for more detail.
I should have all the Python key words memorized, and I should carefully avoid using them in my own code. But, oh, the negligence. And the tears.
Thankfully, flake8-builtins happily slaps my wrists when I forget and use, for instance,
list as a variable name.
I admit: if I don't have an annoying robot reminding me to write docstrings, and write them well, I will blissfully write functions and modules without them.
Darglint takes this one step further and will check your function arguments and
return statements, and make sure you have followed the guidance of Google or Numpy or even Sphinx and included the appropriately named documentation.
I do love isort. This tool sorts your imports "so you don't have to," sorting alphabetically, and separating into sections and by type.
Need encouragement to get your import order right? The flake8-isort plugin will output warnings if the imports are not grouped, spaced, and ordered according to isort's configuration.
Note: flake8-spellcheck is more or less English only. If you want to use other human languages, skip this one or be prepared to add a lot of words to the allow list.
I love and hate the flake8-spellcheck plugin. It takes more of my attention than any other Flake8 plugin, because I am constantly needing to add words to the allowed spelling list.
That said, I enjoy the discipline. If I am using variable and module names (and words in comments) that are not actual words, can I really be confident that other developers (or me, a year later) will understand the code?
If list, dict, and set comprehensions aren't your thing, then skip this one (and ask yourself why you are not using these powerful Python features). But, wow, if they are, the flake8-comprehensions plugin is pure gold.
It will warn you if you are using one type of comprehension when another will do, or if you are using a generator when a comprehension will work.
See the list of warnings for a full explanation.
See the list of Bandit test plugins to see what sorts of warnings you might expect.
This one is a pain, but good.
Ever comment out code to disable it, but save it for later, as though version control weren't a thing? Of course, I tell myself, it is only temporary. Until a year and a half later I see the commented out code and wonder if:
- I forgot to delete it
- or forgot to re-enable it
Pytest is a powerful and easy-to-use Python testing framework. Not surprisingly, there are good and not-so-good style choices that can be made with pytest tests.
Flake8-pytest-style ferrets out stylistic offenses in your pytest tests.
I do not regularly use the wemake-python-styleguide as I end up spending an inordinate amount of time selectively disabling the warnings per line or per file of Python code.
That said, if you want to enter a very stylistically opinionated world for a time, to encourage greater finesse in your coding, it is a great tool. Think of it as a suite of Flake8 plugins. A suite that crashes down on you from lofty heights.
Flake8 has a powerful configuration mechanism, using
tox.ini files. Plugins and warnings can be disabled per file (or even per line with
# noqa comments). See the configuration documentation for more info.
Are there Flake8 plugins or other Python linting tools you use and recommend? Feel free to leave comments!
For inspiration, check out this curated awesome list.