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:
It creates the formatter and provides it the options parsed from the configuration files and command-line
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.
- 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.
- newline¶
The string to add to the end of a line. This is only used when the output filename has been specified.
- beginning(filename)[source]¶
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)[source]¶
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)[source]¶
Format an error reported by Flake8.
This method must be implemented by subclasses.
- handle(error)[source]¶
Handle an error reported by Flake8.
This defaults to calling
format()
,show_source()
, and thenwrite()
. To extend how errors are handled, override this method.- Parameters
error (Violation) – This will be an instance of
Violation
.- Return type
None
- show_source(error)[source]¶
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.
- show_statistics(statistics)[source]¶
Format and print the statistics.
- Parameters
statistics (Statistics) –
- Return type
None
- start()[source]¶
Prepare the formatter to receive input.
This defaults to initializing
output_fd
iffilename
- Return type
None