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

[reinhard]

Author: reinhard
Date: 2005-08-03 09:05:53 -0500 (Wed, 03 Aug 2005)
New Revision: 7775

Modified:
   trunk/gnue-common/src/datasources/Exceptions.py
   trunk/gnue-common/src/datasources/GDataSource.py
   trunk/gnue-common/src/datasources/drivers/Base/Connection.py
   trunk/gnue-common/src/datasources/drivers/Base/RecordSet.py
Log:
Started exception cleanup and documentation.


Modified: trunk/gnue-common/src/datasources/Exceptions.py
===================================================================
--- trunk/gnue-common/src/datasources/Exceptions.py     2005-08-03 04:23:13 UTC 
(rev 7774)
+++ trunk/gnue-common/src/datasources/Exceptions.py     2005-08-03 14:05:53 UTC 
(rev 7775)
@@ -108,6 +108,28 @@
 
 # -----------------------------------------------------------------------------
 
+class MissingSqlDefinitionError (InvalidDatasourceDefinition):
+  """
+  Datasource is of type 'sql', but has no <sql> definition
+  """
+  def __init__ (self, name):
+    InvalidDatasourceDefinition.__init__ (self,
+        u_("Datasource %s is of type 'sql', but has no <sql> definition.") \
+            % name)
+
+# -----------------------------------------------------------------------------
+
+class NotSqlTypeError (InvalidDatasourceDefinition):
+  """
+  Datasource is not of type 'sql', but has an <sql> definition
+  """
+  def __init__ (self, name):
+    InvalidDatasourceDefinition.__init__ (self,
+        u_("Datasource %s is not of type 'sql', but has an <sql> definition.") 
\
+            % name)
+
+# -----------------------------------------------------------------------------
+
 class MasterNotFoundError (InvalidDatasourceDefinition):
   """
   "master" attribute points to an non-existant datasource.
@@ -144,7 +166,7 @@
 class MasterDetailFieldMismatch (InvalidDatasourceDefinition):
   """
   "masterfield" and "detailfield" attributes contain different numbers of
-  fields
+  fields.
   """
   def __init__ (self, name):
     InvalidDatasourceDefinition.__init__ (self,
@@ -166,19 +188,22 @@
 
 
 # -----------------------------------------------------------------------------
+# Cannot call a function of an empty record
+# -----------------------------------------------------------------------------
+
+class FunctionCallOfEmptyRecordError (errors.ApplicationError):
+  """
+  Cannot call a function on an empty record - it doesn't exist in the backend.
+  """
+  def __init__ (self):
+    errors.ApplicationError.__init__ (self,
+        u_("Cannot call a function on an empty record"))
+
+
+# -----------------------------------------------------------------------------
 #
 # -----------------------------------------------------------------------------
 
 class ConnectionError(errors.AdminError):
   # Generic error reading from the database connection
   pass
-
-class DataTypeNotAvailable(errors.ApplicationError):
-  # Raised when a datatype is not supported by an database
-  # during writing a schema definition to the database
-  pass
-
-class NoWriteSchemaSupport(Error):
-  # Raised when a database adapter doesn't support
-  # writing Schema to datasource
-  pass

Modified: trunk/gnue-common/src/datasources/GDataSource.py
===================================================================
--- trunk/gnue-common/src/datasources/GDataSource.py    2005-08-03 04:23:13 UTC 
(rev 7774)
+++ trunk/gnue-common/src/datasources/GDataSource.py    2005-08-03 14:05:53 UTC 
(rev 7775)
@@ -298,13 +298,9 @@
 
     # Check whether the type matches the used tags
     if self.type == "sql" and self._rawSQL is None:
-      raise Exceptions.InvalidDatasourceDefintion, \
-        u_("Datasource %s is sql-based, but has no <sql> definition.") \
-        % self.name
+      raise Exceptions.MissingSqlDefinitionError, self.name
     elif not self.type == "sql" and self._rawSQL is not None:
-      raise Exceptions.InvalidDatasourceDefintion, \
-        u_("Datasource %s is not sql-based, but has a <sql> definition.") \
-        % self.name
+      raise Exceptions.NotSqlTypeError, self.name
 
     # compatibility
     self.extensions = self._connection

Modified: trunk/gnue-common/src/datasources/drivers/Base/Connection.py
===================================================================
--- trunk/gnue-common/src/datasources/drivers/Base/Connection.py        
2005-08-03 04:23:13 UTC (rev 7774)
+++ trunk/gnue-common/src/datasources/drivers/Base/Connection.py        
2005-08-03 14:05:53 UTC (rev 7775)
@@ -70,7 +70,17 @@
   # ---------------------------------------------------------------------------
 
   def __init__ (self, connections, name, parameters):
+    """
+    Create a new Connection instance.
 
+    Usually, this is achieved via L{GConnections.GConnections.getConnection}.
+
+    @param connections: Connection manager (instance of
+      L{GConnections.GConnections}.
+    @param name: Name of the connection.
+    @param parameters: Connection parameters from connections.conf.
+    """
+
     self.manager    = connections
     self.name       = name
     self.parameters = parameters
@@ -130,6 +140,8 @@
     A typical return value would be::
       [(_('User Name'), '_username', 'string', None, None, []),
        (_('Password'), '_password', 'password', None, None, [])]
+
+    @raise errors.AdminError: if the communication with the backend fails.
     """
 
     gEnter (8)
@@ -146,6 +158,10 @@
 
     @param connectData: A dictionary with the login fields as requested by
       L{getLoginFields} and all parameters from connections.conf.
+    @raise Exceptions.LoginError: if the authentication failed and can be tried
+      again.
+    @raise Exception: if the connection fails. The exact exception class
+      depends on the backend.
     """
 
     gEnter (8)
@@ -165,6 +181,8 @@
     @param table: Table name.
     @param fields: List of field names.
     @return: Dictionary with fieldname/value pairs.
+    @raise Exception: if the retrieval of default values from the backend
+      fails. The exact exception class depends on the backend.
     """
 
     gEnter (8)
@@ -183,6 +201,8 @@
     @param newfields: Fieldname/Value dictionary of data to insert.
     @return: The rowid of the newly inserted record, or None if no rowid's are
     supported.
+    @raise Exception: if the insert fails. The exact exception type depends on
+      the backend.
     """
 
     gEnter (8)
@@ -203,6 +223,8 @@
     @param oldfields: Fieldname/Value dictionary of fields to find the existing
       record (aka where-clause).
     @param newfields: Fieldname/Value dictionary of data to change.
+    @raise Exception: if the update fails. The exact exception type depends on
+      the backend.
     """
 
     gEnter (8)
@@ -222,6 +244,8 @@
     @param table: Table name.
     @param oldfields: Fieldname/Value dictionary of fields to find the existing
       record (aka where-clause).
+    @raise Exception: if the deletion fails. The exact exception type depends
+      on the backend.
     """
 
     gEnter (8)
@@ -243,6 +267,8 @@
       record (aka where-clause).
     @param fields: List of field names to query.
     @return: Fieldname/Value dictionary with data fresh from the backend.
+    @raise Exception: if the requery fails. The exact exception type depends on
+      the backend.
     """
 
     gEnter (8)
@@ -263,6 +289,8 @@
     @param methodname: Name of the function to call.
     @param parameters: parametername/value dictionary.
     @return: Result of the function that was called.
+    @raise Exception: if the call fails. The exact exception type depends on
+      the backend.
     """
 
     gEnter (8)
@@ -295,6 +323,9 @@
   def commit (self):
     """
     Commit pending changes in the backend and start a new transaction.
+
+    @raise Exception: if the commit fails. The exact exception type depends on
+      the backend.
     """
 
     gEnter (8)
@@ -311,6 +342,9 @@
   def rollback (self):
     """
     Undo any uncommitted changes in the backend and start a new transaction.
+
+    @raise Exception: if the rollback fails. The exact exception type depends
+      on the backend.
     """
 
     gEnter (8)
@@ -327,6 +361,9 @@
   def close (self):
     """
     Close the connection to the backend.
+
+    @raise Exception: if the close fails. The exact exception type depends on
+      the backend.
     """
 
     gEnter (8)

Modified: trunk/gnue-common/src/datasources/drivers/Base/RecordSet.py
===================================================================
--- trunk/gnue-common/src/datasources/drivers/Base/RecordSet.py 2005-08-03 
04:23:13 UTC (rev 7774)
+++ trunk/gnue-common/src/datasources/drivers/Base/RecordSet.py 2005-08-03 
14:05:53 UTC (rev 7775)
@@ -25,7 +25,6 @@
 RecordSet class used by all database driver plugins.
 """
 
-from gnue.common.apps import errors
 from gnue.common.datasources import Exceptions
 
 
@@ -236,6 +235,7 @@
 
     @param fieldname: Field name.
     @param value: Value to set.
+    @raise: L{Exceptions.ReadOnlyModifyError}
     """
     if fieldname in self.__boundFields and self.__readonly:
       raise Exceptions.ReadOnlyModifyError
@@ -292,6 +292,7 @@
 
     @param updateDict: dictionary with the keys being the field names and the
       values being the new values for the fields.
+    @raise: L{Exceptions.ReadOnlyModifyError}
     """
     for (fieldname, value) in updateDict.items ():
       self [fieldname] = value
@@ -343,6 +344,8 @@
 
     The actual deletion occurs on the next call to the L{_post} method (to be
     called via L{ResultSet.post}).
+
+    @raise: L{Exceptions.ReadOnlyDeleteError}
     """
 
     if self.__readonly:
@@ -374,10 +377,13 @@
     @param methodname: Name of the function to call.
     @param parameters: Dictionary with parametername/value pairs.
     @return: Return value of the function that was called.
+
+    @raise: L{Exceptions.FunctionCallOnEmptyRecordError}, whatever the called
+      function raises
     """
 
     if self.isEmpty ():
-      raise errors.ApplicationError, u_("Function call on empty record")
+      raise Exceptions.FunctionCallOnEmptyRecordError
 
     return self.__connection.call (self.__tablename, self.__wherefields (),
         methodname, parameters)