Plugins

class PluginBase

PluginBase(pluginRun=None, client=None, **kwargs)

Base class for plugins

PluginBase is the base class of all Pymemri plugins. You can either build your plugin from scratch, or start with one of our Plugins Templates.

All inheriting classes should implement:

Note that both the pluginRun and client arguments are mandatory for running a plugin. When using the run_plugin CLI, these are handled for you. For local development and testing, a plugin can be initialized with just a client, which results in a RuntimeWarning.

Example plugin

Let's use the following plugin as an example of how we can define and run plugins.

from pymemri.pod.client import Dog
class ExamplePlugin(PluginBase):
    def __init__(self, dog_name: str = "Bob", **kwargs):
        super().__init__(**kwargs)
        self.dog_name = dog_name
    def run(self):
        print("Started plugin run...")
        dog = Dog(self.dog_name, 10)
        self.client.create(dog)
        print("Run success!")
    def add_to_schema(self):
        self.client.add_to_schema(Dog)

Authentication

Many plugins use authentication for external services that require passwords or oauth authentication. Pymemri implements some common cases, see OAuthAuthenticator or PasswordAuthenticator.

Running your plugin using the CLI

Plugins can be started using the pymemri run_plugin or simulate_run_plugin_from_frontend CLI. With run_plugin the plugin is invoked directly by spawning a new python process, while simulate_run_plugin_from_frontend requests the pod to spawn a new process, docker container, or kubernetes container, which in calls run_plugin (for more info see simulate_run_plugin_from_frontend. When using run_plugin, you can either pass your run arguments as parameters, or set them as environment variables. If both are set, the CLI will use the passed arguments.

run_plugin

run_plugin(pod_full_address:"The pod full address"='http://localhost:3030', plugin_run_id:"Run id of the plugin to be executed"=None, database_key:"Database key of the pod"=None, owner_key:"Owner key of the pod"=None, read_args_from_env:"Read the args from the environment"=False, metadata:"metadata file for the PluginRun"=None, config_file:"A plugin configuration, overwrites the configuration of the PluginRun"=None)

To start a plugin on your local machine, you can use the CLI. This will create a client for you, initialize the plugin, and run the code defined in the run method of your plugin.

!run_plugin --metadata "../example_plugin.json"
reading database_key from /home/eelco/.pymemri/pod_keys/keys.json
reading owner_key from /home/eelco/.pymemri/pod_keys/keys.json
pod_full_address=http://localhost:3030
owner_key=3115475769495298505787935906714974107670251574210177626680528981
writing run info to /home/eelco/.pymemri/plugins/pymemri/current_run.json
Started plugin run...
Run success!

Plugin configuration

Often, plugins require some configuration for a run. For example, our ExamplePlugin has a dog_name argument, which could be different for different runs.

Pymemri handles plugin configuration by passing a dictionary of configuration values to the __init__ method of the plugin. A possible configuration for the ExamplePlugin could be:

{"dog_name": "Alice"}

Configuration can be passed to the run_plugin CLI in two ways:

  • Defined in the PluginRun item, as config property. This value should be a json serialized dictionary, which is deserialized and passed to the plugin by the CLI
  • Defined in a json file and passed to run_plugin as a --config_file argument. If this option is used, the config property from the PluginRun is ignored.

Run from pod

In production, we start plugins by making an API call to the pod, which in turn creates an environment for the plugin and starts it using docker containers, kubernetes containers or a shell script. We can start this process using the simulate_run_plugin_from_frontend CLI. Note that when using docker, provided container name should be built within the Pod environment (e.g. docker build -t pymemri . for this repo), or available on the memri gitlab container repository.

running a plugin

simulate_run_plugin_from_frontend

simulate_run_plugin_from_frontend(pod_full_address:"The pod full address"='http://localhost:3030', database_key:"Database key of the pod"=None, owner_key:"Owner key of the pod"=None, container:"Pod container to run frod"=None, plugin_path:"Plugin path"=None, metadata:"metadata file for the PluginRun"=None, config_file:"A plugin configuration, overwrites the configuration of the PluginRun"=None, account_id:"Account id to be used inside the plugin"=None)

Example usage

!simulate_run_plugin_from_frontend --metadata "../example_plugin.json"
reading database_key from /home/eelco/.pymemri/pod_keys/keys.json
reading owner_key from /home/eelco/.pymemri/pod_keys/keys.json
pod_full_address=http://localhost:3030
owner_key=0669504049511661364795770949641722972379709465482258592795264679
Created pluginrun with id DDDFb7dFDeFF5c5917e7f846BF5df099 on http://localhost:3030
writing run info to /home/eelco/.pymemri/plugins/pymemri/current_run.json
*Check the pod log/console for debug output.*