mirror of
https://github.com/PyCQA/flake8.git
synced 2026-03-29 18:46:52 +00:00
103 lines
3.4 KiB
ReStructuredText
103 lines
3.4 KiB
ReStructuredText
===================
|
|
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`
|