Developing a Formatting Plugin for Flake8

Flake8 allowed for custom formatting plugins in version 3.0.0. Let’s write a plugin together:

from flake8.formatting import base


class Example(base.BaseFormatter):
    """Flake8's example formatter."""

    pass

We notice, as soon as we start, that we inherit from Flake8’s BaseFormatter class. If we follow the instructions to register a plugin and try to use our example formatter, e.g., flake8 --format=example then Flake8 will fail because we did not implement the format method. Let’s do that next.

class Example(base.BaseFormatter):
    """Flake8's example formatter."""

    def format(self, error):
        return 'Example formatter: {0!r}'.format(error)

With that we’re done. Obviously this isn’t a very useful formatter, but it should highlight the simplicity of creating a formatter with Flake8. If we wanted to instead create a formatter that aggregated the results and returned XML, JSON, or subunit we could also do that. Flake8 interacts with the formatter in two ways:

1. It creates the formatter and provides it the options parsed from the configuration files and command-line

2. It uses the instance of the formatter and calls handle with the error.

By default flake8.formatting.base.BaseFormatter.handle() simply calls the format method and then write. Any extra handling you wish to do for formatting purposes should override the handle method.

API Documentation

class flake8.formatting.base.BaseFormatter(options: optparse.Values)

Class defining the formatter interface.

options

The options parsed from both configuration files and the command-line.

filename

If specified by the user, the path to store the results of the run.

output_fd

Initialized when the start() is called. This will be a file object opened for writing.

newline

The string to add to the end of a line. This is only used when the output filename has been specified.

after_init() → None

Initialize the formatter further.

beginning(filename: str) → None

Notify the formatter that we’re starting to process a file.

Parameters

filename (str) – The name of the file that Flake8 is beginning to report results from.

finished(filename: str) → None

Notify the formatter that we’ve finished processing a file.

Parameters

filename (str) – The name of the file that Flake8 has finished reporting results from.

format(error: Violation) → Optional[str]

Format an error reported by Flake8.

This method must be implemented by subclasses.

Parameters

error (flake8.style_guide.Violation) – This will be an instance of Violation.

Returns

The formatted error string.

Return type

str

handle(error: Violation) → None

Handle an error reported by Flake8.

This defaults to calling format(), show_source(), and then write(). To extend how errors are handled, override this method.

Parameters

error (flake8.style_guide.Violation) – This will be an instance of Violation.

show_benchmarks(benchmarks: List[Tuple[str, float]]) → None

Format and print the benchmarks.

show_source(error: Violation) → Optional[str]

Show the physical line generating the error.

This also adds an indicator for the particular part of the line that is reported as generating the problem.

Parameters

error (flake8.style_guide.Violation) – This will be an instance of Violation.

Returns

The formatted error string if the user wants to show the source. If the user does not want to show the source, this will return None.

Return type

str

show_statistics(statistics: Statistics) → None

Format and print the statistics.

start() → None

Prepare the formatter to receive input.

This defaults to initializing output_fd if filename

stop() → None

Clean up after reporting is finished.

write(line: Optional[str], source: Optional[str]) → None

Write the line either to the output file or stdout.

This handles deciding whether to write to a file or print to standard out for subclasses. Override this if you want behaviour that differs from the default.

Parameters

• line (str) – The formatted string to print or write.

• source (str) – The source code that has been formatted and associated with the line of output.