===================
 Public Python API
===================

|Flake8| 3.0.0 presently does not have a public, stable Python API.

When it does it will be located in :mod:`flake8.api` and that will
be documented here.


Legacy API
==========

When |Flake8| broke its hard dependency on the tricky internals of
pycodestyle, it lost the easy backwards compatibility as well. To help
existing users of that API we have :mod:`flake8.api.legacy`. This module
includes a couple classes (which are documented below) and a function.

The main usage that the developers of Flake8 observed was using the
:func:`~flake8.api.legacy.get_style_guide` function and then calling
:meth:`~flake8.api.legacy.StyleGuide.check_files`. To a lesser extent,
people also seemed to use the :meth:`~flake8.api.legacy.Report.get_statistics`
method on what ``check_files`` returns. We then sought to preserve that
API in this module.

Let's look at an example piece of code together:

.. code-block:: python

    from flake8.api import legacy as flake8


    style_guide = flake8.get_style_guide(ignore=['E24', 'W503'])
    report = style_guide.check_files([...])
    assert report.get_statistics('E') == [], 'Flake8 found violations'

This represents the basic universal usage of all existing Flake8 2.x
integrations. Each example we found was obviously slightly different,
but this is kind of the gist, so let's walk through this.

Everything that is backwards compatible for our API is in the
:mod:`flake8.api.legacy` submodule. This is to indicate, clearly, that
the old API is being used.

We create a |StyleGuide| by calling |style_guide|.  We can pass options
to |style_guide| that correspond to the command-line options one might use.
For example, we can pass ``ignore``, ``select``, ``exclude``, ``format``, etc.
Our legacy API, does not enforce legacy behaviour, so we can combine
``ignore`` and ``select`` like we might on the command-line, e.g.,

.. code-block:: python

    style_guide = flake8.get_style_guide(
        ignore=['E24', 'W5'],
        select=['E', 'W', 'F'],
        format='pylint',
    )

Once we have our |StyleGuide| we can use the same methods that we used before,
namely

.. automethod:: flake8.api.legacy.StyleGuide.check_files

.. automethod:: flake8.api.legacy.StyleGuide.excluded

.. automethod:: flake8.api.legacy.StyleGuide.init_report

.. automethod:: flake8.api.legacy.StyleGuide.input_file

.. warning::

    These are not *perfectly* backwards compatible. Not all arguments are
    respsected, and some of the types necessary for something to work have
    changed.

Most people, we observed, were using
:meth:`~flake8.api.legacy.StyleGuide.check_files`. You can use this to specify
a list of filenames or directories to check. In |Flake8| 3.0, however, we
return a different object that has similar methods. We return a |Report| which
has the method

.. automethod:: flake8.api.legacy.Report.get_statistics

Most usage of this method that we noted was as documented above. Keep in mind,
however, that it provides a list of strings and not anything more malleable.


Autogenerated Legacy Documentation
----------------------------------

.. automodule:: flake8.api.legacy
    :members:

.. autoclass:: flake8.api.legacy.StyleGuide
    :members: options, paths

.. autoclass:: flake8.api.legacy.Report
    :members: total_errors


.. |style_guide| replace:: :func:`flake8.api.legacy.get_style_guide`
.. |StyleGuide| replace:: :class:`flake8.api.legacy.StyleGuide`
.. |Report| replace:: :class:`flake8.api.legacy.Report`