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

[reinhard]

Author: reinhard
Date: 2005-03-11 07:30:15 -0600 (Fri, 11 Mar 2005)
New Revision: 7166

Modified:
   trunk/gnue-common/src/datasources/drivers/Base/RecordSet.py
Log:
Updated comments and docstrings.


Modified: trunk/gnue-common/src/datasources/drivers/Base/RecordSet.py
===================================================================
--- trunk/gnue-common/src/datasources/drivers/Base/RecordSet.py 2005-03-11 
12:46:01 UTC (rev 7165)
+++ trunk/gnue-common/src/datasources/drivers/Base/RecordSet.py 2005-03-11 
13:30:15 UTC (rev 7166)
@@ -78,10 +78,10 @@
 
   def getField (self, field):
     """
-    This function reads the current value of a field.
+    Return the current value of a field.
 
-    @param field: field name, case insensitive
-    @returns: the field value.
+    @param field: Field name, case insensitive.
+    @return: Field value.
     """
     fn = field.lower ()
     if self._fields.has_key (fn):
@@ -98,7 +98,7 @@
 
   def getFieldsAsDict (self):
     """
-    Returns the record set as a dictionary.
+    Return all fieldnames and values as a dictionary.
 
     @return: A python dictionary of field name/value pairs.
     """
@@ -108,13 +108,13 @@
 
   def setField (self, field, value, trackMod = True):
     """
-    This function sets a new value for a field.
+    Set 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
+    @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
+    @return: The value parameter
     """
     gDebug (8, "Set field %s to %s" % (field, repr (value)))
     do = self._parent._dataObject
@@ -143,7 +143,7 @@
 
   def setFields (self, updateDict, trackMod = True):
     """
-    This function sets new values for several fields at once.
+    Set 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
@@ -157,10 +157,10 @@
 
   def isFieldModified (self, field):
     """
-    This function determines if a field of this record has local modifications.
+    Determine whether a field of this record has local modifications.
 
-    @param field: field name, case insensitive
-    @returns: True if the field has local modifications, False otherwise
+    @param field: Field name, case insensitive
+    @return: True if the field has local modifications, False otherwise
     """
     fn = field.lower ()
     return self._modifiedFlags.has_key (fn)
@@ -169,9 +169,9 @@
 
   def modifiedFields (self):
     """
-    This method delivers a list of all fields that have local modifications.
+    Return a list of all fields that have local modifications.
 
-    @returns: the list of field names
+    @return: The list of field names
     """
     return self._modifiedFlags.keys ()
 
@@ -180,6 +180,11 @@
   # ---------------------------------------------------------------------------
 
   def delete (self):
+    """
+    Mark the record as deleted.
+
+    The actual deletion occurs on the next call to the L{post} method.
+    """
     if self._parent.isReadOnly():
       # Provide better feedback??
       tmsg = _("Attempted to delete from a read only datasource")
@@ -194,9 +199,11 @@
 
   def isEmpty (self):
     """
-    Returns True if the record is empty, which means that it has been newly
-    inserted, but neither has any field been changed nor has a detail for this
-    record been inserted with a status other than empty.
+    Return True if the record is empty.
+    
+    "Empty" means that it has been newly inserted, but neither has any field
+    been changed nor has a detail for this record been inserted with a status
+    other than empty.
     """
     if self._emptyFlag:
       result = True
@@ -212,9 +219,10 @@
 
   def isInserted (self):
     """
-    Returns True if the record has been newly inserted and has either changes
-    or a detail has been inserted. Records with this status will be inserted
-    into the database on post.
+    Return True if the record has been newly inserted and has either changes
+    or a detail has been inserted.
+    
+    Records with this status will be inserted into the database on post.
     """
     return self._insertFlag and not self._deleteFlag and not self.isEmpty ()
 
@@ -222,7 +230,8 @@
 
   def isModified (self):
     """
-    Returns True if the record is an existing record with local changes.
+    Return True if the record is an existing record with local changes.
+
     Records with this status will be updated in the database on post.
     """
     return self._updateFlag and not self._insertFlag and not self._deleteFlag
@@ -231,7 +240,8 @@
 
   def isDeleted (self):
     """
-    Returns True if the record is an existing record that has been deleted.
+    Return True if the record is an existing record that has been deleted.
+
     Records with this status will be deleted in the database on post.
     """
     return self._deleteFlag and not self._insertFlag
@@ -240,8 +250,10 @@
 
   def isPending (self):
     """
-    Returns True if the record has any local changes that make it necessary to
-    post it to the database. Equal to isInserted or isModified or isDeleted.
+    Return True if the record has any local changes that make it necessary to
+    post it to the database.
+    
+    The result is True if either isInserted, isModified, or isDeleted is True.
     """
     return self.isInserted () or self.isModified () or self.isDeleted ()
 
@@ -252,10 +264,10 @@
 
   def post (self, recordNumber = None):
     """
-    This method writes all local changes for this record to the backend, as
+    Write all local changes for this record to the backend, as
     well as for all detail records where this record is the master.
 
-    @param recordNumber: the record number to be used in error messages
+    @param recordNumber: Record number to be used in error messages.
     """
     # Should a post() to a read only datasource cause a ReadOnlyError?
     # It does no harm to attempt to post since nothing will be posted,
@@ -306,8 +318,7 @@
 
   def addDetailResultSet(self, resultSet):
     """
-    This method adds a result set to the list of detail result sets for this
-    record.
+    Add a result set to the list of detail result sets for this record.
 
     @param resultSet: the ResultSet object to add
     """
@@ -325,12 +336,12 @@
 
   def __getitem__ (self, attr):
     return self.getField (attr)
-  
+
   # ---------------------------------------------------------------------------
 
   def keys (self):
     return self._fields.keys ()
-  
+
   # ---------------------------------------------------------------------------
 
   def values (self):
@@ -340,7 +351,7 @@
 
   def items (self):
     return self._fields.items ()
-    
+
   # ---------------------------------------------------------------------------
   # Nice string representation
   # ---------------------------------------------------------------------------