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:
PluginBase.run, which implements the logic of the pluginPluginBase.add_to_schema, for adding plugin specific item types to the Pod
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.
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):
schema_classes = [Dog]
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!")
Many plugins use authentication for external services that require passwords or oauth authentication. Pymemri implements some common cases, see OAuthAuthenticator or PasswordAuthenticator.
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.
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"
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
PluginRunitem, asconfigproperty. 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_pluginas a--config_fileargument. If this option is used, theconfigproperty from thePluginRunis ignored.
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.
!simulate_run_plugin_from_frontend --metadata "../example_plugin.json"