app_python3: update documentation

- update documentation and python_examples/ to reflect the new module name
- fix typo arg->args in python_examples/handler.py

src/modules/app_python3/README

@@ -1,7 +1,9 @@
-app_python Module
+app_python3 Module
 
 Maxim Sobolev
 
+Anthony Alba
+
 Edited by
 
 Maxim Sobolev
@@ -70,12 +72,20 @@ Chapter 1. Admin Guide
 
 1. Overview
 
-   This module allows executing Python scripts from config file, exporting
-   functions to access the SIP message from Python.
+   This module is a port of the 'app_python' module to Python 3. It is
+   based on the work of Maxim Sobolev.
+
+   This module cannot be loaded together with 'app_python' as global
+   symbols have not been renamed. To ease transition, the functions, KEMI
+   exports, and RPC commands have the same names as 'app_python', which
+   also means the two modules cannot coexist.
+
+   This module allows executing Python scripts from the config file,
+   exporting functions to access the SIP message from Python.
 
    For some basic examples of Python scripts that can be used with this
-   module, look at the files inside source tree located at
-   'modules/app_python/python_examples/'.
+   module, look at the files inside the source tree located at
+   'modules/app_python3/python_examples/'.
 
 2. Dependencies
 
@@ -91,7 +101,13 @@ Chapter 1. Admin Guide
 
    The following libraries or applications must be installed before
    running Kamailio with this module loaded:
-     * python-dev - Python devel library.
+     * 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.
 
 3. Parameters
 
@@ -109,7 +125,7 @@ Chapter 1. Admin Guide
 
    Example 1.1. Set load parameter
 ...
-modparam("app_python", "load", "/usr/local/etc/kamailio/myscript.py")
+modparam("app_python3", "load", "/usr/local/etc/kamailio/myscript.py")
 ...
 
 3.2. script_name (string)
@@ -126,7 +142,7 @@ modparam("app_python", "load", "/usr/local/etc/kamailio/myscript.py")
 
    Example 1.2. Set mod_init_function parameter
 ...
-modparam("app_python", "mod_init_function", "my_mod_init")
+modparam("app_python3", "mod_init_function", "my_mod_init")
 ...
 
 3.4. child_init_method (string)
@@ -138,7 +154,7 @@ modparam("app_python", "mod_init_function", "my_mod_init")
 
    Example 1.3. Set child_init_method parameter
 ...
-modparam("app_python", "child_init_method", "my_child_init")
+modparam("app_python3", "child_init_method", "my_child_init")
 ...
 
 4. Functions
@@ -170,8 +186,8 @@ python_exec("my_python_function", "$rU");
    IMPORTANT: not functional yet (can crash a running instance, use it
    only for testing).
 
-   Marks the need to reload the js script. The actual reload is done by
-   every working process when the next call to KEMI config is executed.
+   Marks the need to reload the Python script. The actual reload is done
+   by every working process when the next call to KEMI config is executed.
 
    Name: app_python.reload
 

src/modules/app_python3/README.TestCase-Loggers

@@ -1,10 +1,10 @@
 
 Example of using loggers in Python:
 
-loadmodule "app_python.so"
-modparam("app_python", "script_name", "/path/to/Loggers.py")
-modparam("app_python", "mod_init_function", "mod_init")
-modparam("app_python", "child_init_method", "child_init")
+loadmodule "app_python3.so"
+modparam("app_python3", "script_name", "/path/to/Loggers.py")
+modparam("app_python3", "mod_init_function", "mod_init")
+modparam("app_python3", "child_init_method", "child_init")
 
 ...
 

src/modules/app_python3/doc/Makefile

@@ -1,4 +1,4 @@
-docs = app_python.xml
+docs = app_python3.xml
 
 docbook_dir = ../../../../doc/docbook
 include $(docbook_dir)/Makefile.module

src/modules/app_python3/doc/app_python.xml → src/modules/app_python3/doc/app_python3.xml

@@ -10,13 +10,17 @@
 
 <book xmlns:xi="http://www.w3.org/2001/XInclude">
     <bookinfo>
-	<title>app_python Module</title>
+	<title>app_python3 Module</title>
 	<productname class="trade">&kamailioname;</productname>
 	<authorgroup>
 	    <author>
 		<firstname>Maxim</firstname>
 		<surname>Sobolev</surname>
 	    </author>
+	    <author>
+                <firstname>Anthony</firstname>
+		<surname>Alba</surname>
+	    </author>
 	    <editor>
 		<firstname>Maxim</firstname>
 		<surname>Sobolev</surname>
@@ -29,6 +33,6 @@
     </bookinfo>
     <toc></toc>
 
-	<xi:include href="app_python_admin.xml"/>
+	<xi:include href="app_python3_admin.xml"/>
 
 </book>

src/modules/app_python3/doc/app_python_admin.xml → src/modules/app_python3/doc/app_python3_admin.xml

@@ -17,13 +17,22 @@
     <section>
 	<title>Overview</title>
 	<para>
-		This module allows executing Python scripts from config file,
+		This module is a port of the 'app_python' module to Python 3.
+		It is based on the work of Maxim Sobolev.
+	</para>
+	<para>
+		<emphasis>This module cannot be loaded together with 'app_python'</emphasis> as global symbols
+		have not been renamed. To ease transition, the functions, KEMI exports, and
+		RPC commands have the same names as 'app_python', which also means the two modules cannot coexist.
+	</para>
+	<para>
+		This module allows executing Python scripts from the config file,
 		exporting functions to access the SIP message from Python.
 	</para>
 	<para>
 		For some basic examples of Python scripts that can be used with
-		this module, look at the files inside source tree located at
-		'modules/app_python/python_examples/'.
+		this module, look at the files inside the source tree located at
+		'modules/app_python3/python_examples/'.
 	</para>
     </section>
     <section>
@@ -49,7 +58,24 @@
 	    	<itemizedlist>
 		    <listitem>
 			<para>
-			    <emphasis>python-dev</emphasis> - Python devel library.
+			    <emphasis>python3</emphasis> - Python 3 runtime.
+			</para>
+		    </listitem>
+	    	</itemizedlist>
+	    </para>
+	    <para>
+		To compile this module the Python 3 development package is needed.
+		Requirements:
+	    	<itemizedlist>
+		    <listitem>
+			<para>
+			    <emphasis>python3-dev</emphasis> - Python 3 development package.
+			</para>
+		    </listitem>
+		    <listitem>
+			<para>
+			    <emphasis>python3-config</emphasis> - (part of python3-dev) 
+				tool to output C includes and library paths.
 			</para>
 		    </listitem>
 	    	</itemizedlist>
@@ -58,7 +84,7 @@
     </section>
     <section>
 	<title>Parameters</title>
-	<section id="app_python.p.load">
+	<section id="app_python3.p.load">
 	    <title><varname>load</varname> (string)</title>
 	    <para>
 			The path to the file with Python code to be executed
@@ -73,21 +99,21 @@
 		<title>Set <varname>load</varname> parameter</title>
 		<programlisting format="linespecific">
 ...
-modparam("app_python", "load", "/usr/local/etc/kamailio/myscript.py")
+modparam("app_python3", "load", "/usr/local/etc/kamailio/myscript.py")
 ...
 </programlisting>
 	    </example>
 	</section>
 
-	<section id="app_python.p.script_name">
+	<section id="app_python3.p.script_name">
 	    <title><varname>script_name</varname> (string)</title>
 	    <para>
 			This is same as "load" parameter, kept for backward compatibility
 			with the older versions of the module.
 	    </para>
 	</section>
 
-	<section id="app_python.p.mod_init_function">
+	<section id="app_python3.p.mod_init_function">
 	    <title><varname>mod_init_function</varname> (string)</title>
 	    <para>
 			The Python function to be executed by this module when
@@ -102,13 +128,13 @@ modparam("app_python", "load", "/usr/local/etc/kamailio/myscript.py")
 		<title>Set <varname>mod_init_function</varname> parameter</title>
 		<programlisting format="linespecific">
 ...
-modparam("app_python", "mod_init_function", "my_mod_init")
+modparam("app_python3", "mod_init_function", "my_mod_init")
 ...
 </programlisting>
 	    </example>
 	</section>
 
-	<section id="app_python.p.child_init_method">
+	<section id="app_python3.p.child_init_method">
 	    <title><varname>child_init_method</varname> (string)</title>
 	    <para>
 			The Python function to be executed by this module when
@@ -123,7 +149,7 @@ modparam("app_python", "mod_init_function", "my_mod_init")
 		<title>Set <varname>child_init_method</varname> parameter</title>
 		<programlisting format="linespecific">
 ...
-modparam("app_python", "child_init_method", "my_child_init")
+modparam("app_python3", "child_init_method", "my_child_init")
 ...
 </programlisting>
 	    </example>
@@ -133,7 +159,7 @@ modparam("app_python", "child_init_method", "my_child_init")
 
     <section>
 	<title>Functions</title>
- 	<section id="app_python.f.python_exec">
+ 	<section id="app_python3.f.python_exec">
 	    <title>
 		<function moreinfo="none">python_exec(method [, args])</function>
 	    </title>
@@ -160,7 +186,7 @@ python_exec("my_python_function", "$rU");
     </section>
 	<section>
         <title>RPC Commands</title>
-        <section id="app_python.r.reload">
+        <section id="app_python3.r.reload">
             <title>
             <function moreinfo="none">app_python.reload</function>
             </title>
@@ -169,7 +195,7 @@ python_exec("my_python_function", "$rU");
 				use it only for testing).
 			</para>
             <para>
-            Marks the need to reload the js script.
+            Marks the need to reload the Python script.
             The actual reload is done by every working process when the next
             call to KEMI config is executed.
             </para>
@@ -186,7 +212,7 @@ python_exec("my_python_function", "$rU");
 ...
             </programlisting>
 		</section>
-		<section id="app_python.r.api_list">
+		<section id="app_python3.r.api_list">
             <title>
             <function moreinfo="none">app_python.api_list</function>
             </title>

src/modules/app_python3/python_examples/Loggers.py

@@ -46,61 +46,62 @@
         PROC_TCP_MAIN
         PROC_UNIXSOCK
         PROC_ATTENDANT
-	PROC_INIT
-	PROC_NOCHLDINIT
-	PROC_SIPINIT
-	PROC_SIPRPC
-	PROC_MIN
+        PROC_INIT
+        PROC_NOCHLDINIT
+        PROC_SIPINIT
+        PROC_SIPRPC
+        PROC_MIN
 
 """
 
+
 class Loggers:
 
     def __init__(self):
-	pass
+        pass
 
     def __del__(self):
-	pass
+        pass
 
     def child_init(self, rank):
-	if rank == Ranks.PROC_MAIN:
-	    Logger.LM_ERR("rank is PROC_MAIN")
-	elif rank == Ranks.PROC_TIMER:
-	    Logger.LM_ERR("rank is PROC_TIMER")
-	elif rank == Ranks.PROC_RPC:
-	    Logger.LM_ERR("rank is PROC_RPC")
-	elif rank == Ranks.PROC_FIFO:
-	    Logger.LM_ERR("rank is PROC_FIFO")
-	elif rank == Ranks.PROC_TCP_MAIN:
-	    Logger.LM_ERR("rank is PROC_TCP_MAIN")
-	elif rank == Ranks.PROC_UNIXSOCK:
-	    Logger.LM_ERR("rank is PROC_UNIXSOCK")
-	elif rank == Ranks.PROC_ATTENDANT:
-	    Logger.LM_ERR("rank is PROC_ATTENDANT")
-	elif rank == Ranks.PROC_INIT:
-	    Logger.LM_ERR("rank is PROC_INIT")
-	elif rank == Ranks.PROC_NOCHLDINIT:
-	    Logger.LM_ERR("rank is PROC_NOCHLDINIT")
-	elif rank == Ranks.PROC_SIPINIT:
-	    Logger.LM_ERR("rank is PROC_SIPINIT")
-	elif rank == Ranks.PROC_SIPRPC:
-	    Logger.LM_ERR("rank is PROC_SIPRPC")
-	elif rank == Ranks.PROC_MIN:
-	    Logger.LM_ERR("rank is PROC_MIN")
-
-	return 0
+        if rank == Ranks.PROC_MAIN:
+            Logger.LM_ERR("rank is PROC_MAIN")
+        elif rank == Ranks.PROC_TIMER:
+            Logger.LM_ERR("rank is PROC_TIMER")
+        elif rank == Ranks.PROC_RPC:
+            Logger.LM_ERR("rank is PROC_RPC")
+        elif rank == Ranks.PROC_FIFO:
+            Logger.LM_ERR("rank is PROC_FIFO")
+        elif rank == Ranks.PROC_TCP_MAIN:
+            Logger.LM_ERR("rank is PROC_TCP_MAIN")
+        elif rank == Ranks.PROC_UNIXSOCK:
+            Logger.LM_ERR("rank is PROC_UNIXSOCK")
+        elif rank == Ranks.PROC_ATTENDANT:
+            Logger.LM_ERR("rank is PROC_ATTENDANT")
+        elif rank == Ranks.PROC_INIT:
+            Logger.LM_ERR("rank is PROC_INIT")
+        elif rank == Ranks.PROC_NOCHLDINIT:
+            Logger.LM_ERR("rank is PROC_NOCHLDINIT")
+        elif rank == Ranks.PROC_SIPINIT:
+            Logger.LM_ERR("rank is PROC_SIPINIT")
+        elif rank == Ranks.PROC_SIPRPC:
+            Logger.LM_ERR("rank is PROC_SIPRPC")
+        elif rank == Ranks.PROC_MIN:
+            Logger.LM_ERR("rank is PROC_MIN")
+
+        return 0
 
     def TestLoggers(self, msg, args):
-	Logger.LM_GEN1(Logger.L_INFO,                           	"Loggers.py:     LM_GEN1: msg: %s" % str(args))
-	Logger.LM_GEN2(Logger.L_INFO, Logger.DEFAULT_FACILITY,	        "Loggers.py:     LM_GEN2: msg: %s" % str(args))
-	Logger.LM_ALERT(                                        	"Loggers.py:    LM_ALERT: msg: %s" % str(args))
-	Logger.LM_CRIT(                                         	"Loggers.py:     LM_CRIT: msg: %s" % str(args))
-	Logger.LM_ERR(                                          	"Loggers.py:      LM_ERR: msg: %s" % str(args))
-	Logger.LM_WARN(                                         	"Loggers.py:     LM_WARN: msg: %s" % str(args))
-	Logger.LM_NOTICE(                                       	"Loggers.py:   LM_NOTICE: msg: %s" % str(args))
-	Logger.LM_INFO(                                         	"Loggers.py:     LM_INFO: msg: %s" % str(args))
-	Logger.LM_DBG(                                          	"Loggers.py:      LM_DBG: msg: %s" % str(args))
-	return 1
+        Logger.LM_GEN1(Logger.L_INFO,                                   "Loggers.py:     LM_GEN1: msg: %s" % str(args))
+        Logger.LM_GEN2(Logger.L_INFO, Logger.DEFAULT_FACILITY,                "Loggers.py:     LM_GEN2: msg: %s" % str(args))
+        Logger.LM_ALERT(                                                "Loggers.py:    LM_ALERT: msg: %s" % str(args))
+        Logger.LM_CRIT(                                                 "Loggers.py:     LM_CRIT: msg: %s" % str(args))
+        Logger.LM_ERR(                                                  "Loggers.py:      LM_ERR: msg: %s" % str(args))
+        Logger.LM_WARN(                                                 "Loggers.py:     LM_WARN: msg: %s" % str(args))
+        Logger.LM_NOTICE(                                               "Loggers.py:   LM_NOTICE: msg: %s" % str(args))
+        Logger.LM_INFO(                                                 "Loggers.py:     LM_INFO: msg: %s" % str(args))
+        Logger.LM_DBG(                                                  "Loggers.py:      LM_DBG: msg: %s" % str(args))
+        return 1
 
 def mod_init():
     return Loggers()