Python modules

Python modules are modules which are scripted in the Python scripting language. There are two kinds of Python modules:

• Modules which communicate with the associated Python script using UDP sockets
• Modules which communicate with the associated Python script using http requests

Overview

Python modules allow to execute Python code in any Python 2 or Python 3 environment:

• A Python module creates a Python process using the Python executable path defined in the framework properties. By default the framework will look for a Python 2.x executable among the applications installed on the System
• services reception from the Python module will be deferred to the associated Python script using an UDP or http communication
• services invocation from the Python script will be deferred as a Python module Service invocation using an UDP or http communication

Two generic additional Python scripts are necessary to handle the communication between the Python module and the Python script:

• The pythonModule.py (or pythonHttpModule.py) script is responsible for the Services subscription in the Python environment
• The pythonUtils.py (or pythonHttpUtils.py) script is an utility script usable by the user Python script

Note that these two modules are valid:

• For both a Python 2 or Python 3 environment for UDP communication
• For Python 3 environment only for http communication

Initialization and runtime sequence

The initialization and runtime sequence of Python scripts follows two general phases:

• The initialization phase: this phase takes place during the module initialization
• The runtime phase: this phase takes place after the module start

Note that if the initialization phase does not end correctly^[1]

It can be the case if the Python script takes too much time to start-up, or if there is an exception during the initialization of the script

, then the Python module initialization will be aborted. Else the runtime phase will be started.

Using lengthy methods for the Python scripts

Python framework

The Python script is not executed in the JVM, but the framework will look for a Python executable on the Platform, or the user can specify the path of the Python executable.

Deployment

These modules do not need a deployment in their parent application because they are scripted.

Declaration

These modules are declared by the top-level pythonModule element.

For UDP modules:

      <pythonModule name="FlightManagementSystem">

For http modules:

      <pythonHttpModule name="FlightManagementSystem">

Types limitations

• Python UDP modules have two ways of exchanging data between Java and Python depending on the Python executable version. See Python UDP modules for more information
• Python TCP modules only use Python 3. As there is a JSON library included in the Python implementation, so the exchange of Data is performed using the JSON format. There are no limitations on the types which can be exchanged with Python modules, including types complex types

Python module implementation

The pythonImplementation element declares the Python script file which implements the script, and specified associated properties. The content of this element depends of the type of Python module:

• For Python UDP modules
• For Python http modules

waitAtStart

The waitAtStart attribute specifies the maximum duration to wait for after the start of the Python script. This is necessary to allow the Python executable to start-up. By default the duration will be specified as 200 ms if not defined.

Python runtime

It is possible to override the general Python executable path defined for the framework in the configuration by specifying the optional pythonRuntime element. This element has two possible attributes:

• "path": for a Python path to use for the Python executable. Note that if the path is a symbolic link linking to a real Python executable, the framework will follow this link.
• "env": for an environment variable to use to start the Python executable^[2]
  It is often useful to use this on Unix systems

For example:

      <pythonModule name="FlightManagementSystem" >
         <pythonImplementation path="pythonAppli" inputPort="6000" outputPort="6005" inputSize="1024" outputSize="1024">
              <pythonRuntime path="C:/Program Files (x86)/Python24/python.exe" />
         </pythonImplementation>
      </pythonModule>

or:

      <pythonModule name="FlightManagementSystem" >
         <pythonImplementation path="pythonAppli" inputPort="6000" outputPort="6005" inputSize="1024" outputSize="1024">
              <pythonRuntime env="python24" />
         </pythonImplementation>
      </pythonModule>

Usage with Anaconda

If you use the Anaconda version of Python for a Python module, you should set the environment path to pass to the python process, or else you may have errors when trying to import some packages such as NumPy.

You have two ways to get rid of these errors:

• Add the Anaconda paths to the PATH environment variable
• Specify that the Python runtime is an Anaconda runtime. This is the most simple way to use Python scripts when using Anaconda

Python environment variables

It is possible to specify environment variables which will be passed to the Python process^[3]

By default the environment variables will be those defined for the Java protoFramework process

. All the environment variables have to be defined under the systemEnv element:

• The env children allow to define regular environment variables
• The envPath children allow to define environment variables which define a directory or file path. The parser will make sure that the corresponding paths will be converted to absolute paths, even if the paths are defined relative to the directory of the Python script.
• The append attribute specifies if the path will be added to the current value of the environment variable or if it will replace it

For example:

      <pythonModule name="FlightManagementSystem" >
         <pythonImplementation path="pythonAppli" inputPort="6000" outputPort="6005" inputSize="1024" outputSize="1024">
              <systemEnv>
                 <env key="MYENV" value="toto" />
                 <envPath key="PATH" path="toto.xml" append="false" />
                 <envPath key="PATH" path="titi.xml" append="true" />
              </systemEnv>
         </pythonImplementation>
      </pythonModule>

In that case, the values for the MYENV and PATH environment variables will be:

      MYENV=toto
      PATH=<path of the applications.xml parent directory>/toto.xml;<path of the applications.xml parent directory>/titi.xml

Python class name

By default the module must contain at least one class which must have the same name as the module file itself^[4]

Minus the first character which must be upper case

. For example, if the file name is myPythonAppli.py, then the path parameter must be myPythonAppli, and the class defined in the module must be named MyPythonAppli.

The module is free to contain other classes as well.

For example:

      <pythonModule name="FlightManagementSystem" id="1" >
         <pythonImplementation path="pythonAppli" inputPort="6000" outputPort="6005" inputSize="1024" outputSize="1024"/>
      </pythonModule>

and:

      from pythonUtils import PythonUtils

      class PythonAppli:

However, it is possible to specify the name of the class to call in the module by using the className parameter.

For example:

      <pythonModule name="FlightManagementSystem" id="1" >
         <pythonImplementation path="pythonAppli" className="FMS" inputPort="6000" outputPort="6005" inputSize="1024" outputSize="1024"/>
      </pythonModule>

and:

      from pythonUtils import PythonUtils

      class FMS:

Python module implementation constraint

For the moment, there is one limitation on the way the module should be implemented:

• The module must import the PythonUtils class in the pythonUtils module

Interfacing with the services

See Python modules service interface.

Defining module properties

See module properties configuration.

Debugging Python modules

As for all scripts, the framework help debugging the Python scripts by showing the Python StackTrace in case of an execution error in the script.

Python compatibility

The pythonModule.py and pythonUtils.py scripts must change when the communication between Java and Python is upgraded.

The Python modules version is provided by the Framework as a launch argument when starting the Python process. The pythonModule.py script check if its own version is compatible with the version proviced by Java. This means that you normally should replace the pythonModule.py and pythonUtils.py scripts if the Python modules version changes.

Python library

In order for the Python script to work properly, you must copy two additional Python scripts which will be used as a library in the same directory as the script itself:

• The pythonModule.py (or pythonHttpModule.py) script
• The pythonUtils.py (or pythonHttpUtils.py) script

These two supporting scripts do not depend on the content of the Python script and can be retrieved in the Browser by performing the command Tools => Generate Python Library.

Note that you must use the correct version of the Python scripts depending on the version of Python you intend to use. See generating a Python library more information.