Python Module

The module provides the means to load a python module and run its functions. Each function has to receive the SIP message as parameter, and optionally some extra arguments passed from the script.

In order to run Python functions, one has to load the module that contains them, by specifying the script name using the script_name parameter. The module has to contain the following components:

A class that contains all the methods that can be invoked from the script.
A method within the class that is called when a SIP child is created. The method should receive an integer parameter, which represents the rank of the child, and must return 0 or positive in case the function was executed successfully, or negative otherwise. The name of this method is specified by the child_init_method parameter.
A global function that initializes the Python module and returns an object from the class whose functions will be invoked by the script. The name of the global function is indicated by the mod_init_method parameter.

A minimal example of a Python script that satisfies these requirements is:

	def mod_init():
		return SIPMsg()

	class SIPMsg:
        def child_init(self, rank):
	        return 0

A function from the object returned above can be executed from the script using the python_exec() script function. The python method has to receive the following parameters:

The SIP message, that has the structure detailed below
Optionally, a string passed from the script

The SIP message received as parameter by the function has the following fields and methods:

Type - the type of the message, either SIP_REQUEST or SIP_REPLY
Method - the method of the message
Status - the status of the message, available only for replies
RURI - the R-URI of the message, available only for requests
src_address - the (IP, port) tuple representing source address of the message
dst_address - the (IP, port) tuple representing the destination address (OpenSIPS address) of the message
copy() - copies the current SIP message in a new object
rewrite_ruri() - changes the R-URI of the message; available only for requests
set_dst_uri() - sets the destination URI of the message; available only for requests
getHeader() - returns the header of a message
call_function() - calls built-in script function or function exported by other module
get_pseudoVar(name) - returns the value of the the pseudo-variable specified by the name as Unicode string.
set_pseudoVar(name, value) - sets pseudo-variable using Unicode string value.

1.2. Dependencies

1.2.1. OpenSIPS Modules

The following modules must be loaded before this module:

None.

1.2.2. External Libraries or Applications

The following libraries or applications must be installed before running OpenSIPS with this module loaded:

python-dev - provides the Python bindings.

1.3. Exported Parameters

1.3.1. `script_name` (string)

The script that contains the Python module.

Default value is “/usr/local/etc/opensips/handler.py”.

Example 1.1. Set script_name parameter

...
modparam("python", "script_name", "/usr/local/bin/opensips_handler.py")
...

1.3.2. `mod_init_function` (string)

The method used to initialize the Python module and return the object.

Default value is “mod_init”.

Example 1.2. Set mod_init_function parameter

...
modparam("python", "mod_init_function", "module_initializer")
...

1.3.3. `child_init_method` (string)

The method called for each child process.

Default value is “child_init”.

Example 1.3. Set child_init_method parameter

...
modparam("python", "child_init_method", "child_initializer")
...

1.4. Exported Functions

1.4.1. `python_exec(method_name [, extra_args])`

This function is used to execute a method from the Python module loaded.

This function can be used from REQUEST_ROUTE, ONREPLY_ROUTE, FAILURE_ROUTE and BRANCH_ROUTE.

Meaning of the parameters is as follows:

method_name (string) - name of the method called
extra_args (string, optional) - extra arguments that can be passed from the script to the python function.

Chapter 2. Contributors

2.1. By Commit Statistics

Table 2.1. Top contributors by DevScore⁽¹⁾, authored commits⁽²⁾ and lines added/removed⁽³⁾

	Name	DevScore	Commits	Lines ++	Lines --
1.	Maksym Sobolyev (@sobomax)	22	10	1319	23
2.	Razvan Crainea (@razvancrainea)	20	13	500	99
3.	Vlad Patrascu (@rvlad-patrascu)	13	9	204	113
4.	Liviu Chircu (@liviuchircu)	8	6	30	61
5.	Bogdan-Andrei Iancu (@bogdan-iancu)	6	4	36	48
6.	Peter Lemenkov (@lemenkov)	4	2	2	2
7.	importos	3	1	104	4

(1) DevScore = author_commits + author_lines_added / (project_lines_added / project_commits) + author_lines_deleted / (project_lines_deleted / project_commits)

(2) including any documentation-related commits, excluding merge commits. Regarding imported patches/code, we do our best to count the work on behalf of the proper owner, as per the "fix_authors" and "mod_renames" arrays in opensips/doc/build-contrib.sh. If you identify any patches/commits which do not get properly attributed to you, please submit a pull request which extends "fix_authors" and/or "mod_renames".

(3) ignoring whitespace edits, renamed files and auto-generated files

2.2. By Commit Activity

Table 2.2. Most recently active contributors⁽¹⁾ to this module

	Name	Commit Activity
1.	Maksym Sobolyev (@sobomax)	Dec 2009 - Feb 2023
2.	Razvan Crainea (@razvancrainea)	Mar 2015 - Jan 2021
3.	importos	Nov 2020 - Nov 2020
4.	Liviu Chircu (@liviuchircu)	Jul 2014 - Jan 2020
5.	Vlad Patrascu (@rvlad-patrascu)	May 2017 - Nov 2019
6.	Peter Lemenkov (@lemenkov)	Jun 2018 - Oct 2019
7.	Bogdan-Andrei Iancu (@bogdan-iancu)	Oct 2014 - Apr 2019

(1) including any documentation-related commits, excluding merge commits

Chapter 3. Documentation

3.1. Contributors

Last edited by: importos, Vlad Patrascu (@rvlad-patrascu), Peter Lemenkov (@lemenkov), Liviu Chircu (@liviuchircu), Razvan Crainea (@razvancrainea).