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)

Class defining the formatter interface.

Parameters:

options (Namespace) –

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()

Initialize the formatter further.

Return type:

None

beginning(filename)

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.

Return type:

None

finished(filename)

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.

Return type:

None

format(error)

Format an error reported by Flake8.

This method must be implemented by subclasses.

Parameters:

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

Returns:

The formatted error string.

Return type:

str | None

handle(error)

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 (Violation) – This will be an instance of Violation.

Return type:

None

show_benchmarks(benchmarks)

Format and print the benchmarks.

Parameters:

benchmarks (List[Tuple[str, float]]) –

Return type:

None

show_source(error)

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 (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 | None

show_statistics(statistics)

Format and print the statistics.

Parameters:

statistics (Statistics) –

Return type:

None

start()

Prepare the formatter to receive input.

This defaults to initializing output_fd if filename

Return type:

None

stop()

Clean up after reporting is finished.

Return type:

None

write(line, 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.

Parameters:

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

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

Return type:

None