[Top][All Lists]
[Date Prev][Date Next][Thread Prev][Thread Next][Date Index][Thread Index]
[gnue] r7661 - in trunk/gnue-common/src/datasources: . drivers/Base
From: |
reinhard |
Subject: |
[gnue] r7661 - in trunk/gnue-common/src/datasources: . drivers/Base |
Date: |
Mon, 27 Jun 2005 05:19:41 -0500 (CDT) |
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
[Prev in Thread] |
Current Thread |
[Next in Thread] |
- [gnue] r7661 - in trunk/gnue-common/src/datasources: . drivers/Base,
reinhard <=