[gnue] r7147 - in trunk/gnue-common/src/datasources/drivers: Base DBSIG2

[reinhard]

Author: reinhard
Date: 2005-03-09 17:29:42 -0600 (Wed, 09 Mar 2005)
New Revision: 7147

Modified:
   trunk/gnue-common/src/datasources/drivers/Base/Connection.py
   trunk/gnue-common/src/datasources/drivers/DBSIG2/Connection.py
Log:
Code cleanup, use virtual methods (beginning with _) in DBSIG2 Connection
object, work on comments and docstrings.


Modified: trunk/gnue-common/src/datasources/drivers/Base/Connection.py
===================================================================
--- trunk/gnue-common/src/datasources/drivers/Base/Connection.py        
2005-03-09 22:37:01 UTC (rev 7146)
+++ trunk/gnue-common/src/datasources/drivers/Base/Connection.py        
2005-03-09 23:29:42 UTC (rev 7147)
@@ -115,7 +115,7 @@
 
     gEnter (8)
     self._connect (connectData)
-    self._startTransaction ()
+    self._beginTransaction ()
     gLeave (8)
 
   # ---------------------------------------------------------------------------
@@ -129,7 +129,7 @@
 
     gEnter (8)
     self._commit ()
-    self._startTransaction ()
+    self._beginTransaction ()
     gLeave (8)
 
   # ---------------------------------------------------------------------------
@@ -143,7 +143,7 @@
 
     gEnter (8)
     self._rollback ()
-    self._startTransaction ()
+    self._beginTransaction ()
     gLeave (8)
 
   # ---------------------------------------------------------------------------
@@ -355,6 +355,18 @@
 
   # ---------------------------------------------------------------------------
 
+  def _beginTransaction (self):
+    """
+    Start a new transaction (to be implemented by descendants).
+
+    Database drivers can overwrite this method that gets called after
+    connecting to the database as well as after each commit and rollback.  If
+    it is not overwritten, it does nothing.
+    """
+    pass
+
+  # ---------------------------------------------------------------------------
+
   def _commit (self):
     """
     Commit pending changes in the backend (to be implemented by descendants).
@@ -378,18 +390,6 @@
 
   # ---------------------------------------------------------------------------
 
-  def _startTransaction (self):
-    """
-    Start a new transaction (to be implemented by descendants).
-
-    Database drivers can overwrite this method that gets called after
-    connecting to the database as well as after each commit and rollback.  If
-    it is not overwritten, it does nothing.
-    """
-    pass
-
-  # ---------------------------------------------------------------------------
-
   def _close (self):
     """
     Close the connection to the backend (to be implemented by descendants).

Modified: trunk/gnue-common/src/datasources/drivers/DBSIG2/Connection.py
===================================================================
--- trunk/gnue-common/src/datasources/drivers/DBSIG2/Connection.py      
2005-03-09 22:37:01 UTC (rev 7146)
+++ trunk/gnue-common/src/datasources/drivers/DBSIG2/Connection.py      
2005-03-09 23:29:42 UTC (rev 7147)
@@ -1,6 +1,9 @@
+# GNU Enterprise Common Library - DBSIG2 DB Driver - Connection
 #
-# This file is part of GNU Enterprise.
+# Copyright 2001-2005 Free Software Foundation
 #
+# This file is part of GNU Enterprise
+#
 # GNU Enterprise is free software; you can redistribute it
 # and/or modify it under the terms of the GNU General Public
 # License as published by the Free Software Foundation; either
@@ -16,52 +19,47 @@
 # write to the Free Software Foundation, Inc., 59 Temple Place
 # - Suite 330, Boston, MA 02111-1307, USA.
 #
-# Copyright 2000-2005 Free Software Foundation
-#
-# FILE:
-# _dbsig/DBdriver.py
-#
-# DESCRIPTION:
-# Generic implementation of dbdriver using Python DB-SIG v2
-# specification.
-#
-# NOTES:
-# The classes below are meant to be extended
-#
-# HISTORY:
-#
 # $Id$
 
 __all__ = ['Connection']
 
 from types import *
 
-from gnue.common.datasources import Exceptions
-from gnue.common.datasources.drivers.Base.Connection import Connection as 
BaseConnection
-from gnue.common.apps import errors
 import string
 import sys
 import mx.DateTime
 
-class Connection (BaseConnection):
-  """
-  The base class for all drivers that use DBSIG2 compatible modules. All
-  these drivers I{must} subclass this class.
+from gnue.common.apps import errors, GDebug
+from gnue.common.datasources import Exceptions
+from gnue.common.datasources.drivers import Base
 
-  Descendants I{must} override the following class variables:
+# =============================================================================
+# Generic DBSIG2 connection class
+# =============================================================================
 
-  @param _driver: the loaded Python module of the DBSIG2 driver
+class Connection (Base.Connection):
+  """
+  The base class for all drivers that use DBSIG2 compatible modules.
 
-  Descendants I{may} override the following class variables:
+  Driver plugins derived from this driver must subclass this class and
+  overwrite at least the L{_driver} class variable and implement the _connect
+  method as defined in L{Base.Connection.Connection._connect}.
 
-  @param _boolean_false: Value to post to the database for boolean FALSE
-      (defaults to '0')
-  @param _boolean_true: Value to post to the database for boolean TRUE
-      (defaults to '1')
-  @param _numbers_as_string: Flags wether to convert numbers to strings or not
-  @param _named_as_sequence: If paramstyle = 'named' pass parameters as
-      sequence (True) or as mapping (False)
+  @cvar _driver: The loaded Python module of the DBSIG2 driver. Must be
+    overwritten by descendants.
+  @cvar _boolean_false: Value to post to the database for boolean FALSE
+    (defaults to '0'). Can be overwritten by descendants.
+  @cvar _boolean_true: Value to post to the database for boolean TRUE
+    (defaults to '1'). Can be overwritten by descendants.
+  @cvar _broken_fetchmany: Can be set to True by descendants if the DBSIG2
+    driver raises an exception if fetchmany() is called when no records are
+    left.
+  @cvar _numbers_as_string: Flags wether to convert numbers to strings or not.
+    Can be overwritten by descendants.
+  @cvar _named_as_sequence: If paramstyle = 'named' pass parameters as
+    sequence (True) or as mapping (False). Can be overwritten by descendants.
   """
+
   _driver = None                        # DBSIG2 compatible driver module
   _boolean_false = '0'                  # value to pass for boolean FALSE
   _boolean_true  = '1'                  # value to pass for boolean TRUE
@@ -70,54 +68,7 @@
   _numbers_as_string = True             # Convert numbers into strings
   _named_as_sequence = False            # Pass 'named' parameters as sequence
 
-  # This should be over-ridden only if driver needs more than user/pass
-  def getLoginFields(self):
-    return [['_username', _('User Name'),0],['_password', _('Password'),1]]
 
-  def commit(self):
-    gDebug (8,"DB-SIG database driver: commit()")
-
-    try:
-      self.native.commit()
-      
-    except self._DatabaseError, value:
-      raise Exceptions.ConnectionError, errors.getException () [2]
-
-    self._beginTransaction()
-
-  def rollback(self):
-    gDebug (8,"DB-SIG database driver: rollback()")
-
-    try:
-      self.native.rollback()
-    except:
-      pass     # I'm SURE this isn't right (jcater)
-                # But not all db's support transactions
-
-    self._beginTransaction()
-
-  def close(self):
-    """
-    Close the DBSIG2 Connection.
-    """
-    BaseConnection.close (self)
-
-    if hasattr (self, 'native') and self.native is not None:
-      self.native.close ()
-    
-    
-  def _beginTransaction(self):
-    """
-    Code necessary to force the connection into transaction mode...
-    this is usually not necessary (MySQL is one of few DBs that must force)
-    """
-    pass
-
-
-  # ===========================================================================
-  # SQL statement handling
-  # ===========================================================================
-
   # ---------------------------------------------------------------------------
   # Convert type into what the DBSIG2 driver wants as parameter
   # ---------------------------------------------------------------------------
@@ -148,7 +99,6 @@
         return str (value)
       else:
         return value
-    
 
     elif isinstance (value, FloatType):
       # Some databases (especially postgres) want floating point numbers
@@ -169,6 +119,7 @@
       # Strings, Integers
       return value
 
+
   # ---------------------------------------------------------------------------
   # Change SQL statement and parameters to different paramstyles
   # ---------------------------------------------------------------------------
@@ -192,6 +143,8 @@
       l.append (parameters [key])
     return (s, l)
 
+  # ---------------------------------------------------------------------------
+
   def __param_numeric (self, statement, parameters):
     s = statement
     l = []
@@ -209,6 +162,8 @@
       l.append (parameters [key])
     return (s, l)
 
+  # ---------------------------------------------------------------------------
+
   def __param_named (self, statement, parameters):
     s = statement
     values = []
@@ -225,6 +180,7 @@
 
     return (s, self._named_as_sequence and values or parameters)
 
+  # ---------------------------------------------------------------------------
 
   def __param_format (self, statement, parameters):
     s = statement
@@ -241,6 +197,7 @@
       l.append (parameters [key])
     return (s, l)
 
+
   # ---------------------------------------------------------------------------
   # Create a new DBSIG2 cursor object and execute the given SQL statement
   # ---------------------------------------------------------------------------
@@ -250,10 +207,11 @@
     Create a new DBSIG2 cursor object and execute the given SQL statement.
 
     @param statement: The SQL statement as either 8-bit or unicode string. Can
-        contain %(name)s style placeholders for parameters.
+      contain %(name)s style placeholders for parameters.
     @param parameters: A dictionary with the parameter values. The values of
-        the dictionary can be 8-bit strings, unicode strings, integer or
-        floating point numbers, booleans or mx.DateTime values.
+      the dictionary can be 8-bit strings, unicode strings, integer or floating
+      point numbers, booleans or mx.DateTime values.
+    @return: A DBSIG2 cursor object holding the result of the query.
     """
     checktype (statement, [StringType, UnicodeType])
     checktype (parameters, [DictionaryType, NoneType])
@@ -308,6 +266,7 @@
 
     return cursor
 
+
   # ---------------------------------------------------------------------------
   # Execute the given SQL statement and return the result matrix
   # ---------------------------------------------------------------------------
@@ -317,10 +276,11 @@
     Execute the given SQL statement and return the result matrix.
 
     @param statement: The SQL statement as either 8-bit or unicode string. Can
-        contain %(name)s style placeholders for parameters.
+      contain %(name)s style placeholders for parameters.
     @param parameters: A dictionary with the parameter values. The values of
-        the dictionary can be 8-bit strings, unicode strings, integer or
-        floating point numbers, booleans or mx.DateTime values.
+      the dictionary can be 8-bit strings, unicode strings, integer or floating
+      point numbers, booleans or mx.DateTime values.
+    @return: A 2-dimensional matrix holding the complete result of the query.
     """
     result = None
     cursor = self.makecursor (statement, parameters)
@@ -341,6 +301,7 @@
     else:
       return []
 
+
   # ---------------------------------------------------------------------------
   # Execute the given SQL statement that is expected to return a single value
   # ---------------------------------------------------------------------------
@@ -348,13 +309,16 @@
   def sql1 (self, statement, parameters = None):
     """
     Execute the given SQL statement that is expected to return a single value.
-    If the query returns nothing, None is returned
 
+    If the query returns nothing, None is returned.
+
     @param statement: The SQL statement as either 8-bit or unicode string. Can
-        contain %(name)s style placeholders for parameters.
+      contain %(name)s style placeholders for parameters.
     @param parameters: A dictionary with the parameter values. The values of
-        the dictionary can be 8-bit strings, unicode strings, integer or
-        floating point numbers, booleans or mx.DateTime values.
+      the dictionary can be 8-bit strings, unicode strings, integer or floating
+      point numbers, booleans or mx.DateTime values.
+    @return: The value returned by the query. If the query returns more than a
+      single value, the first column of the first row is returned.
     """
     cursor = self.makecursor (statement, parameters)
     try:
@@ -366,3 +330,34 @@
       return result [0]
     else:
       return None
+
+
+  # ---------------------------------------------------------------------------
+  # Implementations of virtual methods
+  # ---------------------------------------------------------------------------
+
+  def _getLoginFields (self):
+    return [('_username', _('User Name'), 0), ('_password', _('Password'), 1)]
+
+  # ---------------------------------------------------------------------------
+
+  def _commit (self):
+    try:
+      self.native.commit ()
+    except self._DatabaseError, value:
+      raise Exceptions.ConnectionError, errors.getException () [2]
+
+  # ---------------------------------------------------------------------------
+
+  def _rollback (self):
+    try:
+      self.native.rollback ()
+    except:
+      pass     # I'm SURE this isn't right (jcater)
+                # But not all db's support transactions
+
+  # ---------------------------------------------------------------------------
+
+  def _close (self):
+    if hasattr (self, 'native') and self.native is not None:
+      self.native.close ()