[gnue] r7143 - trunk/gnue-common/src/datasources/drivers/Base

[reinhard]

Author: reinhard
Date: 2005-03-09 06:13:39 -0600 (Wed, 09 Mar 2005)
New Revision: 7143

Modified:
   trunk/gnue-common/src/datasources/drivers/Base/RecordSet.py
Log:
Code cleanup, added comments and docstrings.


Modified: trunk/gnue-common/src/datasources/drivers/Base/RecordSet.py
===================================================================
--- trunk/gnue-common/src/datasources/drivers/Base/RecordSet.py 2005-03-09 
10:31:32 UTC (rev 7142)
+++ trunk/gnue-common/src/datasources/drivers/Base/RecordSet.py 2005-03-09 
12:13:39 UTC (rev 7143)
@@ -1,4 +1,4 @@
-# GNU Enterprise Common - Database Drivers - Base Record Set
+# GNU Enterprise Common Library - Base DB Driver - Record Set
 #
 # Copyright 2001-2005 Free Software Foundation
 #
@@ -21,13 +21,13 @@
 #
 # $Id$
 
-__all__ = ['RecordSet']
+import string
 
-import string
 from gnue.common.datasources import Exceptions
 
+
 # =============================================================================
-# This class implements the basic record set
+# Basic RecordSet class
 # =============================================================================
 
 class RecordSet:
@@ -36,55 +36,159 @@
   # Constructor
   # ---------------------------------------------------------------------------
 
-  def __init__ (self, parent, initialData = {}, dbIdentifier = None,
-                defaultData = {}):
-    self._detailObjects = []
-    self._dbIdentifier  = dbIdentifier
-    self._deleteFlag    = False
-    self._updateFlag    = False
-    self._parent        = parent
-    self._fieldOrder    = {}
-    self._modifiedFlags = {}      # If field name is present as a key,
-                                  # then field has been modified
+  def __init__ (self, parent, initialData = {}, defaultData = {}):
 
+    # Status information - FIXME: should be private, others should use
+    # isEmpty(), isInserted(), isModified() and isDeleted()
+    self._emptyFlag  = False
+    self._insertFlag = False
+    self._updateFlag = False
+    self._deleteFlag = False
+
+    # The ResultSet this RecordSet is a part of - FIXME: should be private
+    self._parent = parent
+
+    # The field values, keys are lowercase - FIXME: should be private, others
+    # should use getField() and setField()
+    self._fields = {}
+
+    # If field name is present as a key, then field has been modified; keys are
+    # lowercase - FIXME: should be private, others should use isFieldModified()
+    self._modifiedFlags = {}
+
+    # The detail ResultSets where this record is the master
     self._cachedDetailResultSets = {}
 
+    # Dictionary with field:value pairs of initial data
     self._initialData = initialData
 
     if self._initialData and len (self._initialData):
-      self._insertFlag = False
-      self._emptyFlag  = False
-      self._fields     = {}
       self._fields.update (initialData)
     else:
       self._insertFlag = True
       self._emptyFlag  = True
-      self._fields     = {}
       self._fields.update (defaultData)
 
-    gDebug (8, "Initial Data: %s" % self._fields)
+    gDebug (8, "%s initialized with %s" % (repr (self), repr (self._fields)))
 
 
   # ---------------------------------------------------------------------------
-  # Dictionary emulation
+  # Field access
   # ---------------------------------------------------------------------------
 
-  def __setitem__(self, attr, val):
-    self.setField (attr, val)
+  def getField (self, field):
+    """
+    This function reads the current value of a field.
 
-  def __getitem__ (self, attr):
-    return self.getField (attr)
-  
-  def keys (self):
-    return self._fields.keys ()
-  
-  def values (self):
-    return self._fields.values ()
+    @param field: field name, case insensitive
+    @returns: the field value.
+    """
+    fn = field.lower ()
+    if self._fields.has_key (fn):
+      return self._fields [fn]
+    else:
+      # FIXME: If a field value has yet to be set (either from a query or via a
+      # setField), then _fields will not contain a key for the requested field
+      # even though the field name may still be valid.
+      # This should be changed - the _fields dictionary should be initialized
+      # with all valid field names.
+      return None
 
-  def items (self):
-    return self._fields.items ()
-    
   # ---------------------------------------------------------------------------
+
+  def getFieldsAsDict (self):
+    """
+    Returns the record set as a dictionary.
+
+    @return: A python dictionary of field name/value pairs.
+    """
+    return self._fields.copy ()
+
+  # ---------------------------------------------------------------------------
+
+  def setField (self, field, value, trackMod = True):
+    """
+    This function sets a new value for a field.
+
+    @param field: field name, case insensitive
+    @param value: value to set
+    @param trackMod: if set to False, the field isn't marked as modified and
+        will not be included in the post to the backend
+    @returns: the value parameter
+    """
+    gDebug (8, "Set field %s to %s" % (field, repr (value)))
+    do = self._parent._dataObject
+    # If this field is bound to a datasource and the datasource is read only,
+    # generate an error.
+    if self._parent.isFieldBound(field) and self._parent.isReadOnly():
+      # Provide better feedback??
+      tmsg = u_("Attempted to modify read only field '%s'") % field
+      raise Exceptions.ReadOnlyError, tmsg
+    else:
+      fn = field.lower ()
+      self._fields [fn] = value
+      if trackMod:
+        if self._parent.isFieldBound(field):
+          self._emptyFlag = False
+          self._updateFlag = True
+          self._modifiedFlags [fn] = True
+
+          try:
+            do._dataSource._onModification(self)
+          except AttributeError:
+            pass
+    return value
+
+  # ---------------------------------------------------------------------------
+
+  def setFields (self, updateDict, trackMod = True):
+    """
+    This function sets new values for several fields at once.
+
+    @param updateDict: dictionary with the keys being the field names and the
+        values being the new values for the fields
+    @param trackMod: if set to False, the field isn't marked as modified and
+        will not be included in the post to the backend
+    """
+    for (field, value) in updateDict.items ():
+      self.setField (field, value, trackMod)
+
+  # ---------------------------------------------------------------------------
+
+  def isFieldModified (self, field):
+    """
+    This function determines if a field of this record has local modifications.
+
+    @param field: field name, case insensitive
+    @returns: True if the field has local modifications, False otherwise
+    """
+    fn = field.lower ()
+    return self._modifiedFlags.has_key (fn)
+
+  # ---------------------------------------------------------------------------
+
+  def modifiedFields (self):
+    """
+    This method delivers a list of all fields that have local modifications.
+
+    @returns: the list of field names
+    """
+    return self._modifiedFlags.keys ()
+
+  # ---------------------------------------------------------------------------
+  # Mark record as deleted
+  # ---------------------------------------------------------------------------
+
+  def delete (self):
+    if self._parent.isReadOnly():
+      # Provide better feedback??
+      tmsg = _("Attempted to delete from a read only datasource")
+      raise Exceptions.ReadOnlyError, tmsg
+    else:
+      self._deleteFlag = True
+
+
+  # ---------------------------------------------------------------------------
   # Status of this record
   # ---------------------------------------------------------------------------
 
@@ -104,6 +208,8 @@
       result = False
     return result
 
+  # ---------------------------------------------------------------------------
+
   def isInserted (self):
     """
     Returns True if the record has been newly inserted and has either changes
@@ -112,6 +218,8 @@
     """
     return self._insertFlag and not self._deleteFlag and not self.isEmpty ()
 
+  # ---------------------------------------------------------------------------
+
   def isModified (self):
     """
     Returns True if the record is an existing record with local changes.
@@ -119,6 +227,8 @@
     """
     return self._updateFlag and not self._insertFlag and not self._deleteFlag
 
+  # ---------------------------------------------------------------------------
+
   def isDeleted (self):
     """
     Returns True if the record is an existing record that has been deleted.
@@ -126,6 +236,8 @@
     """
     return self._deleteFlag and not self._insertFlag
 
+  # ---------------------------------------------------------------------------
+
   def isPending (self):
     """
     Returns True if the record has any local changes that make it necessary to
@@ -135,105 +247,16 @@
 
 
   # ---------------------------------------------------------------------------
-  # Field access
+  # Post changes to database
   # ---------------------------------------------------------------------------
 
-  # Returns current value of "field"
-  def getField(self, field):
-    try:
-      return self._fields[field]
-    except KeyError:
-      try:
-
-        # TODO: When we're confident that
-        # TODO: all field names are lowercase,
-        # TODO: then this can be removed.
-
-        return self._fields[string.lower(field)]
-      except KeyError:
-        # If a field value has yet to be set
-        # (either from a query or via a setField),
-        # then _fields will not contain a key
-        # for the requested field even though
-        # the field name may still be valid.
-        return None
-
-
-  # Sets current value of "field"
-  # If trackMod is set to 0 then the modification flag isn't raised
-  def setField(self, field, value, trackMod = 1):
-    do = self._parent._dataObject
-    gDebug (8, "setField: %s to %s" % (field, value))
-    # If this field is bound to a datasource and the datasource is read only,
-    # generate an error.
-    if self._parent.isFieldBound(field) and self._parent.isReadOnly():
-      # Provide better feedback??
-      tmsg = u_("Attempted to modify read only field '%s'") % field
-      raise Exceptions.ReadOnlyError, tmsg
-    else:
-      fn = string.lower (field)
-      self._fields [fn] = value
-      if trackMod:
-        if self._parent.isFieldBound(field):
-          self._emptyFlag = False
-          self._updateFlag = True
-          self._modifiedFlags [fn] = True
-          # self._modifiedFlags[field] = True
-
-          try:
-            do._dataSource._onModification(self)
-          except AttributeError:
-            pass
-    return value
-
-  # Batch mode of above setField method
-  # If trackMod is set to 0 then the modification flag isn't raised
-  def setFields(self, updateDict, trackMod = 1):
-    # If this field is bound to a datasource and the datasource is read only,
-    # generate an error.
-    gDebug (8, "calling setField from updateDict: %s" % updateDict)
-    for field in updateDict.keys():
-      self.setField(field, updateDict[field], trackMod)
-
-
-  def getFieldsAsDict(self):
+  def post (self, recordNumber = None):
     """
-    Returns the record set as a dictionary.
+    This method writes all local changes for this record to the backend, as
+    well as for all detail records where this record is the master.
 
-    @return: A python dictionary of field name/value pairs.
+    @param recordNumber: the record number to be used in error messages
     """
-
-    results = {}
-    for field in self._fields.keys():
-      results[field] = self.getField(field)
-    return results
-
-    
-    
-  # Returns 1=Field has been modified
-  def isFieldModified(self, fieldName):
-    #TODO: the string.lower() line should never be called but is left here
-    #TODO: until the code is clean
-    return self._modifiedFlags.has_key(fieldName) or \
-           self._modifiedFlags.has_key (string.lower(fieldName))
-
-  # ---------------------------------------------------------------------------
-  # Mark record as deleted
-  # ---------------------------------------------------------------------------
-
-  def delete(self):
-    if self._parent.isReadOnly():
-      # Provide better feedback??
-      tmsg = _("Attempted to delete from a read only datasource")
-      raise Exceptions.ReadOnlyError, tmsg
-    else:
-      self._deleteFlag = True
-
-  # ---------------------------------------------------------------------------
-  # Post changes to database
-  # ---------------------------------------------------------------------------
-
-  def post (self, recordNumber = None):
     # Should a post() to a read only datasource cause a ReadOnlyError?
     # It does no harm to attempt to post since nothing will be posted,
     # But does this allow sloppy programming?
@@ -262,21 +285,19 @@
       self.post(recordNumber)
       return
 
-
     if self.isPending():
       gDebug (8, 'Posting datasource %s' % self._parent._dataObject.name)
       self._postChanges (recordNumber)
 
-
     # Post all detail records
-    for child in (self._cachedDetailResultSets.keys()):
-      c = self._cachedDetailResultSets[child]._dataObject
+    for child in (self._cachedDetailResultSets.values ()):
+      do = child._dataObject
       # Set the primary key for any new child records
       fk = {}
-      for i in range(len(c._masterfields)):
-        fk[c._detailfields[i]] = self.getField(c._masterfields[i])
+      for i in range(len(do._masterfields)):
+        fk[do._detailfields[i]] = self.getField(do._masterfields[i])
 
-      self._cachedDetailResultSets[child].post(foreign_keys=fk)
+      child.post (foreign_keys = fk)
 
 
   # ---------------------------------------------------------------------------
@@ -284,10 +305,43 @@
   # ---------------------------------------------------------------------------
 
   def addDetailResultSet(self, resultSet):
-    self._cachedDetailResultSets[resultSet._dataObject] = resultSet
+    """
+    This method adds a result set to the list of detail result sets for this
+    record.
 
+    @param resultSet: the ResultSet object to add
+    """
+    self._cachedDetailResultSets [resultSet._dataObject] = resultSet
 
+
   # ---------------------------------------------------------------------------
+  # Dictionary emulation
+  # ---------------------------------------------------------------------------
+
+  def __setitem__(self, attr, val):
+    self.setField (attr, val)
+
+  # ---------------------------------------------------------------------------
+
+  def __getitem__ (self, attr):
+    return self.getField (attr)
+  
+  # ---------------------------------------------------------------------------
+
+  def keys (self):
+    return self._fields.keys ()
+  
+  # ---------------------------------------------------------------------------
+
+  def values (self):
+    return self._fields.values ()
+
+  # ---------------------------------------------------------------------------
+
+  def items (self):
+    return self._fields.items ()
+    
+  # ---------------------------------------------------------------------------
   # Nice string representation
   # ---------------------------------------------------------------------------
 
@@ -332,6 +386,8 @@
     self._insertFlag = False
     self._updateFlag = False
 
+  # ---------------------------------------------------------------------------
+
   def _postDelete (self):
     """
     Post a deletion to the backend. Descendants should override this function
@@ -342,6 +398,8 @@
     """
     pass
 
+  # ---------------------------------------------------------------------------
+
   def _postInsert (self, fields):
     """
     Post an insert to the backend. Descendants should override this function
@@ -355,6 +413,8 @@
     """
     pass
 
+  # ---------------------------------------------------------------------------
+
   def _postUpdate (self, fields):
     """
     Post an update to the backend. Descendants should override this function