DBUtils.SteadyDB (version 1.1, $Date: 2011-08-14 13:57:11 +0200 (So, 14. Aug 2011) $)
index
/var/www/docs/Webware-1.1.1/DBUtils/SteadyDB.py

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'