[gnue] r7661 - in trunk/gnue-common/src/datasources: . drivers/Base

[reinhard]

Author: reinhard
Date: 2005-06-27 05:19:39 -0500 (Mon, 27 Jun 2005)
New Revision: 7661

Modified:
   trunk/gnue-common/src/datasources/GDataSource.py
   trunk/gnue-common/src/datasources/drivers/Base/RecordSet.py
   trunk/gnue-common/src/datasources/drivers/Base/ResultSet.py
Log:
Docstrings, cleanup.


Modified: trunk/gnue-common/src/datasources/GDataSource.py
===================================================================
--- trunk/gnue-common/src/datasources/GDataSource.py    2005-06-27 08:10:22 UTC 
(rev 7660)
+++ trunk/gnue-common/src/datasources/GDataSource.py    2005-06-27 10:19:39 UTC 
(rev 7661)
@@ -497,7 +497,7 @@
     """
 
     newResultSet = self.__createResultSet (masterRecord = masterRecord)
-    resultSet.merge (newResultSet)
+    resultSet._merge (newResultSet)
     newResultSet.close ()
 
     # If this is the current result set, then the UI has to follow the changes.

Modified: trunk/gnue-common/src/datasources/drivers/Base/RecordSet.py
===================================================================
--- trunk/gnue-common/src/datasources/drivers/Base/RecordSet.py 2005-06-27 
08:10:22 UTC (rev 7660)
+++ trunk/gnue-common/src/datasources/drivers/Base/RecordSet.py 2005-06-27 
10:19:39 UTC (rev 7661)
@@ -198,7 +198,7 @@
 
   def __repr__ (self):
     """
-    Shows a string representation of the RecordSet.
+    Show a string representation of the RecordSet.
     """
 
     if self.__tablename:

Modified: trunk/gnue-common/src/datasources/drivers/Base/ResultSet.py
===================================================================
--- trunk/gnue-common/src/datasources/drivers/Base/ResultSet.py 2005-06-27 
08:10:22 UTC (rev 7660)
+++ trunk/gnue-common/src/datasources/drivers/Base/ResultSet.py 2005-06-27 
10:19:39 UTC (rev 7661)
@@ -39,7 +39,8 @@
   Representation of a database resultset (a set of records usually representing
   the result of a database query).
 
-  A ResultSet instance encapsulated an ordered set of database records.
+  A ResultSet instance encapsulates an ordered set of database records. It also
+  maintains a cursor that can be moved around.
   """
 
   # ---------------------------------------------------------------------------
@@ -120,10 +121,50 @@
     # Records that have to be requeried after the post
     self.__recordsToRequery = []
 
+    # Pointer to the current record
     self.current = None
 
 
   # ---------------------------------------------------------------------------
+  # Sequence behaviour
+  # ---------------------------------------------------------------------------
+
+  def __iter__ (self):
+    """
+    Return an iterator yielding the records in the resultset as
+    @L{RecordSet.RecordSet} instances.
+    
+    The cursor is not moved while iterating through the resultset.
+    """
+    position = 0
+    while True:
+      if position >= len (self.__cachedRecords):
+        if not self.__cacheNextRecord ():
+          break
+      yield self.__cachedRecords [position]
+      position += 1
+
+  # ---------------------------------------------------------------------------
+
+  def __nonzero__ (self):
+    return True
+
+  # ---------------------------------------------------------------------------
+
+  def __len__ (self):
+    return self.getRecordCount ()
+
+  # ---------------------------------------------------------------------------
+
+  def __getitem__ (self, index):
+    record = self.getRecord (index)
+    if not record:
+      raise IndexError
+    else:
+      return record
+
+
+  # ---------------------------------------------------------------------------
   # String representation
   # ---------------------------------------------------------------------------
 
@@ -167,11 +208,17 @@
   # ---------------------------------------------------------------------------
 
   def isFirstRecord (self):
+    """
+    Return True if the cursor is at the first record.
+    """
     return (self.__currentRecord == 0)
 
   # ---------------------------------------------------------------------------
 
   def isLastRecord (self):
+    """
+    Return True if the cursor is at the last record.
+    """
     if self.__currentRecord < len (self.__cachedRecords) - 1 or \
        self.__cacheNextRecord ():
       return False
@@ -180,13 +227,18 @@
 
   # ---------------------------------------------------------------------------
 
-  # returns -1=No records in memory, #=Current record #
   def getRecordNumber (self):
+    """
+    Return the zero-based position of the cursor within the recordset.
+    """
     return self.__currentRecord
 
   # ---------------------------------------------------------------------------
 
   def getRecordCount (self):
+    """
+    Return the number of records currently in the recordset.
+    """
     if self.__recordCount > 0:
       return self.__recordCount
     else:
@@ -194,8 +246,10 @@
 
   # ---------------------------------------------------------------------------
 
-  # Returns True if the resultset or a detail resultset has uncommitted changes
   def isPending (self):
+    """
+    Return True if the resultset or a detail resultset has uncommitted changes.
+    """
     for rec in self.__cachedRecords:
       if rec.isPending ():
         return True
@@ -258,6 +312,12 @@
   # ---------------------------------------------------------------------------
 
   def getRecord (self, record):
+    """
+    Return the record at the given position without moving the cursor.
+
+    @param record: the zero-based position of the record to return.
+    @return: the L{RecordSet.RecordSet} instance.
+    """
     while (record + 1 > len (self.__cachedRecords)) \
         and self.__cacheNextRecord ():
       pass
@@ -274,8 +334,12 @@
 
   def getArray (self, fields):
     """
-    This function returns the values of the given fields for all records as a
-    2-dimensional list. The record pointer is *not* moved.
+    Return the values of the given fields for all records in the resultset as
+    a 2-dimensional list.
+    
+    The record pointer is not moved.
+
+    @param fields: Fieldnames of the fields to include in the array.
     """
 
     # First, load all records into the cache
@@ -298,8 +362,18 @@
 
   def getDictArray (self, keyfields, fields):
     """
-    This function returns the values of the given fields for all records as a
-    multidimensional dictionary. The record pointer is *not* moved.
+    Return the values of the given fields for all records as a
+    multidimensional dictionary.
+    
+    The record pointer is not moved.
+
+    @param keyfields: Fieldnames of the fields to use as dictionary keys.
+    @param fields: Fieldnames of the fields to include in the value
+      dictionaries.
+    @return: Dictionary with the values of the first keyfield as key, and the
+      values are dictionaries with the value of the second keyfield as key,
+      and so on, until the last dictionary contains the fieldname/value pairs
+      for the fields given in the second parameter.
     """
 
     # First, load all records into the cache
@@ -357,6 +431,17 @@
   # ---------------------------------------------------------------------------
 
   def setRecord (self, record):
+    """
+    Set the cursor to a specific record.
+
+    If the number of the record to set the cursor to is greater than the number
+    of records in the resultset, the cursor is not moved.
+
+    @param record: zero-based number of the record to set the cursor to.
+    @return: the new current record as a L{RecordSet.RecordSet} instance, or
+      None if the record number to set the cursor to is greater than the number
+      of records in the resultset.
+    """
     while (record > len (self.__cachedRecords) - 1) \
         and self.__cacheNextRecord ():
       pass
@@ -369,6 +454,14 @@
   # ---------------------------------------------------------------------------
 
   def nextRecord (self):
+    """
+    Move the cursor forward by one record.
+
+    If the cursor already points to the last record, it is not moved.
+
+    @return: the new current record as a L{RecordSet.RecordSet} instance, or
+      None if the cursor already pointed to the last record.
+    """
     if self.__currentRecord + 1 == len (self.__cachedRecords):
       if not self.__cacheNextRecord ():
         return None
@@ -378,6 +471,14 @@
   # ---------------------------------------------------------------------------
 
   def prevRecord (self):
+    """
+    Move the cursor backwards by one record.
+
+    If the cursor already points to the first record, it is not moved.
+
+    @return: the new current record as a L{RecordSet.RecordSet} instance, or
+      None if the cursor already pointed to the first record.
+    """
     if self.__currentRecord < 1:
       return None
     else:
@@ -387,6 +488,12 @@
   # ---------------------------------------------------------------------------
 
   def firstRecord (self):
+    """
+    Move the cursor to the first record.
+
+    @return: the new current record as a L{RecordSet.RecordSet} instance, or
+      None if the resultset is empty.
+    """
     if self.__currentRecord < 0:
       if not self.__cacheNextRecord ():
         return None
@@ -396,11 +503,17 @@
   # ---------------------------------------------------------------------------
 
   def lastRecord (self):
-    if self.__currentRecord == -1:
+    """
+    Move the cursor to the last record.
+
+    @return: the new current record as a L{RecordSet.RecordSet} instance, or
+      None if the resultset is empty.
+    """
+    while self.__cacheNextRecord ():
+      pass
+    if len (self.__cachedRecords) = 0:
       return None
     else:
-      while self.__cacheNextRecord ():
-        pass
       self.__move (len (self.__cachedRecords) - 1)
       return self.current
 
@@ -411,18 +524,24 @@
 
   def findRecord (self, fieldValues):
     """
-    This function searches through the already loaded records and sets the
-    current record to the first record to match the given fieldValues
-    dictionary (in the form {fieldname: value}).
+    Find a record by field values.
+
+    This function searches through the already loaded records and moves the
+    cursor to the first record to match the given fieldValues dictionary.
     If no match is found, then the record pointer is set to -1.
+
+    @param fieldValues: fieldname/value dictionary to search for.
+    @return: the first record that matches as a L{RecordSet.RecordSet} instance
+      or None if no match was found.
     """
 
-    # Make sure that all records are cached
-    while self.__cacheNextRecord ():
-      pass
-
-    # Find match
-    for i in range (len (self.__cachedRecords)):
+    i = 0
+    while True:
+      if i >= len (self.__cachedRecords):
+        if not self.__cacheNextRecord ():
+          # No match found
+          self.__move (-1)
+          return None
       record = self.__cachedRecords [i]
       found = True
       for (key, value) in fieldValues.items ():
@@ -432,18 +551,24 @@
       if found:
         self.__move (i)
         return self.current
+      i += 1
 
-    # No match found
-    self.__move (-1)
-    return self.current
 
-
   # ---------------------------------------------------------------------------
   # Insert a new record after the current one
   # ---------------------------------------------------------------------------
 
   def insertRecord (self, defaultData = {}):
+    """
+    Insert a new, empty record after the current cursor position.
 
+    The cursor is moved to the newly inserted record.
+
+    @param defaultData: fieldname/value pairs to initialize the record with.
+      All fields not given in this dictionary are initialized with None.
+    @return: the newly inserted record.
+    """
+
     if self.__readonly:
       raise Exceptions.ReadOnlyInsertError
 
@@ -461,11 +586,22 @@
   # Create a new record with a copy of the existing one
   # ---------------------------------------------------------------------------
 
-  def duplicateRecord (self, exclude = (), include = ()):
+  def duplicateRecord (self, exclude = [], include = []):
+    """
+    Create a new record and initialize it with field values from the record at
+    the current cursor position.
+
+    The cursor is moved to the newly inserted record.
+
+    @param exclude: list of fields not to copy.
+    @param include: list of fields to copy. An empty list means to copy all
+      fields except primary key fields and rowid fields, which are never copied
+      anyway.
+    @return: the newly inserted record.
+    """
+
     current = self.current
     inserted = self.insertRecord ()
-    if not inserted:
-      return None
 
     # If include= is specified, then that is our base list.
     # Otherwise, get the base list as the fields in the table
@@ -517,6 +653,9 @@
     This method leaves the ResultSet in an incomplete state.  After every call
     to post, L{requery} must be called.  If the operation should be committed,
     the L{Connection.commit} method can be called between post and requery.
+
+    @param fkData: fieldname/value dictionary for foreign key fields. Used
+      internally for detail resultsets in a master/detail relationship.
     """
 
     global postingRecordset
@@ -580,7 +719,7 @@
   # Merge another ResultSet into this one
   # ---------------------------------------------------------------------------
 
-  def merge (self, otherResultSet):
+  def _merge (self, otherResultSet):
     """
     Merge another (more current) ResultSet into this one.
 
@@ -726,35 +865,5 @@
     pass
 
 
-  # ---------------------------------------------------------------------------
-  # Sequence behaviour
-  # ---------------------------------------------------------------------------
-
-  def __iter__ (self):
-    record = self.firstRecord ()
-    while record:
-      yield record
-      record = self.nextRecord ()
-
-  # ---------------------------------------------------------------------------
-
-  def __nonzero__ (self):
-    return True
-
-  # ---------------------------------------------------------------------------
-
-  def __len__ (self):
-    return self.getRecordCount ()
-
-  # ---------------------------------------------------------------------------
-
-  def __getitem__ (self, index):
-    record = self.getRecord (index)
-    if not record:
-      raise IndexError
-    else:
-      return record
-
-
 # TODO: wtf?
 postingRecordset = None