Write your own plugin

Minimum example

A plugin is a subclass of Plugin. Define such a class in a python file located in the right directory.

from evariste import plugins

class Foo(plugins.Plugin):
    """Example plugin"""

    keyword = "foo"

The only mandatory attribute or method is the keyword attribute, which must be unique. It will be used to enable your plugin in the setup file.

That’s it! You can now enable it in the setup file:

[setup]
plugins = foo

You are now a proud owner of a plugin that does… nothing. To interact with Évariste, you can:

Of cours, your plugin can do everything listed above, at once.

Attributes

Several useful attributes are defined for every Plugin instance; they are defined in the class documentation. The most complex one are Plugin.shared and Plugin.local.

Plugin.shared

This attribute is a Shared instance, shared among every Plugin and Tree object. It has three attributes, which are all DeepDict instances (in the following examples, shared is an instance of Shared):

  • setup is a representation of the setup file. For instance, option bar of section foo can be read (and set) as shared.setup["foo"]["bar"].

  • plugin is a DeepDict where each plugin can store data that is cached, and accessible from other plugins. Plugin foo can set shared.plugin["foo"] at whatever value it wants. Technically, you can get and set values for other plugins, but think twice before doing so: do the other plugin expect you to get and set its data?

  • tree is a DeepDict where each plugin can store data about tree instances that is cached, and accessible from other plugins. Plugin foo can set whatever information its want about Tree instance tree in shared.tree[tree]["foo"].

Data that is set in Shared attributes plugin and tree is pickled so make sure data you save there are picklable.

Plugin.local

Most of the time, your plugin will only access its own section in the setup file, or in the other attributes of the Plugin.shared attribute. To make things easier, the very same data is also available in Plugin.local. Let’s consider an instance foo of a plugin foo

  • foo.local.setup is a dictionary of the options of foo in the setup file: foo.local.setup is a shortcut for foo.shared.setup["foo"].

  • foo.local.plugin is a shortcut for foo.shared.plugin["foo"] (cached data for this plugin).

  • Given a Tree object mytree, then foo.local.tree[mytree] is a shortcut for foo.shared.tree[mytree]["foo"].

Plugin.default_setup and Plugin.global_default_setup

For any plugin, attributes Plugin.default_setup is default setup of the section Plugin.keyword, while Plugin.global_default_setup is the whole default setup (for all sections).

When reading the setup file, options that are not set are filled with options of Plugin.default_setup, and sections that are not set are filled with sections of Plugin.global_default_setup.

For instance, consider the following plugin:

class Foo(Plugin):
    keyword = "foo"
    default_setup = {
        "foo1": "default1",
        "foo2": "default2",
        }
    global_default_setup = {
        "bar": {
            "bar1": "global1",
            "bar2": "global2",
            },
        "foo": {
            "foo1": "global1",
            "foo3": "global3",
            },
        }

Now, this plugin is loaded with the following setup file:

[setup]
plugins = foo

[foo]
foo2 = setup2
foo4 = setup4

[bar]
bar1 = setup1
bar3 = setup3

Then, once the setup file, and both Plugin.default_setup and Plugin.global_default_setup has been taken into account, the resulting setup is equivalent to:

[setup]
plugins = foo

[foo]
foo1 = default1
foo2 = setup2
foo4 = setup4

[bar]
bar1 = setup1
bar2 = global2
bar3 = setup3

Notice that:

Current working directory

Note that as early as possible, the working directory is changed to the directory of the setup file given in argument to evariste.

Interacting with Évariste

Note that it is also possible to write evs plugins.