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

[reinhard]

Author: reinhard
Date: 2005-08-04 11:39:07 -0500 (Thu, 04 Aug 2005)
New Revision: 7781

Modified:
   trunk/gnue-common/src/datasources/drivers/Base/Behavior.py
   trunk/gnue-common/src/datasources/drivers/Base/Connection.py
   trunk/gnue-common/src/datasources/drivers/Base/ResultSet.py
Log:
Docstrings, comments, type checks.


Modified: trunk/gnue-common/src/datasources/drivers/Base/Behavior.py
===================================================================
--- trunk/gnue-common/src/datasources/drivers/Base/Behavior.py  2005-08-04 
15:29:30 UTC (rev 7780)
+++ trunk/gnue-common/src/datasources/drivers/Base/Behavior.py  2005-08-04 
16:39:07 UTC (rev 7781)
@@ -21,6 +21,12 @@
 #
 # $Id$
 
+"""
+Generic Behavior class extended by all database driver plugins.
+"""
+
+__all__ = ['MissingTypeTransformationError', 'Behavior']
+
 from gnue.common.apps import errors
 from gnue.common.datasources import GSchema
 
@@ -30,19 +36,31 @@
 # =============================================================================
 
 class MissingTypeTransformationError (errors.SystemError):
+  """
+  Cannot transform this type into a native backend type.
+  """
+
   def __init__ (self, typename):
     msg = u_("No type transformation for '%s' found") % typename
     errors.SystemError.__init__ (self, msg)
 
 
 # =============================================================================
-# This class implements the basic schema introspection and creation support
+# Basic schema creation and introspection class
 # =============================================================================
 
 class Behavior:
   """
-  Generic class for schema support
+  Generic class for schema support.
 
+  The Behavior class offers functions for creating new databases, extending the
+  database schema and introspecting the schema. All important functions of this
+  class are available through the L{Connection.Connection} object, so this
+  class is never used directly.
+
+  This class must be subclassed by all database drivers that want to offer
+  schema support.
+
   @cvar _maxIdLength: maximum length of an identifier or None if no restriction
   @cvar _type2native: dictionary mapping field-types to native datatypes
 
@@ -65,22 +83,39 @@
   # ---------------------------------------------------------------------------
 
   def __init__ (self, connection):
+    """
+    Create a new Behavior instance.
 
+    This is usually done silently when creating a connection instance.
+
+    @param connection: The L{Connection.Connection} instance bound to this
+      Behavior instance.
+    """
+
     self.__connection = connection
     self._lookups     = {}      # Name-conversion mapping for element names
     self._elements    = {}      # Per table mapping of elements
 
 
   # ---------------------------------------------------------------------------
+  # Nice string representation
+  # ---------------------------------------------------------------------------
+
+  def __repr__ (self):
+
+    return "<Behavior for connection %s at %d>" % \
+        (self.__connection.name, id (self))
+
+  # ---------------------------------------------------------------------------
   # Read schema information from connection and return it as GSchema tree
   # ---------------------------------------------------------------------------
 
   def readSchema (self):
     """
-    Retrieve the connection's schema information and return it as GSchema
+    Retrieve the connection's schema information and return it as L{GSchema}
     object tree.
 
-    @return: current schema as GSchema object tree
+    @return: current schema as L{GSchema} object tree.
     """
 
     result = GSchema.GSSchema ()
@@ -103,12 +138,11 @@
     connection's current schema.
 
     @param schema: GSchema object tree to be integrated in the connection's
-        current schema
+      current schema.
     @param simulation: if True, do not create the schema. Instead only the code
-        should be generated.
-
+      should be generated.
     @return: sequence of statements to be executed on the connection in order
-        to create/update the schema
+      to create/update the schema.
     """
 
     self._current = self.readSchema ()
@@ -189,10 +223,10 @@
 
   def _readSchema_ (self, parent):
     """
-    Retrieve the connection's schema information and return it as GSchema
-    object tree. This method must be overriden by a descendant.
+    Retrieve the connection's schema information and return it as L{GSchema}
+    object tree. This method must be overwritten by descendants.
 
-    @raises NotImplementedError: unless it get's replaced by a descendant
+    @param parent: parent object to use for the newly created GSchema object.
     """
 
     raise NotImplementedError
@@ -203,7 +237,20 @@
   # ---------------------------------------------------------------------------
 
   def _writeSchema_ (self, current, new, diff, simulation = False):
+    """
+    Change the schema for the connection. This method must be overwritten by
+    descendants.
 
+    @param current: Current state of the backend schema as found out by
+      L{_readSchema_}.
+    @param new: New, desired state of the backend schema.
+    @param diff: L{GSchema} object tree only containing the elements that have
+      to be added.
+    @param simulation: if set to True, the schema should not be changed in the
+      backend, but only the command string should be generated and returned.
+    @return: command string to change the schema as desired.
+    """
+
     raise NotImplementedError
 
 
@@ -221,9 +268,8 @@
     
     @param field: GSField to get a native datatype for
     @return: string with the native datatype
-
-    @raises MissingTypeTransformationError: if there is no conversion method
-        for the GSField's type
+    @raise MissingTypeTransformationError: if there is no conversion method
+      for the GSField's type
     """
 
     if hasattr (field, 'type'):
@@ -249,7 +295,6 @@
     fieldname.
 
     @param field: GSField instance to create a sequence name for
-
     @return: string with a name for the given sequence
     """
 

Modified: trunk/gnue-common/src/datasources/drivers/Base/Connection.py
===================================================================
--- trunk/gnue-common/src/datasources/drivers/Base/Connection.py        
2005-08-04 15:29:30 UTC (rev 7780)
+++ trunk/gnue-common/src/datasources/drivers/Base/Connection.py        
2005-08-04 16:39:07 UTC (rev 7781)
@@ -21,6 +21,10 @@
 #
 # $Id$
 
+"""
+Generic Connection class extended by all database driver plugins.
+"""
+
 __all__ = ['Connection']
 
 from gnue.common.apps import GDebug

Modified: trunk/gnue-common/src/datasources/drivers/Base/ResultSet.py
===================================================================
--- trunk/gnue-common/src/datasources/drivers/Base/ResultSet.py 2005-08-04 
15:29:30 UTC (rev 7780)
+++ trunk/gnue-common/src/datasources/drivers/Base/ResultSet.py 2005-08-04 
16:39:07 UTC (rev 7781)
@@ -25,6 +25,8 @@
 Generic ResultSet class extended by all database driver plugins.
 """
 
+__all__ = ['ResultSet']
+
 from gnue.common.datasources import Exceptions
 
 from RecordSet import RecordSet
@@ -39,8 +41,15 @@
   Representation of a database resultset (a set of records usually representing
   the result of a database query).
 
-  A ResultSet instance encapsulates an ordered set of database records. It also
-  maintains a cursor that can be moved around.
+  A ResultSet instance encapsulates an ordered set of database records. It
+  maintains a cursor that can be moved around. It also provides functions to
+  insert new records and to post changes to the backend.
+
+  This class must be subclassed by all database drivers, and a driver must at
+  least implement one of the following functions:
+    - _query_object_ (for normal queries)
+    - _query_sql_ (for raw SQL queries)
+  and the L{_count_}, L{_fetch_} and L{_close_} functions.
   """
 
   # ---------------------------------------------------------------------------
@@ -185,9 +194,17 @@
     Populate the resultset with data.
 
     @param type: Type of the query, can be 'object' or 'sql'.
+    @param cache: Size of the cache to use for this query.
     @param kwargs: Depends on the type.
+    @raise L{Exceptions.ObjectTypeNotAvailableError}: if the requested type of
+      query is not available for this connection.
+    @raise Exception: if the query cannot be executed. The exact exception type
+      depends on the backend.
     """
 
+    checktype (type, str)
+    checktype (cache, int)
+
     queryfunc = '_query_' + type + '_'
     if not hasattr (self, queryfunc):
       raise Exceptions.ObjectTypeNotAvailableError, type
@@ -224,9 +241,15 @@
     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.
+    @return: the L{RecordSet.RecordSet} instance, or None if the given position
+      is higher than the number of records in the ResultSet.
+    @except Exception: if the requested record is not yet in cache and fetching
+      it from the backend fails. The exact exception class depends on the
+      backend.
     """
 
+    checktype (record, int)
+
     while (record + 1 > len (self.__cachedRecords)) \
         and self.__cacheNextRecord ():
       pass
@@ -249,8 +272,12 @@
     The record pointer is not moved.
 
     @param fields: Fieldnames of the fields to include in the array.
+    @except Exception: if a record is not yet in cache and fetching it from the
+      backend fails. The exact exception class depends on the backend.
     """
 
+    checktype (fields, list)
+
     # First, load all records into the cache
     while self.__cacheNextRecord ():
       pass
@@ -283,8 +310,13 @@
       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.
+    @except Exception: if a record is not yet in cache and fetching it from the
+      backend fails. The exact exception class depends on the backend.
     """
 
+    checktype (keyfields, list)
+    checktype (fields, list)
+
     # First, load all records into the cache
     while self.__cacheNextRecord ():
       pass
@@ -310,6 +342,9 @@
 
     @return: the new current record as a L{RecordSet.RecordSet} instance, or
       None if the resultset is empty.
+    @except Exception: if the requested record is not yet in cache and fetching
+      it from the backend fails. The exact exception class depends on the
+      backend.
     """
     if self.__currentRecord < 0:
       if not self.__cacheNextRecord ():
@@ -344,6 +379,9 @@
 
     @return: the new current record as a L{RecordSet.RecordSet} instance, or
       None if the cursor already pointed to the last record.
+    @except Exception: if the requested record is not yet in cache and fetching
+      it from the backend fails. The exact exception class depends on the
+      backend.
     """
     if self.__currentRecord + 1 == len (self.__cachedRecords):
       if not self.__cacheNextRecord ():
@@ -359,6 +397,9 @@
 
     @return: the new current record as a L{RecordSet.RecordSet} instance, or
       None if the resultset is empty.
+    @except Exception: if the requested record is not yet in cache and fetching
+      it from the backend fails. The exact exception class depends on the
+      backend.
     """
     while self.__cacheNextRecord ():
       pass
@@ -381,7 +422,11 @@
     @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.
+    @except Exception: if the requested record is not yet in cache and fetching
+      it from the backend fails. The exact exception class depends on the
+      backend.
     """
+    checktype (record, int)
     while (record > len (self.__cachedRecords) - 1) \
         and self.__cacheNextRecord ():
       pass
@@ -404,8 +449,10 @@
     @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.
+    @except Exception: if a record is not already in cache and fetching it from
+      the backend fails. The exact exception class depends on the backend.
     """
-
+    checktype (fieldValues, dict)
     i = 0
     while True:
       if i >= len (self.__cachedRecords):
@@ -446,6 +493,9 @@
   def isLastRecord (self):
     """
     Return True if the cursor is at the last record.
+
+    @except Exception: if the next record is not yet in cache and fetching it
+      from the backend fails. The exact exception class depends on the backend.
     """
     if self.__currentRecord < len (self.__cachedRecords) - 1 or \
        self.__cacheNextRecord ():
@@ -475,8 +525,11 @@
     @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.
+    @raise L{Exceptions.ReadOnlyInsertError}: if the ResultSet is read only.
     """
 
+    checktype (defaultData, dict)
+
     if self.__readonly:
       raise Exceptions.ReadOnlyInsertError
 
@@ -506,8 +559,12 @@
       fields except primary key fields and rowid fields, which are never copied
       anyway.
     @return: the newly inserted record.
+    @raise L{Exceptions.ReadOnlyInsertError}: if the ResultSet is read only.
     """
 
+    checktype (exclude, list)
+    checktype (include, list)
+
     current = self.current
     inserted = self.insertRecord ()
 
@@ -571,6 +628,8 @@
 
     @param fkData: fieldname/value dictionary for foreign key fields. Used
       internally for detail resultsets in a master/detail relationship.
+    @raise Exception: if posting the changes to the backend fails for any
+      reason. The exact exception classes depend on the backend.
     """
 
     # save current record position
@@ -621,6 +680,9 @@
     This method must be called after each call to the L{post} method. If the
     operation should be committed, the L{Connection.commit} method can be
     called between post and requery.
+
+    @raise Exception: if querying the records from the backend fails for any
+      reason. The exact exception classes depend on the backend.
     """
 
     index = 0