flake8-pantsbuild

This Flake8 plugin provides several custom lints used by the Pants project and its users.

Table of Contents

• Installation
  • Supported Python versions
• Usage
• Error Codes
• Migrating from lint.pythonstyle to flake8
  • Differences between the tools
  • Steps to migrate
  • Alternatives to custom lints
• Development

Installation

If using with Pants, add this to your pants.toml:

[GLOBAL]
backend_packages2.add = ["pants.backend.python.lint.flake8"]

[flake8]
extra_requirements.add = ["flake8-pantsbuild"]

If using Flake8 without Pants, install with:

$ pip install flake8-pantsbuild

Supported Python versions

This plugin works with Python 3.6+.

If you need support for Python 2.7 or Python 3.5, install flake8-pantsbuild==1.* and refer to the README at https://github.com/pantsbuild/flake8-pantsbuild/blob/1.x/README.md.

Usage

If using with Pants, run ./pants lint file.py as usual.

If using without Pants, run flake8 file.py as usual.

Error Codes

¹ To enable the PB20 indentation lint, set --enable-extensions=PB20. You'll need to disable E111 (check for 4-space indentation) via --extend-ignore=E111. You'll likely want to disable E121, E124, E125, E127, and E128 as well.

² To enable the PB30 trailing slash lint, set --enable-extensions=PB30.

Migrating from lint.pythonstyle to flake8

lint.pythonstyle was a custom Pants task from the pants.contrib.python.checks plugin that behaved like Flake8, but was generally inferior to the more popular Flake8.

Differences between the tools

Pants' lint.pythonstyle task runs pycodestyle and pyflakes, in addition to providing several custom lints.

In contrast, Flake8 runs pycodestyle and pyflakes, but it also uses mccabe to check for complex sections of code and it adds its own lints. Flake8 does not have any of the custom lint.pythonstyle lints by default, but the below table shows how to keep any of these lints you'd like.

Flake8 has hundreds of plugins that you may easily add to Pants. See Awesome Flake8 Extensions for a curated list of plugins.

Steps to migrate

First, follow the installation instructions to hook up Flake8 with Pants. Then, disable lint.pythonstyle by removing pants.contrib.python.checks from your pants.toml.

Then, run Flake8 by running ./pants lint file.py (see Usage).

The first time you run ./pants lint , you will likely have several errors due to its differences with lint.pythonstyle. We recommend starting by disabling those errors in a .flake8 config file. Add this to your pants.toml to ensure Pants uses the config:

[flake8]
config = "path/to/.flake8"

If you want to keep any of the custom lints from lint.pythonstyle, refer to the below table. You will need to install additional plugins by adding this to your pants.toml:

[flake8]
extra_requirements.add = [
  "flake8-pantsbuild",
  "pep8-naming",
  "flake8-import-order",
  # and so on...
]

Alternatives to custom lints

¹ This lint is disabled by default. See the above section Error Codes for instructions on how to enable this lint.

² To use isort with Pants, set backend_packages2.add = ["pants.backend.python.lint.isort"] in your pants.toml.

³ The PB6* lints are only available in the 1.x release series for this plugin because 2.x drops support for Python 2. Please refer to the README at https://github.com/pantsbuild/flake8-pantsbuild/blob/1.x/README.md#error-codes for instructions on how to use this plugin.

Development

We use tox for test automation. To run the test suite, invoke tox:

$ tox

You may run certain environments with tox -e (run tox -a to see all options):

$ tox -e format-run
$ tox -e typecheck
$ tox -e py36

You may also manually test by building a PEX with this plugin, as follows:

$ pex flake8 . --entry-point flake8 --output-file flake8.pex
$ vim example.py  # add whatever content you want
$ ./flake.pex example.py