1.. _formatting-plugins:
2
3===========================================
4 Developing a Formatting Plugin for Flake8
5===========================================
6
7|Flake8| allowed for custom formatting plugins in version
83.0.0. Let's write a plugin together:
9
10.. code-block:: python
11
12    from flake8.formatting import base
13
14
15    class Example(base.BaseFormatter):
16        """Flake8's example formatter."""
17
18        pass
19
20We notice, as soon as we start, that we inherit from |Flake8|'s
21:class:`~flake8.formatting.base.BaseFormatter` class. If we follow the
22:ref:`instructions to register a plugin <register-a-plugin>` and try to use
23our example formatter, e.g., ``flake8 --format=example`` then
24|Flake8| will fail because we did not implement the ``format`` method.
25Let's do that next.
26
27.. code-block:: python
28
29    class Example(base.BaseFormatter):
30        """Flake8's example formatter."""
31
32        def format(self, error):
33            return 'Example formatter: {0!r}'.format(error)
34
35With that we're done. Obviously this isn't a very useful formatter, but it
36should highlight the simplicity of creating a formatter with Flake8. If we
37wanted to instead create a formatter that aggregated the results and returned
38XML, JSON, or subunit we could also do that. |Flake8| interacts with the
39formatter in two ways:
40
41#. It creates the formatter and provides it the options parsed from the
42   configuration files and command-line
43
44#. It uses the instance of the formatter and calls ``handle`` with the error.
45
46By default :meth:`flake8.formatting.base.BaseFormatter.handle` simply calls
47the ``format`` method and then ``write``. Any extra handling you wish to do
48for formatting purposes should override the ``handle`` method.
49
50API Documentation
51=================
52
53.. autoclass:: flake8.formatting.base.BaseFormatter
54    :members:
55