doc/salome/python_doc_compl.dox

   1 /*!
   2
   3 \page python_doc_compl Organizing the SALOME python functions in a packaged structure
   4
   5 This chapter contains the instruction notes to organise the python files of %SALOME
   6 in a packaged python structure. This is the first step of the development process,
   7 whose goal is to validate the principles and show a possible way.
   8
   9 \b Contacts: Guillaume Boulant, Christian Caremoli, Renaud Barate
  10
  11 \section Compl_objectives Objectives
  12
  13 The main idea is to import %SALOME python functions by doing:
  14
  15 \code
  16 from salome.kernel.<myPythonModule> import <myFunction>
  17 \endcode
  18
  19 instead of:
  20
  21 \code
  22 from <myPythonModule> import <myFunction>
  23 \endcode
  24
  25 as it must be done up to now because of the flat organisation of
  26 python files in the installation folders of %SALOME modules.
  27
  28 To reach this target, the files <b><myPythonModule>.py</b> have to be
  29 organised in a packaged python structure where the main package is
  30 named salome, and then sub-packages could be created for each
  31 %SALOME module:
  32
  33 - <b>salome.kernel</b>: for kernel python functions, embedded in the
  34   KERNEL module
  35 - <b>salome.gui</b>: for gui python functions, embedded in the GUI module
  36 - <b>salome.geom</b>: for geom python functions, embedded in the GEOM
  37   module
  38 - and so on ...
  39
  40 The motivations of this objective are twice:
  41
  42 - Definitively prevent the risk of naming conflict between python
  43   modules coming from different %SALOME modules. Today, the developper
  44   of a module has to take care of the names used in other modules to
  45   choose a name.
  46 - Integrate in %SALOME some python modules initially developed in the
  47   context of domain specific %SALOME applications (%SALOME-MECA,
  48   %SALOME-CFD, OPENTURN, PANTHERE) and whose source files are organized
  49   in a packaged python structure.
  50
  51 The starting point then is a python library named \em nepal that
  52 provides %SALOME helper functions classified by modules
  53 (KERNEL,GEOM,...) and organized in a packaged python structure:
  54
  55 - <b>salome.kernel</b>: helper functions for manipulating the %SALOME
  56   study and its components (SComponents and SObject). This provides
  57   also general purpose utilities for logging and threading.
  58 - <b>salome.gui</b>:  helper functions to manipulate the graphical
  59   representation of studies and the general behavior of the graphical
  60   interface. This provides also generic templates for implementing
  61   dialog box with the MVC pattern.
  62 - <b>salome.geom</b>: essentially contains a function called
  63   "visualization of structural elements". This is used by mechanical
  64   ingeneers to create the 3D geometrical object corresponding to the
  65   numerical model of a given structural element.
  66 - <b>salome.smesh</b>: to manipulated smesh data handled from the SObject
  67   in the %SALOME study.
  68
  69 The target point is to have the <b>salome.kernel</b> part in the KERNEL
  70 module, the <b>salome.geom</b> part in the GEOM module, and so on. And
  71 with <b>no impact on %SALOME scripts</b> that already exists (import salome,
  72 and all other stuff should be imported and work as before).
  73
  74 \section Compl_problems Problems
  75
  76 To reach this target, we have to face two problems:
  77
  78 - %A naming conflict with the instruction <b>import salome</b>. The result
  79   is unpredictable because of the existence in the <b>sys.path</b> of
  80   both a file <b>salome.py</b> and a package \b salome.
  81 - The dispatching of <b>salome.*</b> sub-packages in the different %SALOME
  82   modules.
  83
  84 \subsection subsection_prob1 Naming conflict between salome.py module and salome package
  85
  86 The problem is solved by installing the <b>salome.py</b> file under the
  87 name <b>__init__.py</b> in a folder named <b>${salomepythondir}/salome</b>.
  88
  89 By this operation, the <b>${salomepythondir}/salome</b> directory is
  90 transformed in a python package and the instruction <b>import salome</b>
  91 do the same things as before this modification, without any
  92 modification of the <b>sys.path</b>.
  93
  94 \subsection subsection_prob2 Dispatching of salome.* sub-packages in different %SALOME modules
  95
  96 When we use a %SALOME virtual application, the problem is naturally
  97 solved by the fact that every sub-packages are virtually installed in
  98 the same directory, the directory <b>${salomepythondir}/salome</b>
  99 containing the file <b>__init__.py</b>.
 100
 101 Nevertheless, some people doesn't use the virtual application. To get
 102 a robust configuration in any case, one can use the python namespace
 103 pattern. This consists in creating a virtual python package that
 104 aggregates all the sub-packages.
 105
 106 Technically speaking, this consists in implementing in the file
 107 <b>${salomepythondir}/salome/__init__.py</b> (new version of
 108 <b>salome.py</b>) a function that automatically extend the <b>__path__</b>
 109 variable with sub-packages that can be found in %SALOME modules
 110 installation paths. The code looks something like that:
 111
 112 \code
 113 import os, sys
 114 MATCH_ENDING_PATTERN="site-packages/salome"
 115 def extend_path(pname):
 116   for dir in sys.path:
 117     if not isinstance(dir, basestring) or not os.path.isdir(dir) or not dir.endswith(MATCH_ENDING_PATTERN):
 118       continue
 119     subdir = os.path.join(dir, pname)
 120     # WARN: This may still add duplicate entries to path on
 121     # case-insensitive filesystems
 122     if os.path.isdir(subdir) and subdir not in __path__:
 123       print "INFO - The directory %s is appended to sys.path" % subdir
 124       __path__.append(subdir)
 125
 126 extend_path(ROOT_PYTHONPACKAGE_NAME)
 127 \endcode
 128
 129 \subsection subsection_prob3 Adaptation of the apply_gen utility
 130
 131 Due to the specific above choices, the <b>apply_gen</b> utility must be
 132 modified so that the sub-folder \b salome in <b>${salomepythondir}</b>
 133 is not generated as a symbolic link any longer but as a real folder
 134 containing symbolic links towards the module specific python
 135 sub-packages (\b kernel, \b geom, \b smesh, ...) and to the single
 136 file <b>__init__.py</b> provided by the KERNEL module.
 137
 138 This adaptation can be done in the <b>virtual_salome.py</b> script.
 139
 140 \subsection subsection_prob4 What to do with already existing python files?
 141
 142 Do nothing at this step, it works fine because the files are installed
 143 in a path included in the <b>sys.path</b>.
 144
 145 In a future version, it should be nice to reverse all the python files
 146 of the KERNEL library in this packaged structure. But this can't be
 147 done without impact on existing python user scripts.
 148
 149 \section Compl_instructions Instructions
 150
 151 \subsection subsection_instr1 Instructions for creating the python packages
 152
 153 Considering the elements described above, a procedure that works to
 154 get the packaged python structure is:
 155
 156 - Rename the file <b>salome.py</b> in <b>__init__.py</b> (and adapt the
 157   CMakeLists.txt). This is located in the source directory
 158   <b>src/KERNEL_PY</b>.
 159 - Copy the sources files of the kernel part in the source directory
 160   <b>src/KERNEL_PY</b> starting with a stage named \b kernel including
 161   its own packaged structure (only python files and a file
 162   <b>__init__.py</b> for now)
 163 - Copy the sources files of the geom part in the source directory
 164   <b>src/GEOM_PY</b> (to be created) of the GEOM module. In this case, we
 165   copy the python files directly in the directory (no stage named
 166   \b geom, it's not required for source organisation, and will be
 167   created only for installation by makefile).
 168 - Apply the same procedure for every other %SALOME modules (it concerns
 169   only SMESH up to now).
 170 - Apply the "namespace pattern" by implementing and invoking the
 171   <b>extend_path</b> function in the newly created file <b>__init__.py</b>
 172 - Adapt the <b>apply_gen</b> utility to take into account the finer
 173   folder hierarchy in <b>site-packages</b>.
 174
 175 The naming convention for source folder is here the convention in
 176 place in the KERNEL module: the source code of the python packages of
 177 a %SALOME module <MODULE_NAME> is located in the source directory
 178 <b><srcdir>/src/<MODULE_NAME>_PY</b>.
 179
 180 Note also that all python files that were existing in the KERNEL
 181 module are leaft untouched but the file <b>salome.py</b>.
 182
 183 \subsection subsection_instr2 Instructions for the associated documentation
 184
 185 One special point for the documentation:
 186
 187 - The documentation of the python package API is written in HTML
 188   and generated form the source code with doxygen.
 189 - The *.dox (doxygen file) source files are located in the directory
 190   <b><srcdir>/doc/salome</b>.
 191 - The html generated files are installed in the directory
 192   <b><installdir>/share/doc/salome/gui/KERNEL</b> and are connected to
 193   the in-line documentation of the %SALOME associated module (menu help
 194   of the %SALOME application).
 195
 196 \section Compl_tests Tests and usage
 197
 198 The instructions above provides you with a %SALOME application whose
 199 modules embed there dedicated python packages. This installation can
 200 can be tested using some test use cases. For example, the
 201 visualisation of structural elements (provided by the package
 202 <b>salome.geom</b> can be tested by:
 203
 204 \code
 205 from salome.geom.structelem import TEST_StructuralElement
 206 TEST_StructuralElement()
 207 \endcode
 208
 209 This can be enter in the GUI python console or in a python interpreter
 210 executed in a %SALOME session.
 211
 212 For more details, read the \ref python_doc_api "API documentation" in
 213 <b><installdir>/share/doc/salome/gui/KERNEL</b>.
 214 */