Public Python API

Flake8 3.0.0 presently does not have a public, stable Python API.

When it does it will be located in flake8.api and that will be documented here.

Legacy API

When Flake8 broke its hard dependency on the tricky internals of pycodestyle, it lost the easy backwards compatibility as well. To help existing users of that API we have flake8.api.legacy. This module includes a couple classes (which are documented below) and a function.

The main usage that the developers of Flake8 observed was using the get_style_guide() function and then calling check_files(). To a lesser extent, people also seemed to use the get_statistics() method on what check_files returns. We then sought to preserve that API in this module.

Let’s look at an example piece of code together:

from flake8.api import legacy as flake8


style_guide = flake8.get_style_guide(ignore=['E24', 'W503'])
report = style_guide.check_files([...])
assert report.get_statistics('E') == [], 'Flake8 found violations'

This represents the basic universal usage of all existing Flake8 2.x integrations. Each example we found was obviously slightly different, but this is kind of the gist, so let’s walk through this.

Everything that is backwards compatible for our API is in the flake8.api.legacy submodule. This is to indicate, clearly, that the old API is being used.

We create a flake8.api.legacy.StyleGuide by calling flake8.api.legacy.get_style_guide(). We can pass options to flake8.api.legacy.get_style_guide() that correspond to the command-line options one might use. For example, we can pass ignore, select, exclude, format, etc. Our legacy API, does not enforce legacy behaviour, so we can combine ignore and select like we might on the command-line, e.g.,

style_guide = flake8.get_style_guide(
    ignore=['E24', 'W5'],
    select=['E', 'W', 'F'],
    format='pylint',
)

Once we have our flake8.api.legacy.StyleGuide we can use the same methods that we used before, namely

StyleGuide.check_files(paths=None)

Run collected checks on the files provided.

This will check the files passed in and return a Report instance.

Parameters:paths (list) – List of filenames (or paths) to check. Returns:Object that mimic’s Flake8 2.0’s Reporter class. Return type:flake8.api.legacy.Report

StyleGuide.excluded(filename, parent=None)

Determine if a file is excluded.

Parameters:

• filename (str) – Path to the file to check if it is excluded.
• parent (str) – Name of the parent directory containing the file.

Returns:

True if the filename is excluded, False otherwise.

Return type:

bool

StyleGuide.init_report(reporter=None)

Set up a formatter for this run of Flake8.

StyleGuide.input_file(filename, lines=None, expected=None, line_offset=0)

Run collected checks on a single file.

This will check the file passed in and return a Report instance.

Parameters:

• filename (str) – The path to the file to check.
• lines (list) – Ignored since Flake8 3.0.
• expected – Ignored since Flake8 3.0.
• line_offset (int) – Ignored since Flake8 3.0.

Returns:

Object that mimic’s Flake8 2.0’s Reporter class.

Return type:

flake8.api.legacy.Report

Warning

These are not perfectly backwards compatible. Not all arguments are respsected, and some of the types necessary for something to work have changed.

Most people, we observed, were using check_files(). You can use this to specify a list of filenames or directories to check. In Flake8 3.0, however, we return a different object that has similar methods. We return a flake8.api.legacy.Report which has the method

Report.get_statistics(violation)

Get the list of occurrences of a violation.

Returns:List of occurrences of a violation formatted as: {Count} {Error Code} {Message}, e.g., 8 E531 Some error message about the error Return type:list

Most usage of this method that we noted was as documented above. Keep in mind, however, that it provides a list of strings and not anything more maleable.

Autogenerated Legacy Documentation

Module containing shims around Flake8 2.x behaviour.

Previously, users would import get_style_guide() from flake8.engine. In 3.0 we no longer have an “engine” module but we maintain the API from it.

flake8.api.legacy.get_style_guide(**kwargs)

Provision a StyleGuide for use.

Parameters:**kwargs – Keyword arguments that provide some options for the StyleGuide. Returns:An initialized StyleGuide Return type:StyleGuide

class flake8.api.legacy.StyleGuide(application)

Public facing object that mimic’s Flake8 2.0’s StyleGuide.

Note

There are important changes in how this object behaves compared to the StyleGuide object provided in Flake8 2.x.

Warning

This object should not be instantiated directly by users.

Changed in version 3.0.0.

options

Return application’s options.

An instance of argparse.Namespace containing parsed options.

paths

Return the extra arguments passed as paths.

class flake8.api.legacy.Report(application)

Public facing object that mimic’s Flake8 2.0’s API.

Note

There are important changes in how this object behaves compared to the object provided in Flake8 2.x.

Warning

This should not be instantiated by users.

Changed in version 3.0.0.

total_errors

Return the total number of errors.