[Top][All Lists]
[Date Prev][Date Next][Thread Prev][Thread Next][Date Index][Thread Index]
[gnue] r7781 - trunk/gnue-common/src/datasources/drivers/Base
From: |
reinhard |
Subject: |
[gnue] r7781 - trunk/gnue-common/src/datasources/drivers/Base |
Date: |
Thu, 4 Aug 2005 11:39:08 -0500 (CDT) |
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
[Prev in Thread] |
Current Thread |
[Next in Thread] |
- [gnue] r7781 - trunk/gnue-common/src/datasources/drivers/Base,
reinhard <=