Organizing the SALOME python functions in a packaged structure

This chapter contains the instruction notes to organise the python files of SALOME in a packaged python structure.

This is the first step of the development process, whose goal is to validate the principles and show a possible way.

Contacts: Guillaume Boulant, Christian Caremoli, Renaud Barate

Objectives

The main idea is to import SALOME python functions by doing:

from salome.kernel.<myPythonModule> import <myFunction>

instead of:

from <myPythonModule> import <myFunction>

as it must be done up to now because of the flat organisation of python files in the installation folders of SALOME modules.

To reach this target, the files <myPythonModule>.py have to be organised in a packaged python structure where the main package is named salome, and then sub-packages could be created for each SALOME module:

• salome.kernel: for kernel python functions, embedded in the KERNEL module
• salome.gui: for gui python functions, embedded in the GUI module
• salome.geom: for geom python functions, embedded in the GEOM module
• and so on ...

The motivations of this objective are twice:

• Definitively prevent the risk of naming conflict between python modules coming from different SALOME modules. Today, the developer of a module has to take care of the names used in other modules to choose a name.
• Integrate in SALOME some python modules initially developed in the context of domain specific SALOME applications (SALOME-MECA, SALOME-CFD, OPENTURN, PANTHERE) and whose source files are organized in a packaged python structure.

The starting point then is a python library named nepal that provides SALOME helper functions classified by modules (KERNEL,GEOM,...) and organized in a packaged python structure:

• salome.kernel: helper functions for manipulating the SALOME study and its components (SComponents and SObject). This provides also general purpose utilities for logging and threading.
• salome.gui: helper functions to manipulate the graphical representation of studies and the general behavior of the graphical interface. This provides also generic templates for implementing dialog box with the MVC pattern.
• salome.geom: essentially contains a function called "visualization of structural elements". This is used by mechanical ingeneers to create the 3D geometrical object corresponding to the numerical model of a given structural element.
• salome.smesh: to manipulated smesh data handled from the SObject in the SALOME study.

The target point is to have the salome.kernel part in the KERNEL module, the salome.geom part in the GEOM module, and so on. And with no impact on SALOME scripts that already exists (import salome, and all other stuff should be imported and work as before).

Problems

To reach this target, we have to face two problems:

• A naming conflict with the instruction import salome. The result is unpredictable because of the existence in the sys.path of both a file salome.py and a package salome.
• The dispatching of salome.* sub-packages in the different SALOME modules.

Naming conflict between salome.py module and salome package

The problem is solved by installing the salome.py file under the name init.py in a folder named ${salomepythondir}/salome.

By this operation, the ${salomepythondir}/salome directory is transformed in a python package and the instruction import salome do the same things as before this modification, without any modification of the sys.path.

Dispatching of salome.* sub-packages in different %SALOME modules

When we use a SALOME virtual application, the problem is naturally solved by the fact that every sub-packages are virtually installed in the same directory, the directory ${salomepythondir}/salome containing the file init.py.

Nevertheless, some people doesn't use the virtual application. To get a robust configuration in any case, one can use the python namespace pattern. This consists in creating a virtual python package that aggregates all the sub-packages.

Technically speaking, this consists in implementing in the file ${salomepythondir}/salome/__init__.py (new version of salome.py) a function that automatically extend the path variable with sub-packages that can be found in SALOME modules installation paths. The code looks something like that:

import os, sys 
MATCH_ENDING_PATTERN="site-packages/salome"
def extend_path(pname):
  for dir in sys.path:
    if not isinstance(dir, basestring) or not os.path.isdir(dir) or not dir.endswith(MATCH_ENDING_PATTERN):
      continue
    subdir = os.path.join(dir, pname)
    # WARN: This may still add duplicate entries to path on
    # case-insensitive filesystems
    if os.path.isdir(subdir) and subdir not in __path__:
      print("INFO - The directory %s is appended to sys.path" % subdir)
      __path__.append(subdir)
 
extend_path(ROOT_PYTHONPACKAGE_NAME)

Adaptation of the apply_gen utility

Due to the specific above choices, the apply_gen utility must be modified so that the sub-folder salome in ${salomepythondir} is not generated as a symbolic link any longer but as a real folder containing symbolic links towards the module specific python sub-packages (kernel, geom, smesh, ...) and to the single file init.py provided by the KERNEL module.

This adaptation can be done in the virtual_salome.py script.

What to do with already existing python files?

Do nothing at this step, it works fine because the files are installed in a path included in the sys.path.

In a future version, it should be nice to reverse all the python files of the KERNEL library in this packaged structure. But this can't be done without impact on existing python user scripts.

Instructions

Instructions for creating the python packages

Considering the elements described above, a procedure that works to get the packaged python structure is:

• Rename the file salome.py in init.py (and adapt the CMakeLists.txt). This is located in the source directory src/KERNEL_PY.
• Copy the sources files of the kernel part in the source directory src/KERNEL_PY starting with a stage named kernel including its own packaged structure (only python files and a file init.py for now)
• Copy the sources files of the geom part in the source directory src/GEOM_PY (to be created) of the GEOM module. In this case, we copy the python files directly in the directory (no stage named geom, it's not required for source organisation, and will be created only for installation by makefile).
• Apply the same procedure for every other SALOME modules (it concerns only SMESH up to now).
• Apply the "namespace pattern" by implementing and invoking the extend_path function in the newly created file init.py
• Adapt the apply_gen utility to take into account the finer folder hierarchy in site-packages.

The naming convention for source folder is here the convention in place in the KERNEL module: the source code of the python packages of a SALOME module <MODULE_NAME> is located in the source directory <srcdir>/src/<MODULE_NAME>_PY.

Note also that all python files that were existing in the KERNEL module are leaft untouched but the file salome.py.

Instructions for the associated documentation

One special point for the documentation:

• The documentation of the python package API is written in HTML and generated form the source code with doxygen.
• The *.dox (doxygen file) source files are located in the directory <srcdir>/doc/salome.
• The html generated files are installed in the directory <installdir>/share/doc/salome/gui/KERNEL and are connected to the in-line documentation of the SALOME associated module (menu help of the SALOME application).

Tests and usage

The instructions above provides you with a SALOME application whose modules embed there dedicated python packages. This installation can can be tested using some test use cases. For example, the visualisation of structural elements (provided by the package salome.geom can be tested by:

from salome.geom.structelem import TEST_StructuralElement
TEST_StructuralElement()

This can be enter in the GUI python console or in a python interpreter executed in a SALOME session.

For more details, read the API documentation in <installdir>/share/doc/salome/gui/KERNEL.