alterator-python-functions/README.md

# 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:
```python
#!/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`).