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

PooledDB - pooling for DB-API 2 connections.
 
Implements a pool of steady, thread-safe cached connections
to a database which are transparently reused,
using 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 pool of connections thread-safe.
If the underlying DB-API module is thread-safe at the connection level,
the requested connections may be shared with other threads by default,
but you can also request dedicated connections in case you need them.
 
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 the database connection pool by creating
an instance of PooledDB, passing the following parameters:
 
    creator: either an arbitrary function returning new DB-API 2
        connection objects or a DB-API 2 compliant database module
    mincached: the initial number of idle connections in the pool
        (the default of 0 means no connections are made at startup)
    maxcached: the maximum number of idle connections in the pool
        (the default value of 0 or None means unlimited pool size)
    maxshared: maximum number of shared connections allowed
        (the default value of 0 or None means all connections are dedicated)
        When this maximum number is reached, connections are
        shared if they have been requested as shareable.
    maxconnections: maximum number of connections generally allowed
        (the default value of 0 or None means any number of connections)
    blocking: determines behavior when exceeding the maximum
        (if this is set to true, block and wait until the number of
        connections decreases, but by default an error will be reported)
    maxusage: maximum number of reuses of a single connection
        (the default of 0 or None means unlimited reuse)
        When this maximum usage number of the connection is reached,
        the connection is automatically reset (closed and reopened).
    setsession: an optional list of SQL commands that may serve to
        prepare the session, e.g. ["set datestyle to german", ...]
    reset: how connections should be reset when returned to the pool
        (False or None to rollback transcations started with begin(),
        the default value True always issues a rollback for safety's sake)
    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 fetched from the pool,
        2 = when a cursor is created, 4 = when a query is executed,
        7 = always, and all other bit combinations of these values)
 
    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 a pool of at least five connections to your local database 'mydb':
 
    import pgdb # import used DB-API 2 module
    from DBUtils.PooledDB import PooledDB
    pool = PooledDB(pgdb, 5, database='mydb')
 
Once you have set up the connection pool you can request
database connections from that pool:
 
    db = pool.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.
 
Please note that the connection may be shared with other threads
by default if you set a non-zero maxshared parameter and the DB-API 2
module allows this. If you want to have a dedicated connection, use:
 
    db = pool.connection(shareable=False)
 
You can also use this to get a dedicated connection:
 
    db = pool.dedicated_connection()
 
If you don't need it any more, you should immediately return it to the
pool with db.close(). You can get another connection in the same way.
 
Warning: In a threaded environment, never do the following:
 
    pool.connection().cursor().execute(...)
 
This would release the connection too early for reuse which may be
fatal if the connections are not thread-safe. Make sure that the
connection object stays alive as long as you are using it, like that:
 
    db = pool.connection()
    cur = db.cursor()
    cur.execute(...)
    res = cur.fetchone()
    cur.close() # or del cur
    db.close() # or del db
 
Note that you need to explicitly start transactions by calling the
begin() method. This ensures that the connection will not be shared
with other threads, that the transparent reopening will be suspended
until the end of the transaction, and that the connection will be rolled
back before being given back to the connection pool.
 
 
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 the code of DBPool, contributed to Webware for Python
  by Dan Green in December 2000
 
Licensed under the Open Software License version 2.1.

 
Classes
       
PooledDB
PooledDedicatedDBConnection
PooledSharedDBConnection
SharedDBConnection
exceptions.Exception(exceptions.BaseException)
PooledDBError
InvalidConnection
NotSupportedError
TooManyConnections

 
class InvalidConnection(PooledDBError)
    Database connection is invalid.
 
 
Method resolution order:
InvalidConnection
PooledDBError
exceptions.Exception
exceptions.BaseException
__builtin__.object

Data descriptors inherited from PooledDBError:
__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 NotSupportedError(PooledDBError)
    DB-API module not supported by PooledDB.
 
 
Method resolution order:
NotSupportedError
PooledDBError
exceptions.Exception
exceptions.BaseException
__builtin__.object

Data descriptors inherited from PooledDBError:
__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 PooledDB
    Pool for DB-API 2 connections.
 
After you have created the connection pool, you can use
connection() to get pooled, steady DB-API 2 connections.
 
  Methods defined here:
__del__(self)
Delete the pool.
__init__(self, creator, mincached=0, maxcached=0, maxshared=0, maxconnections=0, blocking=False, maxusage=None, setsession=None, reset=True, failures=None, ping=1, *args, **kwargs)
Set up the DB-API 2 connection pool.
 
creator: either an arbitrary function returning new DB-API 2
    connection objects or a DB-API 2 compliant database module
mincached: initial number of idle connections in the pool
    (0 means no connections are made at startup)
maxcached: maximum number of idle connections in the pool
    (0 or None means unlimited pool size)
maxshared: maximum number of shared connections
    (0 or None means all connections are dedicated)
    When this maximum number is reached, connections are
    shared if they have been requested as shareable.
maxconnections: maximum number of connections generally allowed
    (0 or None means an arbitrary number of connections)
blocking: determines behavior when exceeding the maximum
    (if this is set to true, block and wait until the number of
    connections decreases, otherwise an error will be reported)
maxusage: maximum number of reuses of a single connection
    (0 or None means unlimited reuse)
    When this maximum usage number of the connection is reached,
    the connection is automatically reset (closed and reopened).
setsession: optional list of SQL commands that may serve to prepare
    the session, e.g. ["set datestyle to ...", "set time zone ..."]
reset: how connections should be reset when returned to the pool
    (False or None to rollback transcations started with begin(),
    True to always issue a rollback for safety's sake)
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 fetched from the pool,
    2 = when a cursor is created, 4 = when a query is executed,
    7 = always, and all other bit combinations of these values)
args, kwargs: the parameters that shall be passed to the creator
    function or the connection constructor of the DB-API 2 module
cache(self, con)
Put a dedicated connection back into the idle cache.
close(self)
Close all connections in the pool.
connection(self, shareable=True)
Get a steady, cached DB-API 2 connection from the pool.
 
If shareable is set and the underlying DB-API 2 allows it,
then the connection may be shared with other threads.
dedicated_connection(self)
Alias for connection(shareable=False).
steady_connection(self)
Get a steady, unpooled DB-API 2 connection.
unshare(self, con)
Decrease the share of a connection in the shared cache.

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

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

 
class PooledDedicatedDBConnection
    Auxiliary proxy class for pooled dedicated connections.
 
  Methods defined here:
__del__(self)
Delete the pooled connection.
__getattr__(self, name)
Proxy all members of the class.
__init__(self, pool, con)
Create a pooled dedicated connection.
 
pool: the corresponding PooledDB instance
con: the underlying SteadyDB connection
close(self)
Close the pooled dedicated connection.

 
class PooledSharedDBConnection
    Auxiliary proxy class for pooled shared connections.
 
  Methods defined here:
__del__(self)
Delete the pooled connection.
__getattr__(self, name)
Proxy all members of the class.
__init__(self, pool, shared_con)
Create a pooled shared connection.
 
pool: the corresponding PooledDB instance
con: the underlying SharedDBConnection
close(self)
Close the pooled shared connection.

 
class SharedDBConnection
    Auxiliary class for shared connections.
 
  Methods defined here:
__eq__(self, other)
__ge__(self, other)
__gt__(self, other)
__init__(self, con)
Create a shared connection.
 
con: the underlying SteadyDB connection
__le__(self, other)
__lt__(self, other)
__ne__(self, other)
share(self)
Increase the share of this connection.
unshare(self)
Decrease the share of this connection.

 
class TooManyConnections(PooledDBError)
    Too many database connections were opened.
 
 
Method resolution order:
TooManyConnections
PooledDBError
exceptions.Exception
exceptions.BaseException
__builtin__.object

Data descriptors inherited from PooledDBError:
__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'