SteadyDB - hardened DB-API 2 connections.
 
Implements steady connections to a database based on an
arbitrary DB-API 2 compliant database interface module.
 
The connections are transparently reopened when they are
closed or the database connection has been lost or when
they are used more often than an optional usage limit.
Database cursors are transparently reopened as well when
the execution of a database operation cannot be performed
due to a lost connection. Only if the connection is lost
after the execution, when rows are already fetched from the
database, this will give an error and the cursor will not
be reopened automatically, because there is no reliable way
to recover the state of the cursor in such a situation.
Connections which have been marked as being in a transaction
with a begin() call will not be silently replaced either.
 
A typical situation where database connections are lost
is when the database server or an intervening firewall is
shutdown and restarted for maintenance reasons. In such a
case, all database connections would become unusable, even
though the database service may be already available again.
 
The "hardened" connections provided by this module will
make the database connections immediately available again.
 
This approach results in a steady database connection that
can be used by PooledDB or PersistentDB to create pooled or
persistent connections to a database in a threaded environment
such as the application server of "Webware for Python."
Note, however, that the connections themselves may not be
thread-safe (depending on the used DB-API module).
 
For the Python DB-API 2 specification, see:
    http://www.python.org/peps/pep-0249.html
For information on Webware for Python, see:
    http://www.webwareforpython.org
 
Usage:
 
You can use the connection constructor connect() in the same
way as you would use the connection constructor of a DB-API 2
module if you specify the DB-API 2 module to be used as the
first parameter, or alternatively you can specify an arbitrary
constructor function returning new DB-API 2 compliant connection
objects as the first parameter. Passing just a function allows
implementing failover mechanisms and load balancing strategies.
 
You may also specify a usage limit as the second parameter
(set it to None if you prefer unlimited usage), an optional
list of commands that may serve to prepare the session as a
third parameter, the exception classes for which the failover
mechanism shall be applied, and you can specify whether is is
allowed to close the connection (by default this is true).
When the connection to the database is lost or has been used
too often, it will be transparently reset in most situations,
without further notice.
 
    import pgdb # import used DB-API 2 module
    from DBUtils.SteadyDB import connect
    db = connect(pgdb, 10000, ["set datestyle to german"],
        host=..., database=..., user=..., ...)
    ...
    cursor = db.cursor()
    ...
    cursor.execute('select ...')
    result = cursor.fetchall()
    ...
    cursor.close()
    ...
    db.close()
 
 
Ideas for improvement:
 
* Alternatively to the maximum number of uses,
  implement a maximum time to live for connections.
* Optionally log usage and loss of connection.
 
 
Copyright, credits and license:
 
* Contributed as supplement for Webware for Python and PyGreSQL
  by Christoph Zwerschke in September 2005
* Allowing creator functions as first parameter as in SQLAlchemy
  suggested by Ezio Vernacotola in December 2006
 
Licensed under the Open Software License version 2.1.

Modules
		sys

Classes
		SteadyDBConnection SteadyDBCursor exceptions.Exception(exceptions.BaseException) SteadyDBError InvalidCursor   class InvalidCursor(SteadyDBError)     Database cursor is invalid.     Method resolution order: InvalidCursor SteadyDBError exceptions.Exception exceptions.BaseException __builtin__.object Data descriptors inherited from SteadyDBError: __weakref__ list of weak references to the object (if defined) Methods inherited from exceptions.Exception: __init__(...) x.__init__(...) initializes x; see x.__class__.__doc__ for signature Data and other attributes inherited from exceptions.Exception: __new__ = <built-in method __new__ of type object> T.__new__(S, ...) -> a new object with type S, a subtype of T Methods inherited from exceptions.BaseException: __delattr__(...) x.__delattr__('name') <==> del x.name __getattribute__(...) x.__getattribute__('name') <==> x.name __getitem__(...) x.__getitem__(y) <==> x[y] __getslice__(...) x.__getslice__(i, j) <==> x[i:j]   Use of negative indices is not supported. __reduce__(...) __repr__(...) x.__repr__() <==> repr(x) __setattr__(...) x.__setattr__('name', value) <==> x.name = value __setstate__(...) __str__(...) x.__str__() <==> str(x) __unicode__(...) Data descriptors inherited from exceptions.BaseException: __dict__ args message   class SteadyDBConnection     A "tough" version of DB-API 2 connections.     Methods defined here: __del__(self) Delete the steady connection. __init__(self, creator, maxusage=None, setsession=None, failures=None, ping=1, closeable=True, *args, **kwargs) Create a "tough" DB-API 2 connection. begin(self, *args, **kwargs) Indicate the beginning of a transaction.   During a transaction, connections will not not transparently replaced, and all errors will be raised to the application.   If the underlying driver supports this method, it will be called with the given parameters (e.g. for distributed transactions). cancel(self) Cancel a long-running transaction.   If the underlying driver supports this method, it will be called. close(self) Close the tough connection.   You are allowed to close a tough connection by default and it will not complain if you close it more than once.   You can disallow closing connections by setting the closeable parameter to something false. In this case, closing tough connections will be silently ignored. commit(self) Commit any pending transaction. cursor(self, *args, **kwargs) Return a new Cursor Object using the connection. dbapi(self) Return the underlying DB-API 2 module of the connection. ping(self, *args, **kwargs) Ping connection. rollback(self) Rollback pending transaction. threadsafety(self) Return the thread safety level of the connection. Data and other attributes defined here: version = '1.1'   class SteadyDBCursor     A "tough" version of DB-API 2 cursors.     Methods defined here: __del__(self) Delete the steady cursor. __getattr__(self, name) Inherit methods and attributes of underlying cursor. __init__(self, con, *args, **kwargs) Create a "tough" DB-API 2 cursor. close(self) Close the tough cursor.   It will not complain if you close it more than once. setinputsizes(self, sizes) Store input sizes in case cursor needs to be reopened. setoutputsize(self, size, column=None) Store output sizes in case cursor needs to be reopened.   class SteadyDBError(exceptions.Exception)     General SteadyDB error.     Method resolution order: SteadyDBError exceptions.Exception exceptions.BaseException __builtin__.object Data descriptors defined here: __weakref__ list of weak references to the object (if defined) Methods inherited from exceptions.Exception: __init__(...) x.__init__(...) initializes x; see x.__class__.__doc__ for signature Data and other attributes inherited from exceptions.Exception: __new__ = <built-in method __new__ of type object> T.__new__(S, ...) -> a new object with type S, a subtype of T Methods inherited from exceptions.BaseException: __delattr__(...) x.__delattr__('name') <==> del x.name __getattribute__(...) x.__getattribute__('name') <==> x.name __getitem__(...) x.__getitem__(y) <==> x[y] __getslice__(...) x.__getslice__(i, j) <==> x[i:j]   Use of negative indices is not supported. __reduce__(...) __repr__(...) x.__repr__() <==> repr(x) __setattr__(...) x.__setattr__('name', value) <==> x.name = value __setstate__(...) __str__(...) x.__str__() <==> str(x) __unicode__(...) Data descriptors inherited from exceptions.BaseException: __dict__ args message

Functions
		connect(creator, maxusage=None, setsession=None, failures=None, ping=1, closeable=True, *args, **kwargs) A tough version of the connection constructor of a DB-API 2 module.   creator: either an arbitrary function returning new DB-API 2 compliant     connection objects or a DB-API 2 compliant database module maxusage: maximum usage limit for the underlying DB-API 2 connection     (number of database operations, 0 or None means unlimited usage)     callproc(), execute() and executemany() count as one operation.     When the limit is reached, the connection is automatically reset. setsession: an optional list of SQL commands that may serve to prepare     the session, e.g. ["set datestyle to german", "set time zone mez"] failures: an optional exception class or a tuple of exception classes     for which the failover mechanism shall be applied, if the default     (OperationalError, InternalError) is not adequate ping: determines when the connection should be checked with ping()     (0 = None = never, 1 = default = when _ping_check() is called,     2 = whenever a cursor is created, 4 = when a query is executed,     7 = always, and all other bit combinations of these values) closeable: if this is set to false, then closing the connection will     be silently ignored, but by default the connection can be closed args, kwargs: the parameters that shall be passed to the creator     function or the connection constructor of the DB-API 2 module

Data
		__date__ = '$Date: 2011-08-14 13:57:11 +0200 (So, 14. Aug 2011) $' __revision__ = '$Rev: 8218 $' __version__ = '1.1'