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

PersistentDB - persistent DB-API 2 connections.
 
Implements steady, thread-affine persistent connections to a database
based on an arbitrary DB-API 2 compliant database interface module.
 
This should result in a speedup for persistent applications such as the
application server of "Webware for Python," without loss of robustness.
 
Robustness is provided by using "hardened" SteadyDB connections.
Even if the underlying database is restarted and all connections
are lost, they will be automatically and transparently reopened.
However, since you don't want this to happen in the middle of a database
transaction, you must explicitly start transactions with the begin()
method so that SteadyDB knows that the underlying connection shall not
be replaced and errors passed on until the transaction is completed.
 
Measures are taken to make the database connections thread-affine.
This means the same thread always uses the same cached connection,
and no other thread will use it. So even if the underlying DB-API module
is not thread-safe at the connection level this will be no problem here.
 
For best performance, the application server should keep threads persistent.
For this, you have to set MinServerThreads = MaxServerThreads in Webware.
 
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:
 
First you need to set up a generator for your kind of database connections
by creating an instance of PersistentDB, passing the following parameters:
 
    creator: either an arbitrary function returning new DB-API 2
        connection objects or a DB-API 2 compliant database module
    maxusage: the maximum number of reuses of a single connection
        (the default of 0 or None means unlimited reuse)
        Whenever the limit is reached, the connection will be reset.
    setsession: an optional list of SQL commands that may serve to
        prepare the session, e.g. ["set datestyle to german", ...].
    failures: an optional exception class or a tuple of exception classes
        for which the connection failover mechanism shall be applied,
        if the default (OperationalError, InternalError) is not adequate
    ping: an optional flag controlling when connections are checked
        with the ping() method if such a method is available
        (0 = None = never, 1 = default = whenever it is requested,
        2 = when 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 true, then closing connections will
        be allowed, but by default this will be silently ignored
    threadlocal: an optional class for representing thread-local data
        that will be used instead of our Python implementation
        (threading.local is faster, but cannot be used in all cases)
 
    The creator function or the connect function of the DB-API 2 compliant
    database module specified as the creator will receive any additional
    parameters such as the host, database, user, password etc. You may
    choose some or all of these parameters in your own creator function,
    allowing for sophisticated failover and load-balancing mechanisms.
 
For instance, if you are using pgdb as your DB-API 2 database module and want
every connection to your local database 'mydb' to be reused 1000 times:
 
    import pgdb # import used DB-API 2 module
    from DBUtils.PersistentDB import PersistentDB
    persist = PersistentDB(pgdb, 1000, database='mydb')
 
Once you have set up the generator with these parameters, you can
request database connections of that kind:
 
    db = persist.connection()
 
You can use these connections just as if they were ordinary
DB-API 2 connections. Actually what you get is the hardened
SteadyDB version of the underlying DB-API 2 connection.
 
Closing a persistent connection with db.close() will be silently
ignored since it would be reopened at the next usage anyway and
contrary to the intent of having persistent connections. Instead,
the connection will be automatically closed when the thread dies.
You can change this behavior be setting the closeable parameter.
 
Note that you need to explicitly start transactions by calling the
begin() method. This ensures that the transparent reopening will be
suspended until the end of the transaction, and that the connection
will be rolled back before being reused by the same thread.
 
By setting the threadlocal parameter to threading.local, getting
connections may become a bit faster, but this may not work in all
environments (for instance, mod_wsgi is known to cause problems
since it clears the threading.local data between requests).
 
 
Requirements:
 
Python >= 2.3, < 3.0.
 
 
Ideas for improvement:
 
* Add a thread for monitoring, restarting (or closing) bad or expired
  connections (similar to DBConnectionPool/ResourcePool by Warren Smith).
* Optionally log usage, bad connections and exceeding of limits.
 
 
Copyright, credits and license:
 
* Contributed as supplement for Webware for Python and PyGreSQL
  by Christoph Zwerschke in September 2005
* Based on an idea presented on the Webware developer mailing list
  by Geoffrey Talvola in July 2005
 
Licensed under the Open Software License version 2.1.

 
Modules
       
DBUtils.ThreadingLocal

 
Classes
       
PersistentDB
exceptions.Exception(exceptions.BaseException)
PersistentDBError
NotSupportedError

 
class NotSupportedError(PersistentDBError)
    DB-API module not supported by PersistentDB.
 
 
Method resolution order:
NotSupportedError
PersistentDBError
exceptions.Exception
exceptions.BaseException
__builtin__.object

Data descriptors inherited from PersistentDBError:
__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 PersistentDB
    Generator for persistent DB-API 2 connections.
 
After you have created the connection pool, you can use
connection() to get thread-affine, steady DB-API 2 connections.
 
  Methods defined here:
__init__(self, creator, maxusage=None, setsession=None, failures=None, ping=1, closeable=False, threadlocal=None, *args, **kwargs)
Set up the persistent DB-API 2 connection generator.
 
creator: either an arbitrary function returning new DB-API 2
    connection objects or a DB-API 2 compliant database module
maxusage: maximum number of reuses of a single connection
    (number of database operations, 0 or None means unlimited)
    Whenever the limit is reached, the connection will be reset.
setsession: optional list of SQL commands that may serve to prepare
    the session, e.g. ["set datestyle to ...", "set time zone ..."]
failures: an optional exception class or a tuple of exception classes
    for which the connection 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 = whenever it is requested,
    2 = when 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 true, then closing connections will
    be allowed, but by default this will be silently ignored
threadlocal: an optional class for representing thread-local data
    that will be used instead of our Python implementation
    (threading.local is faster, but cannot be used in all cases)
args, kwargs: the parameters that shall be passed to the creator
    function or the connection constructor of the DB-API 2 module
connection(self, shareable=False)
Get a steady, persistent DB-API 2 connection.
 
The shareable parameter exists only for compatibility with the
PooledDB connection method. In reality, persistent connections
are of course never shared with other threads.
dedicated_connection(self)
Alias for connection(shareable=False).
steady_connection(self)
Get a steady, non-persistent DB-API 2 connection.

Data and other attributes defined here:
version = '1.1'

 
class PersistentDBError(exceptions.Exception)
    General PersistentDB error.
 
 
Method resolution order:
PersistentDBError
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

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