Stylish Python code, or learning to use Flake8
Author: Anatoly Solovey, developer
The Python programming language is very much in demand in the modern market, it develops every day, and an active community has developed around it. In order to avoid conflicts between pythonist developers, the language creators wrote a PEP 8 agreement describing code design rules, but even there it was noted that:
Many projects have their own coding style guidelines. In the event of any conflicts, such project-specific guides take precedence for that project.
As a result of the addition of new rules, the number of code design requirements has increased so much that it has become very difficult to keep them in mind. At the same time, referring to guides can take a lot of time and distract from the development process.
For a long time, programmers have developed their own style of writing code, preferences in the style guides, and other trifles that leave the author's seal on the developer’s programs. Convincing developers to abandon their usual code styles is very difficult, but even if they succeed, there is a great chance that old code added by virtue of habit will slip through their code.
')
When each update passes a strict revision code that includes style checking, such errors can slow down the development process very much. And if the mistakes are not noticed in the end, even during the review process, a bunch of unreadable and incomprehensible code will appear in the project version control system very soon.
Linters come to the rescue in this case - tools that control the design of the code in the project. They help to maintain its purity and, in our case, prevent the creation of commits that may contain errors. I use Flake8 for quality control and now I will try to explain why I chose it, and tell you how to set it up in order to get the maximum result. Interested? Welcome under cat.
Flake8: Your Tool For Style Guide Enforcement
Flake8 itself is a tool that allows you to scan a project code and detect stylistic errors and violations of various conventions of Python code in it.
Flake8 is able to work not only with PEP 8, but also with other rules, besides it supports custom plugins, so in the future in this article I will start from the rules from Google Python Style Guide .
Why Flake8?
Flake8: pep8 + pyflakes + more
The creator of Flake8, Tarek Ziade, set himself the goal of combining the main popular code style control tools in one library, which he successfully coped with in the end - Flake8 was truly universal.
Easy installation and configuration
To check whether the code in your project meets the basic requirements of PEP 8, it is enough to install Flake:
$ pip install flake8 and run it - just type on the command line:
$ flake8 my_project after which you will receive a list with file names and line numbers where errors were made, and a detailed description of the errors themselves:
$ flake8 my_project myfile.py:1: 'sys' imported but unused myfile.py:4:1: E302 expected 2 blank lines, found 1 Great, isn't it? But that's not all. If you are not a fan of working with the console, then you can configure Flake8 to integrate with the IDE or the editor you prefer.
Flake8 integration with editors and IDE
PyCharm integration
Also relevant for any other JetBrains IDE.
Integration is carried out in just a couple of easy steps.
Open the External Tools settings in File → Settings → Tools and click on “+”, then fill in the fields using this template:
After that, click on Output Filters, and then on “+” to add a new rule to display messages from the flick:
Here we tell PyCharm that we want the output of the string with errors to be clickable and to open the file and the place with the error in the editor.
Everything. Flake8 integration with PyCharm is complete. In order to call up the flick and check your code, right-click on the file / directory that we want to check, and select External Tools → Flake8 in the context menu.
The PyCharm output will display a clickable list of violations in the selected file / directory:
Atom integration
To install the Flake8 tool for Atom, use the Atom package manager in Settings and find linter-flake8 there:
Or call
apm install flake8 from the command line.
Then go to linter-flake8 settings and specify the path to the directory where flake8 is installed:
Linter-flake8 has its own customization readme, which, if you wish, can be found on the linter-flake8 page in Atom itself.
Availability of Version Control Hooks
That is what I consider to be the main advantage of Flake8, which distinguishes it from other linters. Unlike most of these tools, where entire separate libraries and modules are used to configure VCS hooks (as, for example, in Pylint), the hook configuration in a flake is literally two lines.
At the time of this writing, Flake8 knows how to use pre-commit hooks for Git and Mercurial. These hooks allow, for example, to prevent the creation of a commit if any rules for execution are violated.
Install a hook for Git:
$ flake8 --install-hook git And configure the git itself to take into account the rules of Flake8:
$ git config --bool flake8.strict true I will demonstrate how Git hook works on a project that I used for the example of integrating Flake8 with PyCharm. In the flake8tutorial.py module, we see obvious errors: imported and unused modules, the absence of pre-stringing and the empty line at the end of the file.
First of all, we initialize a git-0 repository in this project, install a flake8 hook and tell our git that it should chase the flake before commits:
Then we will try to make the first commit:
As you can see, flake8 was called before the commit and did not allow us to commit invalid changes.
Now fix the errors marked with a flick and try to commit a valid code:
Commit has been successfully created. Fine!
The Flake8 setting for Mercurial is almost identical. First you need to install Flake8 Mercurial Hook:
$ flake8 --install-hook mercurial And configure Mercurial itself:
$ hg config flake8.strict true That's all, the hook for Mercurial is installed, configured and ready to use!
Details on the Flake8 configuration
Basic configuration
A list of additional options and rules can be passed directly when called from the command line in the following way:
flake8 --select E123 (in this example, using the select option, we say that Flake only reports violations of the E123 rule (this is the “closing bracket does not match indentation of opening bracket's line” rule code)) .
By the way, a full list of options with a description can be found in the documentation for the library itself .
In my opinion, where it is preferable to configure Flake using configuration files, you can store the settings in one of the files setup.cfg, tox.ini or .flake8. For clarity, I prefer to use the latter option.
The settings file allows you to control the use of the library of the same options that are configured for the command line, the basic configuration file looks like this:
[flake8] ignore = D203 exclude = .git,__pycache__,docs/source/conf.py,old,build,dist In this file, we tell Flake that it should not notify us of violations of the D203 rule (“1 blank line required before class docstring”), and should not check the .git, __ pycache__, docs / source / conf.py files and the old directories , build, dist.
You can leave comments in the configuration files, this is useful if you provide a large list of rules that Flake should ignore:
[flake8] # it's not a bug that we aren't using all of hacking ignore = # F812: list comprehension redefines ... F812, # H101: Use TODO(NAME) H101, # H202: assertRaises Exception too broad H202, # H233: Python 3.x incompatible use of print operator H233, # H301: one import per line H301, # H306: imports not in alphabetical order (time, os) H306, # H401: docstring should not start with a space H401, # H403: multi line docstrings should end on a new line H403, # H404: multi line docstring should start without a leading new line H404, # H405: multi line docstring summary not separated with an empty line H405, # H501: Do not use self.__dict__ for string formatting H501 You can also add a separate line in the exceptions in your module, simply by leaving a comment noqa on this line. Then, when checking the Flake8 module, it will ignore errors found in the lines marked with this comment:
import sys # noqa Modules that extend the functionality
Since Flake allows you to create and use custom plugins, you can find a large number of open-source plugins for it. I will describe only those that I use myself and find it especially useful:
flake8-import-order
The plugin that checks the order of imports in the project: in the standard configuration, the standard libraries (stdlib) should be the first to import, then third-party library imports, and then local packages, each group separated by an empty line and sorted in alphabetical order.
This plugin expands the list of Flake alerts by adding three new ones there:
- I100: Your import statements are in the wrong order.
- I101: The names are in the wrong order.
- I201: Missing newline between sections or imports.
Installation:
pip install flake8-import-order Configuration:
[flake8] application-import-names = my_project, tests # , . import-order-style = google # , . , Google Style Guide. More information about setting flake8-import-order can be found on the library page on Github.
flake8-docstrings
The plugin that adds functionality support from pydocstyle - checks dockstrings for compliance with Python conventions.
Installation:
pip install flake8_docstrings The list of rules added by this library can be found in the pydocstyle documentation .
Configuration:
By itself, this library is not configured in any way, however, the added rules can be added to the exceptions if one of them is irrelevant for your project:
[flake8] ignore = D101 # docstrings “Missing docstring in public class” Library page on Github here .
flake8-builtins
Plugin checking code for using embedded names as variables or parameters.
Installation:
pip install flake8-builtins Configuration:
As in the case of flake8-docstrings, the plugin does not have additional settings, but the rules it added can, for example, add flake exceptions:
[flake8] ignore = B001 # builtins “<some_builtin> is a python builtin and is being shadowed, consider renaming the variable” More information about this plugin can be found on this Github plugin page .
flake8-quotes
A plugin that allows you to control the type of quotes that will be used in the project.
Installation:
pip install flake8-quotes Configuration:
[flake8] inline-quotes = " # , More information about this plugin can be found on this Github plugin page .
Afterword
Although the settings described above can prevent poor-quality code from appearing in the repository in 97.5% of cases, it can be run in some way (for example, if the girl was too lazy to enter two lines to configure the pre-commit hook). Therefore, I highly recommend adding Flake8 call on the build-pull request stage in the continuous integration system you are using to prevent merge invalid pull-requests and errors from entering the master.
I hope this article was useful to you and will allow you to further maximally flexibly and efficiently customize the workflow and style guides in your Python projects. All the best.
List of sources:
Source: https://habr.com/ru/post/318776/
All Articles