evariste.plugins

Plugin base class and plugin loader

Every plugin is a subclass of Plugin (see Write your own plugin for more information).

The Loader class finds and loads the plugins.

Constants

evariste.plugins.MANDATORY_PLUGINS = {'action.cached', 'action.directory', 'action.noplugin', 'action.raw', 'changed', 'logging', 'tree'}

Set of mandatory plugins: plugins that are loaded by default, and cannot be disabled.

Plugin

class evariste.plugins.Plugin(shared)[source]

Plugin base: all imported plugins must be subclasses of this class.

See Write your own plugin to see how to write a new plugin.

Parameters:

shared (Shared) – The object shared among plugins.

default_setup: dict[str, str] = {}

Default value for section self.keyword in the setup file. It may be overwritten by data provided by user in the setup file. See Plugin.default_setup and Plugin.global_default_setup.

depends: Iterator[str] = ()

Iterable of plugins this plugin depends on. When this plugin is enabled, those plugins are enabled as well.

classmethod depends_dynamic(shared) → Iterator[str][source]

Iterator of plugins this plugin depends on (as an iterator of str)

When this plugin is enabled, those plugins are enabled as well.

Parameters:

shared (Shared) – Shared object of the current builder.

Warning: called before everything is settled down

global_default_setup: dict[str, dict[str, str]] = {}

Default values for setup file. See Plugin.default_setup and Plugin.global_default_setup.

keyword: None | str = None

Keyword plugin, used to reference it: it is used to enable plugins in the setup file, to name its section in the setup file, etc.

local

Same as Plugin.shared, but from this plugin point of view: see evariste.shared.Shared.get_plugin_view() and Plugin.local.

match(value, *args, **kwargs) → bool[source]

Return True iff value matches self.

Default is keyword match. This method can be overloaded by subclasses.

plugin_type: str = ''

Type of the plugin. Plugins of the same type gather some common behaviour.

priority: int = 0

When Évariste has to choose one plugin among several one, it chooses the one with higher priority.

shared: Shared

Common data shared with every Tree and Plugin of this Builder.

Loader

class evariste.plugins.Loader(*, shared)[source]

Load plugins

Parameters:

shared (evariste.shared.Shared) – The shared object among plugins.

The constructor (Loader.__init__()):

  • reads the setup file (looking for the libdirs option);

  • search all plugins (subclasses of Plugin);

  • instanciate:

  • store them in some attribute, so that they can be accessed later.

applyiterhook(hookname: str, *args, **kwargs) → Iterable[source]

Apply an iteration hook.

Run every fonction hooked to this name (they should be iterators), and iterate over the chain of those iterators.

Parameters:

  • hookname (str) – Name of the hook to apply.

  • arg (list) – Positional arguments passed to the hooks.

  • kwargs (dict) – Named arguments passed to the hooks.

get_plugin(keyword: str) → Plugin[source]

Return the plugin with the given keyword.

Raises:

NoMatch – If no (loaded) plugin was found with this keyword.

items(plugin_type: str | None = None) → Iterable[tuple[str, Plugin]][source]

Iterate over plugin keywords.

Parameters:

plugin_type (Optional[str]) – See Loader.iter().

iter(plugin_type: str | None = None) → Iterable[Plugin][source]

Iterate over keywords.

Parameters:

plugin_type (Optional[str]) –

Type of the plugins to iterate over.

  • if None, iterate over keywords of every (loaded) plugins;

  • else, iterate over keywords of plugins of this given type only.

match(plugin_type: str | None, value) → Plugin[source]

Return the first plugin matching value.

A plugin Foo matches value if Foo.match(value) returns True.

Parameters:

plugin_type (Optional[str]) – See Loader.iter().

values(plugin_type: str | None = None) → Iterable[Plugin][source]

Iterate over plugins.

Parameters:

plugin_type (Optional[str]) – See Loader.iter().

Functions

evariste.plugins.find_plugins(libdirs: Iterable[str] | None = None) → Iterator[Plugin][source]

Iterate over available plugins.

Parameters:

libdirs (Iterable[str]) – Additional iterable of directories where plugins can be found.

Exceptions

class evariste.plugins.NoMatch(value, available)[source]

No plugin found matching value.

The Plugin class has a handful of subclasses.