--- /dev/null
+
+%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
+General presentation of the KERNEL python package
+%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
+
+The KERNEL python package essentially contains:
+
+* Helper functions to manipulate KERNEL objects from python. For
+ example, the ``studyedit.py`` module makes you ease with the
+ manipulation of the SALOME study, its ``SComponent`` and
+ ``SObject``.
+* General purpose functions for logging, threading, and other recurent
+ stuff in python programming. These function has no dependancy with
+ SALOME and could be used from any python interpreter
+
+Note that these functions either encapsulate the python programming
+interface of KERNEL core (the CORBA or SWIG interfaces for example) or
+extend existing utilities as the ``salome*.py`` modules.
+
+The functions are distributed in the python package
+``salome.kernel``. For example, the usage of the study editor to
+manipulate some objects can be done with a set of instructions as:
+
+.. code-block:: python
+
+ import salome
+ salome.salome_init()
+ salomeStudyId = salome.myStudyId
+
+ from salome.kernel import studyedit
+ studyEditor = studyedit.getStudyEditor(salomeStudyId)
+
+ myStudyComponent = studyEditor.findOrCreateComponent(
+ componentName,
+ componentLabel,
+ componentIcon,
+ engineName)
+
+ myStudyItem = studyEditor.createItem(
+ myStudyComponent,
+ itemName,
+ itemComment,
+ itemType,
+ itemIcon)
+
+The specification of the programming interface of this package is
+detailled in the part :doc:`Documentation of the programming interface
+(API)</docapi>` of this documentation.
+
+.. note::
+ The main package ``salome`` contains other sub-packages that are
+ distributed with the other SALOME modules. For example, the GEOM
+ module provides the python package ``salome.geom`` and SMESH the
+ package ``salome.smesh``.
Complement A: Organizing the SALOME python functions in a packaged structure
%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
-:Contacts: Guillaume Boulant, Christian Caremoli, Renaud Barate
+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.
-This notes are the instructions 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
==========
* ``salome.kernel``: helper functions for manipulating the SALOME
study and its components (SComponents and SObject). This provides
- also general purpose utilities as a simple logging, a threading
- helper.
+ 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
"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
Problems
========
-To target this situation, we have to face two problems:
+To reach this target, we have to face two problems:
* A naming conflict with the instruction ``import salome``. The result
is unpredictible because of the existance in the ``sys.path`` of
Instructions
============
-Instructions for creating the python package
---------------------------------------------
+Instructions for creating the python packages
+---------------------------------------------
Considering the elements described above, a procedure that works to
get the packaged python structure is:
* Adapt the ``apply_gen`` utility to take into account the finer
folder hierarchy in ``site-packages``.
-Note that all python files that were existing in the KERNEL module
-are leaft untouched but the file ``salome.py``.
+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``.
-By convention, the source code of the python packages of a SALOME
-module <MYMODULE> is located in the source directory
-``src/<MYMODULE>_PY`` (convention already used in the KERNEL).
+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
---------------------------------------------
