# &adminguide;

## Overview

This module is an alternative 'app_python3' module with static export of 'KSR' object and functions, without instantiating the SIP message object.

This module cannot be loaded together with 'app_python3' as some global symbols conflict.

This module allows executing Python3 scripts from the config file, exporting functions to access the SIP message from Python3.

Note: if symbols exported to KEMI (module or function names) conflict with Python's reserved keywords, use the 'getattr()' function or the '__dict__' attribute for 'KSR' (e.g., 'KSR.__dict__["async"].task_route("myroute")').

## Dependencies

### &kamailio; Modules

The following modules must be loaded before this module:

- none.

### External Libraries or Applications

The following libraries or applications must be installed before running &kamailio; with this module loaded:

- python3 - Python 3 runtime.

To compile this module the Python 3 development package is needed. Requirements:

- python3-dev - Python 3 development package.

- python3-config - (part of python3-dev) tool to output C includes and library paths.

## Parameters

### `load` (string)

The path to the file with Python code to be executed from configuration file.

Default value is /usr/local/etc/kamailio/kamailio.py.

#### Set `load` parameter

    ...
    modparam("app_python3s", "load", "/usr/local/etc/kamailio/myscript.py")
    ...

### `script_init` (string)

The name of the Python function to be executed when the script is loaded or reloaded.

Default value is (not set).

#### Set `script_init` parameter

    ...
    modparam("app_python3s", "script_init", "ksr_script_init")
    ...
    def ksr_script_init():
        KSR.info("init python script\n")
        return 1
    ...

### `script_child_init` (string)

The name of the Python function to be executed when &kamailio; forks child processes at startup and when the script is reloaded.

Default value is (not set).

#### Set `script_child_init` parameter

    ...
    modparam("app_python3s", "script_child_init", "ksr_script_child_init")
    ...
    def ksr_script_child_init():
        KSR.info("child init python script\n")
        return 1
    ...

## Functions

### `app_python3s_exec(method [, param])`

Execute the Python function with the name given by the parameter 'method'. Optionally can be provided a second string with the parameter to be passed to the Python function.

Both parameters can contain pseudo-variables.

#### `app_python3s_exec` usage

    ...
    app_python3s_exec("my_python_function");
    app_python3s_exec("my_python_function", "my_params");
    app_python3s_exec("my_python_function", "$rU");
    ...

## RPC Commands

### `app_python.reload`

IMPORTANT: this is not thread-safe. In your Python script do not use C extensions with threads that call into `apy_exec()`.

Marks the need to reload the Python script. The actual reload is done in each worker when it next invokes a Python method. The module uses a worker process lock to prevent recursive reloads.

This function only reloads (re-executes) the user script and creates a new script object. It does not reinitialize the interpreter (references in the old module remain if not redefined by the new version).

Name: app_python.reload

Parameters: none

Example:

    ...
    &kamcmd; app_python3s.reload
    ...

Note that reload is done for the Python script provided as parameter to this &kamailio; module. To reload the Python libraries imported in this script, leverage "script_init" and use something like:

    ...
    import mod1
    ...
    import modN
    from importlib import reload

    def ksr_script_init():
        reload(mod1)
        ...
        reload(modN)
        return kamailio()
    ...

Where "modX" are the modules imported at the top.

### `app_python.api_list`

List the functions available via Kemi framework.

Name: app_python.api_list

Parameters: none

Example:

    ...
    &kamcmd; app_python3s.api_list
    ...

## KEMI Usage

The module exports KEMI engine with id "python".

Example:

    ...
    loadmodule "app_python3s.so"
    ...
    cfgengine "python"
    ...

For more details about KEMI, see: https://www.kamailio.org/docs/tutorials/devel/kamailio-kemi-framework/