From 08ada45c14fb68cffb1800ef59d3cdc3b3b7477f Mon Sep 17 00:00:00 2001 From: barate Date: Wed, 29 Sep 2010 12:08:06 +0000 Subject: [PATCH] Small fixes and doc updates in Python package --- configure.ac | 6 +++++- doc/docutils/docapi.rst | 2 +- doc/docutils/overview.rst | 29 +++++++++++------------------ src/KERNEL_PY/kernel/deprecation.py | 5 ++--- src/KERNEL_PY/kernel/logger.py | 14 ++++++++++++-- src/KERNEL_PY/kernel/studyedit.py | 27 +++++++++++++++++++-------- 6 files changed, 50 insertions(+), 33 deletions(-) diff --git a/configure.ac b/configure.ac index b7d89075e..7e6479505 100644 --- a/configure.ac +++ b/configure.ac @@ -135,7 +135,11 @@ AC_ENABLE_PRODUCTION(no) AC_ENABLE_MPI_SEQ_CONTAINER(no) # _GBO_SALOME_PYTHON_PACKAGING_ -PYLOGLEVEL=DEBUG +if test "X$enable_debug" = "Xyes"; then + PYLOGLEVEL=DEBUG +else + PYLOGLEVEL=WARNING +fi AC_SUBST(PYLOGLEVEL) echo diff --git a/doc/docutils/docapi.rst b/doc/docutils/docapi.rst index 56ee65286..9634eb428 100644 --- a/doc/docutils/docapi.rst +++ b/doc/docutils/docapi.rst @@ -3,7 +3,7 @@ Documentation of the programming interface (API) %%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%% -This section describes the python packages and modules of the +This section describes the python modules of the ``salome.kernel`` python package. The main part is generated from the code documentation included in source python files. diff --git a/doc/docutils/overview.rst b/doc/docutils/overview.rst index 341e9b652..950792907 100644 --- a/doc/docutils/overview.rst +++ b/doc/docutils/overview.rst @@ -6,12 +6,10 @@ 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 + example, the ``studyedit.py`` module facilitates the + manipulation of components and items in SALOME study. +* General purpose functions for logging and other recurrent + stuff in python programming. Note that these functions either encapsulate the python programming interface of KERNEL core (the CORBA or SWIG interfaces for example) or @@ -23,28 +21,23 @@ 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.studyedit import getStudyEditor - from salome.kernel import studyedit - studyEditor = studyedit.getStudyEditor(salomeStudyId) + studyEditor = getStudyEditor() # Get an editor for the current study myStudyComponent = studyEditor.findOrCreateComponent( + moduleName, componentName, - componentLabel, - componentIcon, - engineName) + componentIcon) myStudyItem = studyEditor.createItem( myStudyComponent, itemName, - itemComment, - itemType, - itemIcon) + comment = itemComment, + icon = itemIcon) The specification of the programming interface of this package is -detailled in the part :doc:`Documentation of the programming interface +detailed in the part :doc:`Documentation of the programming interface (API)` of this documentation. .. note:: diff --git a/src/KERNEL_PY/kernel/deprecation.py b/src/KERNEL_PY/kernel/deprecation.py index a99b2713a..4a7ae671d 100644 --- a/src/KERNEL_PY/kernel/deprecation.py +++ b/src/KERNEL_PY/kernel/deprecation.py @@ -20,8 +20,7 @@ # """ This module provides several functions to indicate the deprecation of a -module, a method or a function. This is a temporary module to be used only -during PAL refactoring. +module, a method or a function. """ import sys @@ -31,7 +30,7 @@ import os from salome.kernel import termcolor -msg_seedoc = "See PAL refactoring documentation for possible replacements." +msg_seedoc = "See documentation for possible replacements." def __deprecated_with_msg(func, msg): diff --git a/src/KERNEL_PY/kernel/logger.py b/src/KERNEL_PY/kernel/logger.py index d2e42f56d..e4165c3d6 100644 --- a/src/KERNEL_PY/kernel/logger.py +++ b/src/KERNEL_PY/kernel/logger.py @@ -33,6 +33,7 @@ This module defines a class which provides logging facility in Salome: import sys, os import logging +from salome.kernel.deprecation import deprecated from salome.kernel import termcolor import salome.kernel.logconfig @@ -50,8 +51,8 @@ class Logger(logging.Logger): When creating a new Logger object, the parameter `keyword` defines the name of the logger, `level` defines the logging level (default is - :const:`logging.WARNING` if PAL module is configured with --disable-debug - option or :const:`logging.DEBUG` otherwise), and `color` defines the color + :const:`logging.DEBUG` if KERNEL module is configured with --enable-debug + option or :const:`logging.WARNING` otherwise), and `color` defines the color of the log messages for this logger (log messages will appear in color only when displayed on color-capable ASCII terminals). See module :mod:`salome.kernel.termcolor` for the color constants. @@ -139,6 +140,8 @@ class Logger(logging.Logger): """ self.setLevel(logging.INFO) + @deprecated("Deprecated since version 5.1.5. Please replace with " + "Logger.critical(message)") def fatal(self, message): """ Log a message with CRITICAL level. This method only exists for @@ -170,6 +173,13 @@ class ExtLogger(Logger): compatibility, as the same thing can be done by calling ``Logger.debug(message, exc_info = True)``. """ + + @deprecated("Class ExtLogger is deprecated since version 5.1.5. See " + "documentation for replacement.") + def __init__(self, keyword = "KEY", + level = salome.kernel.logconfig.loggingLevel, + color = None, sourceFileName=None): + Logger.__init__(self, keyword, level, color, sourceFileName) def debug( self, message ): """ diff --git a/src/KERNEL_PY/kernel/studyedit.py b/src/KERNEL_PY/kernel/studyedit.py index 40c848583..4823daf37 100644 --- a/src/KERNEL_PY/kernel/studyedit.py +++ b/src/KERNEL_PY/kernel/studyedit.py @@ -102,6 +102,10 @@ class StudyEditor: Find a component corresponding to the Salome module `moduleName` in the study. If none is found, create a new component and associate it with the corresponding engine (i.e. the engine named `moduleName`). + Note that in Salome 5, the module name and engine name must be + identical (every module must provide an engine with the same name). + In Salome 6 it will be possible to define a different name for the + engine. :type moduleName: string :param moduleName: name of the module corresponding to the component @@ -131,8 +135,9 @@ class StudyEditor: componentName = moduleName self.builder.SetName(sComponent, componentName) if icon is not None: - # _MEM_ : This will be effective if and only if the componentName - # corresponds to the module name (as specified in the SalomeApp.xml) + # _MEM_ : This will be effective if and only if "moduleName" + # really corresponds to the module name (as specified in the + # SalomeApp.xml) self.setIcon(sComponent, icon) # This part will stay inactive until Salome 6. In Salome 6, the @@ -346,12 +351,19 @@ class StudyEditor: self.setTypeId(item, typeId) def removeItem(self, item, withChildren = False ): - # TODO: Update doc (this doc is not clear. Is the item removed or not?) """ - Remove the given item from the study (the item still is in - the study after the removal) - @param item: the browser object to be removed - @param withChildren: remove children if True + Remove the given item from the study. Note that the items are never + really deleted. They just don't appear in the study anymore. + + :type item: SObject + :param item: the item to be removed + + :type withChildren: boolean + :param withChildren: if :const:`True`, also remove the children of + `item` + + :return: :const:`True` if the item was removed successfully, or + :const:`False` if an error happened. """ ok = False try: @@ -362,7 +374,6 @@ class StudyEditor: ok = True except: ok = False - return ok def setItemAtTag(self, fatherItem, tag, name = None, fileType = None, -- 2.39.2