From 8dd0d97e234783c1a9d9f88caaaaf13a5cb33542 Mon Sep 17 00:00:00 2001 From: Jacobo de Vera Date: Mon, 17 Oct 2022 22:59:10 +0100 Subject: [PATCH] Document the types of plugins and expected results --- docs/source/plugin-development/checkers.rst | 106 ++++++++++++++++++ docs/source/plugin-development/formatters.rst | 2 +- .../plugin-development/getting-started.rst | 39 +++++++ docs/source/plugin-development/index.rst | 51 +-------- .../plugin-development/plugin-types.rst | 22 ++++ 5 files changed, 171 insertions(+), 49 deletions(-) create mode 100644 docs/source/plugin-development/checkers.rst create mode 100644 docs/source/plugin-development/getting-started.rst create mode 100644 docs/source/plugin-development/plugin-types.rst diff --git a/docs/source/plugin-development/checkers.rst b/docs/source/plugin-development/checkers.rst new file mode 100644 index 0000000..da14f42 --- /dev/null +++ b/docs/source/plugin-development/checkers.rst @@ -0,0 +1,106 @@ +.. _checker-plugins: + +=============== +Checker Plugins +=============== + +A |Flake8| checker plugin needs to have a registered entry point. This entry +point must reference a callable object. + + +Declaring the type of plugin +============================ + +Flake8 uses certain key parameters to determine the kind of plugin this is and +how it needs to call it: + +* If it has a parameter called ``tree`` then this plugin is considered to be an + AST checker plugin. It will be called once per file and it will receive the + parsed AST of the file as the ``tree`` parameter. If this entry point + references a class, then the call will construct an instance of such class, + and Flake8 will then call the ``run()`` method on the created object to get + results. +* If the callable has a parameter called ``physical_line`` then whatever the + entry point references is called for each physical line and the call is + expected to yield results directly. +* If the callable has a parameter called ``logical_line`` then the callable + referred to by the entry point will be called from Flake8 with each logical + line and is expected to yield results. + + +.. note:: + Class-style plugins are only supported for AST checker (*tree*) plugins. + + +The Results +=========== + +Tree plugins +------------ + +A tree plugins can be a function or a class. If it is a function, it must take +a parameter called ``tree``. If it is a class, then the ``__init__`` method +must take this parameter. + +For a class based plugin, the ``run`` method is in charge of yielding results. +For functions, they must deliver results directly. + +Flake8 expects the result of running these plugins to be an iterable of tuples, +each of which contain the following: + +* An ``int`` with the line number where the issue appears + +* An ``int`` with the offset within the line where the issue appears (column) + +* A ``str`` with the error message + +* The source of the error (typically the name of the plugin). Although this + field is not used by |Flake8|, it must be present in each tuple + + +Physical Line plugins +--------------------- + +A Physical Line plugin must be callable, it must take a parameter called +``physical_line`` and it must return the result of checking the passed physical +line. + +Flake8 expects the result of this call to be an iterable of tuples, each +containing the following: + +* An ``int`` with the offset within the line where the reported issue appears + +* A ``str`` with the error message + + +Logical Line Plugins +-------------------- + +A Logical Line plugin must be callable, it must take a parameter called +``logical_line`` and it must return the result of checking the passed logical +line. + +Flake8 expects the result of this call to be an iterable of tuples, each +containing the following: + +* An ``int`` with the offset within the logical line where the reported issue + appears + +* A ``str`` with the error message + +|Flake8| will take care of the conversion from the reported offset on the +logical line to a physical line and physical column pair before it outputs +errors to the user. + + +Video Tutorial +============== + +Here's a tutorial which goes over building an AST checking plugin from scratch: + +.. raw:: html + +
+ +
+ diff --git a/docs/source/plugin-development/formatters.rst b/docs/source/plugin-development/formatters.rst index 8133567..88ad309 100644 --- a/docs/source/plugin-development/formatters.rst +++ b/docs/source/plugin-development/formatters.rst @@ -4,7 +4,7 @@ Developing a Formatting Plugin for Flake8 =========================================== -|Flake8| allowed for custom formatting plugins in version +|Flake8| allowes for custom formatting plugins since version 3.0.0. Let's write a plugin together: .. code-block:: python diff --git a/docs/source/plugin-development/getting-started.rst b/docs/source/plugin-development/getting-started.rst new file mode 100644 index 0000000..1ce70e8 --- /dev/null +++ b/docs/source/plugin-development/getting-started.rst @@ -0,0 +1,39 @@ +.. _getting-started: + +=============== +Getting Started +=============== + +To get started writing a |Flake8| :term:`plugin` you first need: + +- An idea for a plugin + +- An available package name on PyPI + +- One or more versions of Python installed + +- A text editor or IDE of some kind + +- An idea of what *kind* of plugin you want to build: + + * Formatter + + * Check + +Once you've gathered these things, you can get started. + +All plugins for |Flake8| must be registered via `entry points`_. In this +section we cover: + +- How to register your plugin so |Flake8| can find it + +- How to make |Flake8| provide your check plugin with information (via + command-line flags, function/class parameters, etc.) + +- How to make a formatter plugin + +- How to write your check plugin so that it works with |Flake8| 2.x and 3.x + + +.. _entry points: + https://setuptools.readthedocs.io/en/latest/pkg_resources.html#entry-points diff --git a/docs/source/plugin-development/index.rst b/docs/source/plugin-development/index.rst index c89e5f0..00a7336 100644 --- a/docs/source/plugin-development/index.rst +++ b/docs/source/plugin-development/index.rst @@ -9,60 +9,15 @@ documentation in this section may reference third-party documentation to reduce duplication and to point you, the developer, towards the authoritative documentation for those pieces. -Getting Started -=============== - -To get started writing a |Flake8| :term:`plugin` you first need: - -- An idea for a plugin - -- An available package name on PyPI - -- One or more versions of Python installed - -- A text editor or IDE of some kind - -- An idea of what *kind* of plugin you want to build: - - * Formatter - - * Check - -Once you've gathered these things, you can get started. - -All plugins for |Flake8| must be registered via `entry points`_. In this -section we cover: - -- How to register your plugin so |Flake8| can find it - -- How to make |Flake8| provide your check plugin with information (via - command-line flags, function/class parameters, etc.) - -- How to make a formatter plugin - -- How to write your check plugin so that it works with |Flake8| 2.x and 3.x - - -Video Tutorial -============== - -Here's a tutorial which goes over building an ast checking plugin from scratch: - -.. raw:: html - -
- -
.. toctree:: :caption: Plugin Developer Documentation :maxdepth: 2 + getting-started + plugin-types registering-plugins plugin-parameters + checkers formatters - - -.. _entry points: - https://setuptools.readthedocs.io/en/latest/pkg_resources.html#entry-points diff --git a/docs/source/plugin-development/plugin-types.rst b/docs/source/plugin-development/plugin-types.rst new file mode 100644 index 0000000..dde664e --- /dev/null +++ b/docs/source/plugin-development/plugin-types.rst @@ -0,0 +1,22 @@ +.. _plugin-types: + +================ +Types of Plugins +================ + +|Flake8| supports two types of plugins: + +- **Check Plugins**: Plugins that contribute additional code checks that will + get reported together with |Flake8|'s default checks. In these, there are + three different ways these checks can happen: + + * Once per file. Your checker plugin will be called once per file and it will + receive a parsed AST for the file. + + * Once per physical line. + + * Once per logical line. + +- **Report Plugins**: Plugins that receive errors and modify the way these are + reported. They can take care of formatting, filtering, aggregating, etc. +