Alterator backends use a very simple communication protocol and can be written in any language. This library contains a set of functions to simplify development of backend on Python.

Main event loop is provided by message_loop function. You must provide your own on_message callback (that accepts contents of Alterator's message in message argument). All incoming parameters are provided as-is (unlike alterator-sh-functions, i.e. without in_ prefix, exactly like in alterator-perl-functions). For example, incoming parameter 'foo' can be found as a key "foo" in message dict.

You should write output parameters using functions with prefix write_. Some parameter names have special meaning. There are: action, _objects, language, expert_mode.

Usually callback determine action using 'action' parameter. Some action types have special meaning. There are: type, help.

Backend's stdout is redirected to stderr, so you can safely write to it. But don't read from stdin, if you are not sure what you doing! Alterator uses stdin to communicate with your backend.

Simple Backend

Simple backend on Python looks like that:

#!/usr/bin/env python3

from alterator_bindings import backend3
from alterator_bindings.backend3 import *

# Set True if you want to see debug messages
backend3.ALTERATOR_DEBUG = True 

# Dictionary to use for translation (usually just alterator module name)
# Will set to running backend filename by default (So may be not what you need)
backend3.TEXTDOMAIN = "alterator-test"

# message object is Python's dict, containing pairs attribute-value from Alterator
def on_message(message: dict):
    match message.get("action"):
        case "read":
            write_string_param('name', 'value')
        case _:
            write_error("Unsupported action: {}".format(message.get("action")))

message_loop(on_message)

Functionality description

Globals (may be set by user)

backend3.ALTERATOR_DEBUG (Default is False) - Indicates if additional debug output (to stderr) is needed (messages from alterator, etc.). Also with this flag write_debug won't be silent (will print messages to stderr)
backend3.TEXTDOMAIN(Defaults to alterator-{running backend filename}) - Sets dictionary used for translations. If not set manually, warning will be printed

Functions

Common functions:

message_loop - Main event loop. Message callback should be specified when calling this function.
on_message - Your (!!!) callback function. All incoming parameters are passed as message argument with type dict. All parameters are stored in this dict by name-value pair. All params are named by it's Alterator originals (Basically as in alterator-sh-functions, but without in_ prefix. So $in__objects here is "_objects", $in_action is "action", etc.)
translate(text: str, domain=None) - Output translated string. Optional param domain allows you to replace a default dictionary (TEXTDOMAIN) with your one. This is a wrapper over gettext utility. You may import this function as _ to match alterator-sh-functions naming.

Functions for processing of incoming parameters:

test_bool(value) - Incoming boolean variable are represented as a string with value '#t' or '#f'. This representation can be changed in the future and we are strongly recommend you to use test_bool function to test variable for True value.

Functions for writing output parameters:

write_string_param(name, value) - Write parameter of string type with name name and value value.
write_bool_param(name, value) - Write parameter of boolean type with name name and value value. value may be either Python's bool type (recommended error-proof way) or str: Strings '1', 'true', 'yes', 'y', and 'on' are treated as a true value, all other strings a treated as a false value.
write_enum_item(name, label=None) - Write member of enumeration. Optional parameter label is a descriptive member name visible for users (default to name value).
write_table_item(row: dict) - Sometimes we need to fill tables or multicolumn lists in interface. This function will print attributes and it's values for one line of a such table (row is dict with pairs column-value). Please note that all attributes should be of a type "string".
write_error(message) - This is a function to notify about problems in backend. This function should work like "throw". You must return from callback immediately after call of this function.
write_type_item(name, type) - Write a parameter definition. All parameters are treated as a strings by default. If you want to have an additional check for values before use, then you should use this function to define a type of parameter. There are a lot of standard types, e.g., ipv-address, tcp-port, hostname etc. You can also create your own types.

Basically, this module provides everything, alterator-sh-functions have (expect for write_enum and write_blob_param).