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

[reinhard]

Author: reinhard
Date: 2005-08-04 10:21:40 -0500 (Thu, 04 Aug 2005)
New Revision: 7779

Modified:
   trunk/gnue-common/src/datasources/drivers/Base/Connection.py
Log:
Docstrings, comments, cleanup.


Modified: trunk/gnue-common/src/datasources/drivers/Base/Connection.py
===================================================================
--- trunk/gnue-common/src/datasources/drivers/Base/Connection.py        
2005-08-03 14:39:22 UTC (rev 7778)
+++ trunk/gnue-common/src/datasources/drivers/Base/Connection.py        
2005-08-04 15:21:40 UTC (rev 7779)
@@ -21,7 +21,10 @@
 #
 # $Id$
 
+__all__ = ['Connection']
+
 from gnue.common.apps import GDebug
+from gnue.common.datasources import GConnections, GSchema
 
 
 # =============================================================================
@@ -35,6 +38,17 @@
   This class must be subclassed by all database drivers. It represents a
   connection to the backend.
 
+  The Connection class offers three basic function group:
+    - Connecting to, authenticating at and disconnecting from the backend.
+    - Inserting, modifying and deleting records in the backend using a
+      dictionary with old field values to select the records to operate on as
+      well as committing and rolling back changes.
+    - Creating the actual database in the backend and creating as well as
+      introspecting the database schema. This is done using an assigned
+      L{Behavior.Behavior} class.
+
+  All operations on the backend go through the connection object.
+
   @cvar _resultSetClass_: implementation of the ResultSet class to be used with
     the connection.  Must be overwritten by descendants.
   @cvar _behavior_: Schema introspector class for this type of connection. If a
@@ -81,9 +95,15 @@
     @param parameters: Connection parameters from connections.conf.
     """
 
+    checktype (connections, GConnections.GConnections)
+    checktype (name, basestring)
+    checktype (parameters, dict)
+
     self.manager    = connections
     self.name       = name
     self.parameters = parameters
+
+    # True if the connection has uncommitted changes
     self.__pending  = False
 
     # Find out Behavior class to use
@@ -113,7 +133,7 @@
 
   def __repr__ (self):
 
-    return "<Connection to %s>" % self.name
+    return "<Connection to %s at %d>" % (self.name, id (self))
 
 
   # ---------------------------------------------------------------------------
@@ -164,6 +184,8 @@
       depends on the backend.
     """
 
+    checktype (connectData, dict)
+
     gEnter (8)
     self._connect_ (connectData)
     self._beginTransaction_ ()
@@ -185,6 +207,9 @@
       fails. The exact exception class depends on the backend.
     """
 
+    checktype (table, basestring)
+    checktype (fields, list)
+
     gEnter (8)
     return gLeave (8, self._initialize_ (table, fields))
 
@@ -205,6 +230,9 @@
       the backend.
     """
 
+    checktype (table, basestring)
+    checktype (newfields, dict)
+
     gEnter (8)
     rowid = self._insert_ (table, newfields)
     self.__pending = True
@@ -227,6 +255,10 @@
       the backend.
     """
 
+    checktype (table, basestring)
+    checktype (oldfields, dict)
+    checktype (newfields, dict)
+
     gEnter (8)
     self._update_ (table, oldfields, newfields)
     self.__pending = True
@@ -248,6 +280,9 @@
       on the backend.
     """
 
+    checktype (table, basestring)
+    checktype (oldfields, dict)
+
     gEnter (8)
     self._delete_ (table, oldfields)
     self.__pending = True
@@ -271,6 +306,10 @@
       the backend.
     """
 
+    checktype (table, basestring)
+    checktype (oldfields, dict)
+    checktype (fields, list)
+
     gEnter (8)
     return gLeave (8, self._requery_ (table, oldfields, fields))
 
@@ -293,6 +332,11 @@
       the backend.
     """
 
+    checktype (table, basestring)
+    checktype (oldfields, dict)
+    checktype (methodname, basestring)
+    checktype (parameters, dict)
+
     gEnter (8)
     result = self._call_ (table, oldfields, methodname, parameters)
     # FIXME: Some calls should not make the connection pending, like requesting
@@ -368,31 +412,20 @@
 
     gEnter (8)
     self._close_ ()
-    # Make sure to release the reference to the connection manager as well as
-    # the introspector's instance (if available). This makes garbage collection
-    # behave nice :)
-    self.manager = None
-    if hasattr (self, 'introspector'):
-      self.introspector = None
     gLeave (8)
 
 
   # ---------------------------------------------------------------------------
-  # Return the current schema information of the connection's backend
+  # Create a new database for this connection
   # ---------------------------------------------------------------------------
 
-  def readSchema (self):
+  def createDatabase (self):
     """
-    Return the schema information of the connection's backend or None if no
-    behavior instance is available.
-
-    @return: GSchema object tree with the current schema or None
+    Create the database in the backend.
     """
 
     if self.__behavior is not None:
-      return self.__behavior.readSchema ()
-    else:
-      return None
+      self.__behavior.createDatabase ()
 
 
   # ---------------------------------------------------------------------------
@@ -404,13 +437,15 @@
     Update the connection's backend database schema with the given schema
     object tree.
 
-    @param schema: GSchema object tree defining the schema to be integrated
+    @param schema: L{GSchema} object tree defining the schema to be integrated
     @param simulate: if True, create only the command sequence. No integration
-        takes place.
+      takes place.
 
     @return: command sequence which could be used to integrate the given schema
     """
 
+    checktype (schema, GSchema.GSchema)
+
     commands = []
 
     if self.__behavior is not None:
@@ -420,13 +455,21 @@
 
 
   # ---------------------------------------------------------------------------
-  # Create a new database for this connection
+  # Return the current schema information of the connection's backend
   # ---------------------------------------------------------------------------
 
-  def createDatabase (self):
+  def readSchema (self):
+    """
+    Return the schema information of the connection's backend or None if no
+    behavior instance is available.
 
+    @return: L{GSchema} object tree with the current schema or None
+    """
+
     if self.__behavior is not None:
-      self.__behavior.createDatabase ()
+      return self.__behavior.readSchema ()
+    else:
+      return None
 
 
   # ---------------------------------------------------------------------------