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

[reinhard]

Author: reinhard
Date: 2005-03-09 16:37:01 -0600 (Wed, 09 Mar 2005)
New Revision: 7146

Modified:
   trunk/gnue-common/src/datasources/drivers/Base/Connection.py
   trunk/gnue-common/src/datasources/drivers/Base/__init__.py
   trunk/gnue-common/src/datasources/drivers/__init__.py
Log:
More work on docstrings, defined purely virtual methods for Connection object.


Modified: trunk/gnue-common/src/datasources/drivers/Base/Connection.py
===================================================================
--- trunk/gnue-common/src/datasources/drivers/Base/Connection.py        
2005-03-09 21:49:35 UTC (rev 7145)
+++ trunk/gnue-common/src/datasources/drivers/Base/Connection.py        
2005-03-09 22:37:01 UTC (rev 7146)
@@ -24,31 +24,32 @@
 import copy
 import string
 
+from gnue.common.apps import GDebug
 
+
 # =============================================================================
 # Basic connection class
 # =============================================================================
 
 class Connection:
   """
+  Generic database connection class.
+
   This class must be subclassed by all database drivers. It represents a
   connection to the backend.
 
-  Following instance variables are available:
-  @param name: name of the connection from connections.conf
-  @param parameters: parameters from connections.conf
-  @param manager: the connection manager (GConnections) instance responsible
-      for this connection
+  @cvar defaultBehaviour: standard schema introspector class for this type of
+    connection.  Must be overwritten by descendants
+  @cvar defaultCreator: standard schema creator class for this type of
+    connection.  Must be overwritten by descendants
+  @cvar supportedDataObjects: dictionary of dataObject classes available for
+    this connection type, where the key is the type of the dataObject (can be
+    'object' or 'sql').  Must be overwritten by descendants
 
-  Descendants I{must} override the following class variables:
-
-  @param defaultBehaviour: standard schema introspector class for this type of
-      connection
-  @param defaultCreator: standard schema creator class for this type of
-      connection
-  @param supportedDataObjects: dictionary of dataObject classes available for
-      this connection type, where the key is the type of the dataObject (can be
-      'object' or 'sql')
+  @ivar name: Name of the connection from connections.conf.
+  @ivar parameters: Parameters from connections.conf.
+  @ivar manager: The connection manager (GConnections) instance responsible
+    for this connection.
   """
 
   defaultBehaviour = None
@@ -79,64 +80,90 @@
 
 
   # ---------------------------------------------------------------------------
-  # Virtual methods to be implemented by descendants
+  # Define fields necessary for login
   # ---------------------------------------------------------------------------
 
   def getLoginFields (self):
     """
-    This method should be overwritten by the database drivers to return a list
-    of tuples in the form (fieldname, label, hide). The first element of the
-    tuple is the field name passed as a dictionary key to the connect method
-    later. The second element is a label to display to the user. If the third
-    element is True, the input for this field should be hidden on the screen.
+    Return information about the necessary login parameters for the L{connect}
+    method.
+
+    The return value is a list of tuples in the form (fieldname, label, hide).
+    The first element of the tuple is the field name passed as a dictionary key
+    to the connect method later. The second element is a label to display to
+    the user. If the third element is True, the input for this field should be
+    hidden on the screen.
+
     A typical return value would be [("username", "User name:", False),
     ("password", "Password:", True)].
     """
-    return []
 
+    gEnter (8)
+    return gLeave (8, self._getLoginFields ())
+
   # ---------------------------------------------------------------------------
+  # Connect to the backend
+  # ---------------------------------------------------------------------------
 
-  def connect(self, connectData):
+  def connect (self, connectData):
     """
-    This method should be overwritten by the database drivers to connect to the
-    backend.
+    Connect to the backend.
 
     @param connectData: A dictionary with the login fields as requested by
-        getLoginFields and all parameters from connections.conf.
+      L{getLoginFields} and all parameters from connections.conf.
     """
-    pass
 
+    gEnter (8)
+    self._connect (connectData)
+    self._startTransaction ()
+    gLeave (8)
+
   # ---------------------------------------------------------------------------
+  # Commit pending changes in the backend
+  # ---------------------------------------------------------------------------
 
-  def commit(self):
+  def commit (self):
     """
-    This method should be overwritten by the database drivers to commit data to
-    the backend.
+    Commit pending changes in the backend and start a new transaction.
     """
-    pass
 
+    gEnter (8)
+    self._commit ()
+    self._startTransaction ()
+    gLeave (8)
+
   # ---------------------------------------------------------------------------
+  # Undo any uncommitted changes in the backend
+  # ---------------------------------------------------------------------------
 
-  def rollback(self):
+  def rollback (self):
     """
-    This method should be overwritten by the database drivers to abort and roll
-    back any running transaction.
+    Undo any uncommitted changes in the backend and start a new transaction.
     """
-    pass
 
+    gEnter (8)
+    self._rollback ()
+    self._startTransaction ()
+    gLeave (8)
+
   # ---------------------------------------------------------------------------
+  # Close the connection to the backend
+  # ---------------------------------------------------------------------------
 
   def close (self):
     """
-    This method should be overwritten by the database drivers to close the
-    connection to the backend.
+    Close the connection to the backend.
     """
+
+    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)
 
 
   # ---------------------------------------------------------------------------
@@ -145,8 +172,8 @@
 
   def getSchemaCreator (self):
     """
-    This function creates a new instance of the schema creator associated with
-    this driver or None if no creator is available.
+    Create a new instance of the schema creator associated with this driver or
+    None if no creator is available.
     """
 
     if self.defaultCreator:
@@ -161,16 +188,15 @@
 
   def updateSchema (self, definition, codeOnly = False):
     """
-    This function modifies the database schema according to the given
-    definition, which is a dictionary of table defininitions (@see:
-    Schema.Creation.Creation), where the tablenames are the keys.
-
-    @param definition: sequence of table definitions
-    @param codeOnly: if TRUE, only the code will be generated to modify the
-        schema, no actions take place.
+    Modify the database schema according to the given definition.
+    
+    @param definition: Sequence of table definitions.
+      @see: Schema.Creation.Creation
+    @param codeOnly: If True, only the code will be generated to modify the
+      schema, no actions take place.
     @return: a tuple of three sequences (prologue, body, epilogue) holding the
-        code to perform all schema modifications needed. These sequences should
-        be executed in this order to successfully create the schema.
+      code to perform all schema modifications needed. These sequences should
+      be executed in this order to successfully create the schema.
     """
 
     result = ([], [], [])
@@ -298,6 +324,83 @@
 
 
   # ---------------------------------------------------------------------------
+  # Virtual methods to be implemented by descendants
+  # ---------------------------------------------------------------------------
+
+  def _getLoginFields (self):
+    """
+    Return information about the necessary login parameters for the L{connect}
+    method (to be implemented by descendants).
+
+    Descendants can overwrite this method to return a list of necessary login
+    fields as defined in L{getLoginFields}.
+
+    If this method is not overwritten, it returns an empty list.
+    """
+    return []
+
+  # ---------------------------------------------------------------------------
+
+  def _connect (self, connectData):
+    """
+    Connect to the backend (to be implemented by descendants).
+
+    This method can be overwritten by the database drivers to connect to the
+    backend.  If it is not overwritten, it does nothing.
+
+    @param connectData: A dictionary with the login fields as requested by
+      getLoginFields and all parameters from connections.conf.
+    """
+    pass
+
+  # ---------------------------------------------------------------------------
+
+  def _commit (self):
+    """
+    Commit pending changes in the backend (to be implemented by descendants).
+
+    This method can be overwritten by the database drivers to commit data to
+    the backend.  If it is not overwritten, it does nothing.
+    """
+    pass
+
+  # ---------------------------------------------------------------------------
+
+  def _rollback (self):
+    """
+    Undo any uncommitted changes in the backend (to be implemented by
+    descendants).
+
+    This can should be overwritten by the database drivers to abort and roll
+    back any running transaction.  If it is not overwritten, it does nothing.
+    """
+    pass
+
+  # ---------------------------------------------------------------------------
+
+  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).
+
+    This method can be overwritten by the database drivers to close the
+    connection to the backend.  If it is not overwritten, it does nothing.
+    """
+    pass
+
+
+  # ---------------------------------------------------------------------------
   # Nice string representation
   # ---------------------------------------------------------------------------
 

Modified: trunk/gnue-common/src/datasources/drivers/Base/__init__.py
===================================================================
--- trunk/gnue-common/src/datasources/drivers/Base/__init__.py  2005-03-09 
21:49:35 UTC (rev 7145)
+++ trunk/gnue-common/src/datasources/drivers/Base/__init__.py  2005-03-09 
22:37:01 UTC (rev 7146)
@@ -1,6 +1,9 @@
+# GNU Enterprise Common Library - Base DB Driver
 #
-# 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,17 +19,12 @@
 # write to the Free Software Foundation, Inc., 59 Temple Place
 # - Suite 330, Boston, MA 02111-1307, USA.
 #
-# Copyright 2000-2005 Free Software Foundation
-#
-# FILE:
-# Base/__init__.py
-#
-# DESCRIPTION:
-#
-# NOTES:
-#
-# $Id :$
+# $Id$
 
+"""
+Generic base classes for database driver plugins.
+"""
+
 # Indicate that this is no plugin
 __noplugin__ = True
 


Property changes on: trunk/gnue-common/src/datasources/drivers/Base/__init__.py
___________________________________________________________________
Name: svn:keywords
   - +Id
   + Id

Modified: trunk/gnue-common/src/datasources/drivers/__init__.py
===================================================================
--- trunk/gnue-common/src/datasources/drivers/__init__.py       2005-03-09 
21:49:35 UTC (rev 7145)
+++ trunk/gnue-common/src/datasources/drivers/__init__.py       2005-03-09 
22:37:01 UTC (rev 7146)
@@ -1,10 +1,13 @@
+# GNU Enterprise Common Library - DB Drivers
 #
-# 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
-# version 2, or(at your option) any later version.
+# version 2, or (at your option) any later version.
 #
 # GNU Enterprise is distributed in the hope that it will be
 # useful, but WITHOUT ANY WARRANTY; without even the implied
@@ -16,8 +19,8 @@
 # write to the Free Software Foundation, Inc., 59 Temple Place
 # - Suite 330, Boston, MA 02111-1307, USA.
 #
-# Copyright 2000-2005 Free Software Foundation
-#
+# $Id$
+
 """
-Database-specific datasource drivers
+Database driver plugins.
 """


Property changes on: trunk/gnue-common/src/datasources/drivers/__init__.py
___________________________________________________________________
Name: svn:keywords
   + Id