[gnue] r8425 - trunk/gnue-common/src/logic

[reinhard]

Author: reinhard
Date: 2006-04-19 03:30:57 -0500 (Wed, 19 Apr 2006)
New Revision: 8425

Modified:
   trunk/gnue-common/src/logic/GTrigger.py
   trunk/gnue-common/src/logic/actions.py
Log:
Started cleanup of GTrigger, a few minor fixes in actions.py.


Modified: trunk/gnue-common/src/logic/GTrigger.py
===================================================================
--- trunk/gnue-common/src/logic/GTrigger.py     2006-04-19 06:55:58 UTC (rev 
8424)
+++ trunk/gnue-common/src/logic/GTrigger.py     2006-04-19 08:30:57 UTC (rev 
8425)
@@ -1,4 +1,7 @@
+# GNU Enterprise Common Library - Trigger handling classes
 #
+# Copyright 2000-2006 Free Software Foundation
+#
 # This file is part of GNU Enterprise.
 #
 # GNU Enterprise is free software; you can redistribute it
@@ -16,58 +19,55 @@
 # write to the Free Software Foundation, Inc., 59 Temple Place
 # - Suite 330, Boston, MA 02111-1307, USA.
 #
-# Copyright 2000-2006 Free Software Foundation
-#
-#
-# FILE:
-# GTrigger.py
-#
-# DESCRIPTION:
-# Provides the basic classes needed by the generic trigger system
-#
-# NOTES:
-#
-import sys
-import types
+# $Id$
+
 import string
-import copy
+from xml.sax import saxutils
+
+from gnue.common.apps import errors, GDebug
 from gnue.common.definitions.GObjects import GObj
-from gnue.common.apps import GDebug
-
+from gnue.common.definitions.GParserHelpers import GContent
 from gnue.common.formatting import GTypecast
-from xml.sax import saxutils
-from gnue.common.definitions.GParserHelpers import GContent
 
 from gnue.common.logic import language
 
-# class TriggerError(StandardError):
-#   pass
-#
-# class TriggerAbort:
-#   pass
-# class TriggerStop:
-#   pass
-# class TriggerSuccess:
-#   pass
+__all__ = ['InvalidTriggerTypeError', 'InvalidTriggerFiredError', 'GTrigger',
+        'GTriggerExtension']
 
-#######################################################################
-#
-# Trigger instance classes
-#
-# Classes in here are used to represent the triggers defined in
-# <trigger> tags in an xml file
-#
-#
-# Note: this is a partial graft of the old GFTrigger system
-#       only here so that the new namespace code could be
-#       put to use right away
 
+# =============================================================================
+# Exceptions
+# =============================================================================
 
-#
-# GTrigger
-#
-# Class used to implement triggers
-#
+class InvalidTriggerTypeError(errors.ApplicationError):
+    """
+    Invalid trigger type associated with object.
+
+    A trigger is defined with a type not allowed for the associated object.
+    """
+    def __init__(self, trigger_type):
+        errors.ApplicationError.__init__(self, u_(
+                "Invalid trigger type '%s'") % trigger_type)
+
+# -----------------------------------------------------------------------------
+
+class InvalidTriggerFiredError(errors.SystemError):
+    """
+    Invalid trigger type fired.
+
+    A trigger has been fired with a type not allowed for the object that fired
+    it.
+    """
+    def __init__(self, trigger_type, xml_object):
+        errors.ApplicationError.__init__(self, u_(
+                "Invalid trigger type '%s' fired by %s") \
+                % (trigger_type, repr(xml_object)))
+
+
+# =============================================================================
+# <trigger>
+# =============================================================================
+
 class GTrigger(GObj):
   def __init__(self, parent=None, type=None, name=None, src=None, text=None,
                language='python'):
@@ -272,100 +272,159 @@
     assert gDebug(1, "Trigger not implemented")
 
 
+# =============================================================================
+# Base class for all objects that can have triggers associated
+# =============================================================================
 
+# FIXME: Should actually be a descendant of GTriggerCore, because the calling
+# object itself is visible in the trigger namespace as "self", so it must
+# obviously be trigger namespace visible.
 
-#######################################################################
-#
-# Trigger processor classes
-#
 class GTriggerExtension:
-  """
-  Objects that inherit this class will be
-  capable of processing triggers.
-  """
-  def __init__(self):
-    self._trigger = {}
-    self._validTriggers = {}
-
-  def associateTrigger(self, key, function):
     """
-    Associates a trigger with the object.  More than one trigger of a specific 
type
-    can be associated with an object.  This function is typically automatically
-    called during tree construction from xml source (A GObj tree)
-    """
-    key = string.upper(key)
-    if key in self._validTriggers.keys():
-      if not self._trigger.has_key(key):
-        self._trigger[key] = []
-      self._trigger[key].append(function)
-    else:
-      assert gDebug (1, "Invalid trigger <%s>" % key)
+    Base class for all objects that can fire triggers.
 
-  def processTrigger(self, key, ignoreAbort=True):
+    Descendants of this class maintain a list of trigger names and attached
+    L{GTrigger} objects. Each trigger name can have several L{GTrigger} objects
+    attached, in which case the code of all of them is executed sequentially.
+
+    @cvar _validTriggers: Dictionary with valid trigger names as keys.
     """
-    Fires the requested trigger if a trigger of that type
-    has been associated with this object.
 
-    B{Note:} You cannot fire a trigger before phase 3 of a gnue object
-    tree phased init.
+    # -------------------------------------------------------------------------
+    # Class variables
+    # -------------------------------------------------------------------------
 
-    @param key: The name of the trigger
-    @type key: string
-    @param ignoreAbort: If true then AbortRequests from the trigger are ignored
-    @type ignoreAbort: boolean
+    _validTriggers = {}
+
+
+    # -------------------------------------------------------------------------
+    # Constructor
+    # -------------------------------------------------------------------------
+
+    def __init__(self):
+
+        self.__triggers = {}
+
+
+    # -------------------------------------------------------------------------
+    # Associate a function with a trigger
+    # -------------------------------------------------------------------------
+
+    def associateTrigger(self, key, function):
+        """
+        Associate a trigger with this object.
+        
+        More than one trigger of a specific type can be associated with an
+        object. This function is typically automatically called during tree
+        construction from xml source.
+
+        @param key: Trigger name
+        @type key: str
+        @param function: User provided code to call
+        @type function: callable
+        """
+
+        key = key.upper()
+
+        if not key in self._validTriggers.keys():
+            raise InvalidTriggerTypeError, key
+
+        if not self.__triggers.has_key(key):
+            self.__triggers[key] = []
+        self.__triggers[key].append(function)
+
+
+    # -------------------------------------------------------------------------
+    # Fire a trigger
+    # -------------------------------------------------------------------------
+
+    def processTrigger(self, key, ignoreAbort=True):
+        """
+        Fire the requested trigger if a trigger of that type has been
+        associated with this object.
+
+        B{Note:} You cannot fire a trigger before phase 3 of a gnue object
+        tree phased init.
+
+        @param key: The name of the trigger.
+        @type key: str
+        @param ignoreAbort: If True (the default), then
+            L{language.AbortRequest} exceptions from the trigger are ignored.
+        @type ignoreAbort: bool
+        """
+
+        key = key.upper()
+
+        if not key in self._validTriggers.keys():
+            raise InvalidTriggerFiredError, (key, self)
+
+        assert gDebug (9, 'Trigger %s on %s' % (key, repr(self)))
+        if self.__triggers.has_key(key):
+            for function in self.__triggers[key]:
+                try:
+                    return function(self = self._namespace_object)
+                except language.AbortRequest:
+                    if not ignoreAbort:
+                        raise
+
+
+# =============================================================================
+# XML Element dictionary
+# =============================================================================
+
+def getXMLelements(updates=None):
     """
-    key = string.upper(key)
-    if key in self._validTriggers.keys():
-      assert gDebug (9, 'Trigger %s on %s' % (key, repr (self)))
-      if self._trigger.has_key(key):
-        for function in self._trigger[key]:
-          # TODO: do we need to call "updateNamespace" here?
-          #   function.updateNamespace()
-          try:
-            return function(self = self._namespace_object)
-          except language.AbortRequest:
-            if not ignoreAbort:
-              raise
-    else:
-      assert gDebug (1, "%s: Invalid trigger <%s>" % (self._type, key))
+    Return the XML Element dictionary for the objects defined in this module.
+    """
 
-def getXMLelements(updates={}):
-  """
-  Return any XML elements associated with
-  GTriggers.  Bases is a dictionary of tags
-  whose values are update dictionaries.
-  For example: bases={'datasource': {'BaseClass':myDataSource}}
-  sets xmlElements['datasource']['BaseClass'] = myDataSource
-  """
-  xmlElements = {
-      'trigger': {
-         'BaseClass': GTrigger,
-         'Importable': 1,
-         'Attributes': {
-            'name': {
-               'Unique': 1,
-               'Typecast': GTypecast.name },
-            'type': {
-               'Typecast': GTypecast.uppername },
-            'file': {
-               'Typecast': GTypecast.name },
-            'src': {
-               'Label': u_('Source Trigger'),
-               'References': 'trigger.name',
-               'Typecast': GTypecast.name },
-            'language': {
-               'Typecast': GTypecast.name,
-               'ValueSet': {
-                   'python': {'Label': u_('Python Script')}},
-               'Default': 'python' } },
-         'MixedContent': 1,
-         'KeepWhitespace': 1,
-         'UsableBySiblings': 1,
-         'ParentTags': None },
-      }
+    xml_elements = {
+            'trigger': {
+                'Description'     : u_(
+                    "A piece of code that can be bound to a specific event."),
+                'BaseClass'       : GTrigger,
+                'ParentTags'      : None,
+                'Importable'      : True,
+                'MixedContent'    : True,
+                'KeepWhitespace'  : True,
+                'UsableBySiblings': True,
+                'Attributes': {
+                    'name': {
+                        'Label'      : u_("Name"),
+                        'Description': u_("Name of this element"),
+                        'Typecast'   : GTypecast.name,
+                        'Required'   : True,
+                        'Unique'     : True},
+                    'type': {
+                        'Label'      : u_("Type"),
+                        'Description': u_(
+                            "Type of the trigger. Can be either the name of "
+                            "the event that should fire this trigger, or "
+                            "'NAMED' for named triggers"),
+                        'Typecast'   : GTypecast.uppername},
+                    'language': {
+                        'Label'      : u_("Language"),
+                        'Description': u_(
+                            "Programming language the code is written in"),
+                        'Typecast'   : GTypecast.name,
+                        'ValueSet'   : {
+                            'python': {'Label': "Python"}},
+                        'Default'    : 'python'},
+                    'file': {
+                        'Label'      : u_("Source file"),
+                        'Description': u_(
+                            "External file containing the source code"),
+                        'Typecast'   : GTypecast.text},
+                    'src': {
+                        'Label'      : u_("Source Trigger"),
+                        'Description': u_(
+                            "Name of a named trigger that contains the "
+                            "program code"),
+                        'References' : 'trigger.name',
+                        'Typecast'   : GTypecast.name}}}}
 
-  for alteration in updates.keys():
-    xmlElements[alteration].update(updates[alteration])
+    if updates is not None:
+        for alteration in updates.keys():
+            xml_elements[alteration].update(updates[alteration])
 
-  return xmlElements
-
+    return xml_elements

Modified: trunk/gnue-common/src/logic/actions.py
===================================================================
--- trunk/gnue-common/src/logic/actions.py      2006-04-19 06:55:58 UTC (rev 
8424)
+++ trunk/gnue-common/src/logic/actions.py      2006-04-19 08:30:57 UTC (rev 
8425)
@@ -20,6 +20,7 @@
 # - Suite 330, Boston, MA 02111-1307, USA.
 #
 # $Id: GDataSource.py 8315 2006-03-31 17:14:37Z reinhard $
+
 """
 Classes for the menu and toolbar object trees.
 """
@@ -257,7 +258,7 @@
 
 def get_xml_elements(updates):
     """
-    Returns the XML Element dictionary for the objects defined in this module.
+    Return the XML Element dictionary for the objects defined in this module.
     """
 
     checktype(updates, dict)