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."""


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 simplicitly 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)[source]

Class defining the formatter interface.


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


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


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


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


Initialize the formatter further.


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.

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 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 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.

Format and print the benchmarks.


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

Format and print the statistics.


Prepare the formatter to receive input.

This defaults to initializing output_fd if filename


Clean up after reporting is finished.

write(line, source)[source]

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.

  • 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.