doc/docutils/salomepypkg.rst

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