alterator_bindings.backend3
This module provides bindings to write alterator backends in Python
.
Pay attention that the module is alterator_bindings.backend3
Description
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 isFalse
) - Indicates if additional debug output (to stderr) is needed (messages from alterator, etc.). Also with this flagwrite_debug
won't be silent (will print messages to stderr)backend3.TEXTDOMAIN
(Defaults toalterator-{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 asmessage
argument with typedict
. All parameters are stored in thisdict
byname-value
pair. All params are named by it's Alterator originals (Basically as inalterator-sh-functions
, but withoutin_
prefix. So$in__objects
here is"_objects"
,$in_action
is"action"
, etc.)translate(text: str, domain=None)
- Output translated string. Optional paramdomain
allows you to replace a default dictionary (TEXTDOMAIN
) with your one. This is a wrapper overgettext
utility. You may import this function as_
to matchalterator-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 usetest_bool
function to test variable forTrue
value.
Functions for writing output parameters:
write_string_param(name, value)
- Write parameter of string type with namename
and valuevalue
.write_bool_param(name, value)
- Write parameter of boolean type with namename
and valuevalue
.value
may be eitherPython's
bool
type (recommended error-proof way) orstr
: 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 parameterlabel
is a descriptive member name visible for users (default toname
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
isdict
with pairscolumn-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
).