Developing 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 simple plugin that accepts no arguments, prints out Hello world! and returns no value requires the following code:

from inmanta.plugins import plugin

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

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

import example

example::hello()

Note

A module’s Python code lives in the inmanta_plugins.<module_name> namespace.

A more complex plugin accepts arguments and returns a value. Compared to what python supports as function arguments, only positional-only arguments are not supported. The following example creates a plugin that converts a string to uppercase:

from inmanta.plugins import plugin

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

This plugin can be tested with:

import example

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

If your plugin requires external libraries, add them as dependencies of the module. For more details on how to add dependencies see Understanding Modules.

Passing entities into plugins

Entities can also be passed into plugins. The python code of the plugin can navigate relations throughout the orchestration model to access attributes of other entities.

This example searches for a specific subnet entity fo a specific IP in a list of subnet entities.

@plugin
def find_subnet_for(
    the_ip: "std::ipv4_address",
    subnets: "Subnet[]",
) -> "Subnet":
    """find a network containing the ip"""
    ip = IPAddress(the_ip)
    for subnet in subnets:
        if ip in IPNetwork(subnet.ip_subnet):
            return subnet
    raise NoSubnetFoundForIpException(the_ip)

When passing entities into a plugin:

  1. the actual python type of the object will be inmanta.execute.proxy.DynamicProxy

  2. the entities can not be modified

  3. when traversing a relation or accessing an attribute, that has no value yet, we will raise an inmanta.ast.UnsetException. The plugin will be re-executed when the value is known. This means that this exception must never be blocked and that code executing before the last attribute or relation access can be executed multiple times.

Raising Exception

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.

1from inmanta.plugins import plugin, PluginException
2
3@plugin
4def raise_exception(message: "string") -> None:
5    raise PluginException(message)

Adding new plugins

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 be annotated with the allowed types from the orchestration model.

To provide this DSL typing information, you can use either:

  • python types (e.g. str)

  • inmanta types (e.g. string)

Type hinting using python types

Pass the native python type that corresponds to the DSL type at hand. e.g. the foo plugin defined below can be used in a model, in a context where the following signature is expected string -> int[]:

1from inmanta.plugins import plugin
2from collections.abc import Sequence
3
4
5@plugin
6def foo(value: str) -> Sequence[int]:
7    ...

This approach is the recommended way of adding type information to plugins as it allows you to use mypy when writing plugin code.

This approach also fully supports the use of Union types (e.g. Union[str, int] for an argument or a return value, that can be of either type).

The table below shows correspondence between types from the Inmanta DSL and their respective python counterpart:

Inmanta DSL type

Python type

string

str

int

int

float

float

int[]

collections.abc.Sequence[int]

dict[int]

collections.abc.Mapping[str, int]

string?

str | None

any

typing.Any

any is a special type that effectively disables type validation.

We also give some liberty to the user to define python types for Inmanta DSL types that are not present on this table.

This is done by combining typing.Annotated with inmanta.plugins.ModelType. The first parameter of typing.Annotated will be the python type we want to assume for typechecking and the second will be the inmanta.plugins.ModelType with the Inmanta DSL type that we want the compiler to validate.

For example, if we want to pass a std::Entity to our plugins and have python validate its type as typing.Any, we could do this:

1from inmanta.plugins import plugin, ModelType
2from typing import Annotated, Any
3
4type Entity = Annotated[Any, ModelType["std::Entity"]]
5
6@plugin
7def my_plugin(my_entity: Entity) -> None:
8    ...

Our compiler will validate my_entity as std::Entity, meaning that we will only be able to provide a std::Entity as an argument to this plugin, but for IDE and static typing purposes it will be treated as typing.Any.

Type hinting using Inmanta DSL types

Alternatively, the Inmanta DSL type annotations can be provided as a string (Python3 style argument annotation) that refers to Inmanta primitive types or to entities.

1from inmanta.plugins import plugin
2
3@plugin
4def foo(value: "string") -> "int[]":
5    ...

Renaming plugins

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:

1from inmanta.plugins import plugin
2
3@plugin("print")
4def printf() -> None:
5    """
6        Prints inmanta
7    """
8    print("inmanta")

Dataclasses

When you want to construct entities in a plugin, you can use dataclasses.

An inmanta dataclass is an entity that has a python counterpart. When used in a plugin, it is a normal python object, when used in the model, it is a normal Entity.

import dataclasses

from inmanta.plugins import plugin

@dataclasses.dataclass(frozen=True)
class Virtualmachine:
    name: str
    ram: int
    cpus: int

@plugin
def make_virtual_machine() -> Virtualmachine:
    return Virtualmachine(name="Test", ram=5, cpus=12)

entity Virtualmachine extends std::Dataclass:
    string name
    int ram
    int cpus
end

implement Virtualmachine using std::none

vm = make_virtual_machine()
std::print(vm.name)

When using dataclasses, the object can be passed around freely into and out of plugins.

However, some restrictions apply: The python class is expected to be:

  • a frozen dataclass

  • with the same name

  • in the plugins package of this module

  • in the corresponding submodule

  • with the exact same fields

The Inmanta entity is expected to:

  • have no relations

  • have no indexes

  • have only std::none as implementation

  • extend std::Dataclass

Note

When the inmanta entity and python class don’t match, the compiler will print out a correction for both. This means you only ever have to write the Entity, because the compiler will print the python class for you to copy paste.

Dataclasses can also be passed into plugins. When the type is a dataclass, it will always be converted to the python dataclass form. When you want pass it in as a normal entity, you have to use annotated types and declare the python type to be ‘DynamicProxy`.

import dataclasses
from typing import Annotated

from inmanta.execute.proxy import DynamicProxy
from inmanta.plugins import plugin, ModelType


@dataclasses.dataclass(frozen=True)
class Virtualmachine:
    name: str
    ram: int
    cpus: int


@plugin
def is_virtual_machine(vm: Virtualmachine) -> None:
    # The declared type is a python type, so we receive an actual python object
    assert isinstance(vm, Virtualmachine)

@plugin
def is_dynamic_proxy(vm: Annotated[DynamicProxy, ModelType["Virtualmachine"]]) -> None:
    # Explicitly request DynamicProxy to prevent the dataclass from being converted
    assert isinstance(vm, DynamicProxy)

entity Virtualmachine extends std::Dataclass:
    string name
    int ram
    int cpus
end

implement Virtualmachine using std::none

vm = Virtualmachine(name="test", ram=5, cpus=5)
is_virtual_machine(vm)
is_dynamic_proxy(vm)

Deprecate plugins

To deprecate a plugin the deprecated() decorator can be used in combination with the plugin() decorator. Using this decorator will log a warning message when the function is called. This decorator also accepts an optional argument replaced_by which can be used to potentially improve the warning message by telling which other plugin should be used in the place of the current one.

For example if the plugin below is called:

1from inmanta.plugins import plugin, deprecated
2
3@deprecated(replaced_by="my_new_plugin")
4@plugin
5def printf() -> None:
6    """
7        Prints inmanta
8    """
9    print("inmanta")

it will give following warning:

Plugin 'printf' in module 'inmanta_plugins.<module_name>' is deprecated. It should be replaced by 'my_new_plugin'

Should the replace_by argument be omitted, the warning would look like this:

Plugin 'printf' in module 'inmanta_plugins.<module_name>' is deprecated.