Plugins

Plugins provide functions that can be called from the DSL. This is the primary mechanism to interface Python code with the orchestration model at compile time. For Example, this mechanism is also used for std::template and std::file. In addition to this, Inmanta also registers all plugins with the template engine (Jinja2) to use as filters.

A plugin is a python function, registered with the platform with the plugin() decorator. This plugin accepts arguments when called from the DSL and can return a value. Both the arguments and the return value must by annotated with the allowed types from the orchestration model. Type annotations are provided as a string (Python3 style argument annotation). any is a special type that effectively disables type validation.

Through the arguments of the function, the Python code in the plugin can navigate the orchestration model. The compiler takes care of scheduling the execution at the correct point in the model evaluation.

A simple plugin that accepts no arguments, prints out “hello world” and returns no value requires the following code:

1
2
3
4
5
from inmanta.plugins import plugin

@plugin
def hello():
    print("Hello world!")

If the code above is placed in the plugins directory of the example module (examples/plugins/__init__.py) the plugin can be invoked from the orchestration model as follows:

import example

example::hello()

The plugin decorator accepts an argument name. This can be used to change the name of the plugin in the DSL. This can be used to create plugins that use python reserved names such as print for example:

1
2
3
4
5
6
7
8
from inmanta.plugins import plugin

@plugin("print")
def printf():
    """
        Prints inmanta
    """
    print("inmanta")

A more complex plugin accepts arguments and returns a value. The following example creates a plugin that converts a string to uppercase:

1
2
3
4
5
from inmanta.plugins import plugin

@plugin
def upper(value: "string") -> "string":
    return value.upper()

This plugin can be tested with:

import example

std::print(example::upper("hello world"))

Argument type annotations are strings that refer to Inmanta primitive types or to entities. If an entity is passed to a plugin, the python code of the plugin can navigate relations throughout the orchestration model to access attributes of other entities.

A base exception for plugins is provided in inmanta.plugins.PluginException. Exceptions raised from a plugin should be of a subtype of this base exception.

1
2
3
4
5
from inmanta.plugins import plugin, PluginException

@plugin
def raise_exception(message: "string"):
    raise PluginException(message)

If your plugin requires external libraries, include a requirements.txt in the module. The libraries listed in this file are automatically installed by the compiler and agents.