2 %%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
3 Complement A: Organizing the SALOME python functions in a packaged structure
4 %%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
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.
11 :Contacts: Guillaume Boulant, Christian Caremoli, Renaud Barate
16 The main idea is to import SALOME python functions by doing:
18 .. code-block:: python
20 from salome.kernel.<myPythonModule> import <myFunction>
24 .. code-block:: python
26 from <myPythonModule> import <myFunction>
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.
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
36 * ``salome.kernel``: for kernel python functions, embedded in the
38 * ``salome.gui``: for gui python functions, embedded in the GUI module
39 * ``salome.geom``: for geom python functions, embedded in the GEOM
43 The motivations of this objective are twice:
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
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.
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:
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
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).
81 To reach this target, we have to face two problems:
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
89 Naming conflict between ``salome.py`` module and ``salome`` package
90 -------------------------------------------------------------------
92 The problem is solved by installing the ``salome.py`` file under the
93 name ``__init__.py`` in a folder named ``${salomepythondir}/salome``.
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``.
100 Dispatching of ``salome.*`` sub-packages in different SALOME modules
101 --------------------------------------------------------------------
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``.
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.
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:
119 .. code-block:: python
123 MATCH_ENDING_PATTERN="site-packages/salome"
125 def extend_path(pname):
127 if not isinstance(dir, basestring) or not os.path.isdir(dir) or not dir.endswith(MATCH_ENDING_PATTERN):
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)
136 extend_path(ROOT_PYTHONPACKAGE_NAME)
139 Adaptation of the ``apply_gen`` utility
140 ----------------------------------------
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.
149 This adaptation can be done in the ``virtual_salome.py`` script.
152 What to do with already existing python files?
153 ----------------------------------------------
155 Do nothing at this step, it works fine because the files are installed
156 in a path included in the ``sys.path``.
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.
165 Instructions for creating the python packages
166 ---------------------------------------------
168 Considering the elements described above, a procedure that works to
169 get the packaged python structure is:
171 * Rename the file ``salome.py`` in ``__init__.py`` (and adapt the
172 Makefile.am). This is located in the source directory
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``.
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``.
195 Note also that all python files that were existing in the KERNEL
196 module are leaft untouched but the file ``salome.py``.
198 Instructions for the associated documentation
199 ---------------------------------------------
201 One special point for the documentation:
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).
212 Any suggestion on this point would be appreciated.
216 * Move all files ``*.txt`` from the ``<srcdir>/doc`` folder to the
217 ``<srcdir>/doc/docutils`` folder and analyse what is still to date
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
229 Finaly, here is a synthesis of modifications in source files.
233 * See the CVS patch files KERNEL.patch, GEOM.patch and SMESH.patch
234 (the only SALOME modules modified today).
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/unix/config_files/check_sphinx.m4``
242 * GEOM : directory ``src/GEOM_PY``
243 * GEOM : directory ``doc/docutils``
244 * SMESH : directory ``src/SMESH_PY``
245 * SMESH : directory ``doc/docutils``
249 * file ``src/KERNEL_PY/salome.py``
255 The instructions above provides you with a SALOME application whose
256 modules embed there dedicated python packages. This installation can
257 can be tested using some test use cases. For example, the
258 visualisation of structural elements (provided by the package
259 ``salome.geom`` can be tested by:
261 .. code-block:: python
263 from salome.geom.structelem import TEST_StructuralElement
264 TEST_StructuralElement()
266 This can be enter in the GUI python console or in a python interpreter
267 executed in a SALOME session.
269 For more details, read the API documentation in
270 ``<installdir>/share/doc/salome/docutils``.