mirror of
https://github.com/AdaCore/e3-core.git
synced 2026-02-12 12:29:08 -08:00
64fbb7f1fb
Use sphinx-autoapi to generate the api documentation and retrieve initial doc from the GitHub wiki. Add a tox command to build the doc: tox -e docs
64 lines
1.9 KiB
ReStructuredText
64 lines
1.9 KiB
ReStructuredText
.. _plugin:
|
|
|
|
Using abc and stevedore to write plugins
|
|
========================================
|
|
|
|
Introduction
|
|
------------
|
|
|
|
``e3-core`` is designed to be small and to be easy to configure and extend by
|
|
loading external code dynamically. In order to discover and load the plugins at runtime ``e3-core`` uses setuptools entry points. To ease the management of the plugins and avoid hard to detect errors, the ``e3`` project uses ``stevedore`` and ``abc``.
|
|
|
|
An entry point is a way to reference an object defined in another Python package.
|
|
In ``e3`` these objects are classes derived from an abstract base class (using ``abc``) defining the plugin interface.
|
|
|
|
Namespaces
|
|
----------
|
|
|
|
The namespace for ``e3`` entry point are all prefixed with ``e3.`` in order to
|
|
avoid polluting the namespace.
|
|
|
|
e3-core plugins
|
|
---------------
|
|
|
|
``e3-core`` defines and uses the following plugins interface:
|
|
|
|
e3-sandbox
|
|
^^^^^^^^^^
|
|
|
|
The command line actions for ``e3-sandbox`` can be provided by external plugins registered in the ``e3.anod.sandbox.sandbox_action`` namespace.
|
|
To add another action subclass :class::`e3.anod.sandbox.SandBoxAction` and
|
|
reference your new class in the ``e3.anod.sandbox.sandbox_action`` entry points namespace.
|
|
|
|
Example
|
|
"""""""
|
|
|
|
In a package ``e3-contrib``, define a new class:
|
|
|
|
.. code-block:: python
|
|
|
|
class SandBoxActionExample(e3.anod.sandbox.SandBoxAction):
|
|
|
|
name = 'example'
|
|
help = 'An example of e3-sandbox action'
|
|
|
|
def add_parser(self):
|
|
self.parser.add_argument(
|
|
'--another-command-line')
|
|
|
|
def run(self.args):
|
|
sandbox = e3.anod.sandbox.SandBox()
|
|
sandbox.root_dir = args.sandbox
|
|
|
|
# Run any action on the sandbox
|
|
# ...
|
|
|
|
Then register it in ``e3-contrib/setup.py``:
|
|
|
|
.. code-block:: python
|
|
|
|
entry_points={
|
|
'e3.anod.sandbox.sandbox_action': [
|
|
'example = e3.contrib.sandbox.SandBoxActionExample',
|
|
]}
|