Added a version attribute and new configuration parameters "failures" and "closeable".

Author: Cito

DBUtils/Docs/UsersGuide.de.txt

@@ -263,14 +263,21 @@ Parameter angeben müssen:
   erzeugt, oder ein DB-API-2-Datenbankadapter-Modul
 
 * ``maxusage``: Obergrenze dafür, wie oft eine einzelne Verbindung
-  wiederverwendet werden darf (der Standardwert ``0`` oder ``False``
+  wiederverwendet werden darf (der Standardwert ``0`` oder ``None``
   bedeutet unbegrenzte Wiederverwendung)
 
   Sobald diese Obergrenze erreicht wird, wird die Verbindung zurückgesetzt.
 
 * ``setsession``: eine optionale Liste von SQL-Befehlen zur Initialisierung
   der Datenbanksitzung, z.B. ``["set datestyle to german", ...]``
 
+* ``failures``: eine optionale Exception-Klasse oder ein Tupel von Exceptions
+  bei denen die Ausfallsicherung zum Tragen kommen soll, falls die Vorgabe
+  (OperationalError, InternalError) nicht geeignet sein sollte
+
+* ``closeable``: wenn dies auf einen wahren Wert gesetzt wird, dann wird das
+  Schließen von Verbindungen erlaubt, normalerweise wird es jedoch ignoriert
+
 * Die als ``creator`` angegebene Funktion oder die Funktion ``connect``
   des DB-API-2-Datenbankadapter-Moduls erhalten alle weiteren Parameter,
   wie ``host``, ``database``, ``user``, ``password`` usw. Sie können einige
@@ -298,8 +305,8 @@ Wenn Sie eine solche persistente Verbindung mit ``db.close()`` schließen,
 wird dies stillschweigend ignoriert, denn sie würde beim nächsten Zugriff
 sowieso wieder geöffnet, und das wäre nicht im Sinne persistenter Verbindungen.
 Stattdessen wird die Verbindung automatisch dann geschlossen, wenn der Thread
-endet. Sie können dieses Verhalten ändern, indem Sie ``persist._closeable``
-auf ``True`` setzen.
+endet. Sie können dieses Verhalten ändern, indem Sie den Parameter namens
+``closeable`` setzen.
 
 PooledDB
 --------
@@ -330,12 +337,12 @@ Parameter angeben müssen:
   bedeutet unbegrenzte Anzahl von Datenbankverbindungen)
 
 * ``blocking``: bestimmt das Verhalten, wenn diese Obergrenze überschritten
-  wird (der Standardwert ``0`` oder ``False`` bedeutet, dass eine Fehlermeldung
-  ausgegeben wird, andernfalls wird blockiert und gewartet, bis die Anzahl
-  an Datenbankverbindungen wieder abnimmt)
+  wird (der Standardwert ``0`` oder ein nicht wahrer Wert bedeutet, dass eine
+  Fehlermeldung ausgegeben wird, andernfalls wird blockiert und gewartet,
+  bis die Anzahl an Datenbankverbindungen wieder abnimmt)
 
 * ``maxusage``: Obergrenze dafür, wie oft eine einzelne Verbindung
-  wiederverwendet werden darf (der Standardwert ``0`` oder ``False``
+  wiederverwendet werden darf (der Standardwert ``0`` oder ``None``
   bedeutet unbegrenzte Wiederverwendung)
 
   Sobald diese Obergrenze erreicht wird, wird die Verbindung automatisch
@@ -344,6 +351,10 @@ Parameter angeben müssen:
 * ``setsession``: eine optionale Liste von SQL-Befehlen zur Initialisierung
   der Datenbanksitzung, z.B. ``["set datestyle to german", ...]``
 
+* ``failures``: eine optionale Exception-Klasse oder ein Tupel von Exceptions
+  bei denen die Ausfallsicherung zum Tragen kommen soll, falls die Vorgabe
+  (OperationalError, InternalError) nicht geeignet sein sollte
+
 * Die als ``creator`` angegebene Funktion oder die Funktion ``connect``
   des DB-API-2-Datenbankadapter-Moduls erhalten alle weiteren Parameter,
   wie ``host``, ``database``, ``user``, ``password`` usw. Sie können einige

DBUtils/Docs/UsersGuide.txt

@@ -243,13 +243,20 @@ of ``PersistentDB``, passing the following parameters:
   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 ``False`` means unlimited reuse)
+  (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
+
+* ``closeable``: if this is set to true, then closing connections will
+  be allowed, but by default this will be silently ignored
+
 * 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
@@ -276,7 +283,7 @@ 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 ``persist._closeable`` to ``True``.
+You can change this behavior be setting the ``closeable`` parameter.
 
 PooledDB
 --------
@@ -303,18 +310,22 @@ following parameters:
   (the default value of ``0`` means any number of connections)
 
 * ``blocking``: determines behavior when exceeding the maximum
-  (the default of ``0`` or ``False`` means report an error; otherwise
-  block and wait until the number of connections decreases)
+  (the default of ``0`` or any false value means report an error;
+  otherwise block and wait until the number of connections decreases)
 
 * ``maxusage``: maximum number of reuses of a single connection
-  (the default of ``0`` or ``False`` means unlimited reuse)
+  (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", ...]``
 
+* ``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
+
 * 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

DBUtils/Examples/DBUtilsExample.py

@@ -32,6 +32,7 @@ def configFilename(self):
     primary key(name, seminar),
     foreign key (seminar) references seminars(id) on delete cascade)''')
 
+
 class DBUtilsExample(ExamplePage):
 	"""Example page for the DBUtils package."""
 

DBUtils/PersistentDB.py

@@ -32,7 +32,7 @@
 	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 False means unlimited reuse)
+		(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", ...].
@@ -63,7 +63,7 @@
 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 persist._closeable to True.
+You can change this behavior be setting the closeable parameter.
 
 
 Requirements:
@@ -111,23 +111,28 @@ class PersistentDB:
 
 	"""
 
+	version = __version__
+
 	def __init__(self, creator,
-		maxusage=0, setsession=None, *args, **kwargs):
+		maxusage=0, setsession=None, failures=None, closeable=0,
+		*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 False means unlimited)
+			(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
+		closeable: if this is set to true, then closing connections will
+			be allowed, but by default this will be silently ignored
 		args, kwargs: the parameters that shall be passed to the creator
 			function or the connection constructor of the DB-API 2 module
 
-		Set the _closeable attribute to True or 1 to allow closing
-		connections. By default, this will be silently ignored.
-
 		"""
 		try:
 			threadsafety = creator.threadsafety
@@ -141,14 +146,17 @@ def __init__(self, creator,
 		self._creator = creator
 		self._maxusage = maxusage
 		self._setsession = setsession
+		self._failures = failures
+		self._closeable = closeable
 		self._args, self._kwargs = args, kwargs
-		self._closeable = 0
 		self.thread = local()
 
 	def steady_connection(self):
 		"""Get a steady, non-persistent DB-API 2 connection."""
 		return connect(self._creator,
-			self._maxusage, self._setsession, *self._args, **self._kwargs)
+			self._maxusage, self._setsession,
+			self._failures, self._closeable,
+			*self._args, **self._kwargs)
 
 	def connection(self, shareable=0):
 		"""Get a steady, persistent DB-API 2 connection.
@@ -164,7 +172,6 @@ def connection(self, shareable=0):
 			con = self.steady_connection()
 			if not con.threadsafety():
 				raise NotSupportedError("Database module is not thread-safe.")
-			con._closeable = self._closeable
 			self.thread.connection = con
 		return con
 

DBUtils/PersistentPg.py

@@ -32,7 +32,7 @@
 by creating an instance of PersistentPg, passing the following parameters:
 
 	maxusage: the maximum number of reuses of a single connection
-		(the default of 0 or False means unlimited reuse)
+		(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
@@ -61,7 +61,7 @@
 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 persist._closeable to True.
+You can change this behavior be setting the closeable parameter.
 
 
 Requirements:
@@ -104,40 +104,42 @@ class PersistentPg:
 
 	"""
 
-	def __init__(self, maxusage=0, setsession=None, *args, **kwargs):
+	version = __version__
+
+	def __init__(self, maxusage=0, setsession=None, closeable=0,
+			*args, **kwargs):
 		"""Set up the persistent PostgreSQL connection generator.
 
 		maxusage: maximum number of reuses of a single connection
-			(0 or False means unlimited reuse)
+			(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 ..."]
+		closeable: if this is set to true, then closing connections will
+			be allowed, but by default this will be silently ignored
 		args, kwargs: the parameters that shall be used to establish
 			the PostgreSQL connections using class PyGreSQL pg.DB()
 
-		Set the _closeable attribute to True or 1 to allow closing
-		connections. By default, this will be silently ignored.
-
 		"""
 		self._maxusage = maxusage
 		self._setsession = setsession
+		self._closeable = closeable
 		self._args, self._kwargs = args, kwargs
-		self._closeable = 0
 		self.thread = local()
 
 	def steady_connection(self):
 		"""Get a steady, non-persistent PyGreSQL connection."""
 		return SteadyPgConnection(
-			self._maxusage, self._setsession, *self._args, **self._kwargs)
+			self._maxusage, self._setsession, self._closeable,
+			*self._args, **self._kwargs)
 
 	def connection(self):
 		"""Get a steady, persistent PyGreSQL connection."""
 		try:
 			con = self.thread.connection
 		except AttributeError:
 			con = self.steady_connection()
-			con._closeable = self._closeable
 			self.thread.connection = con
 		return con
 

DBUtils/PooledDB.py

@@ -40,10 +40,10 @@
 	maxconnections: maximum number of connections generally allowed
 		(the default value of 0 means any number of connections)
 	blocking: determines behavior when exceeding the maximum
-		(the default of 0 or False means report an error; otherwise
+		(the default of 0 or false means report an error; otherwise
 		block and wait until the number of connections decreases)
 	maxusage: maximum number of reuses of a single connection
-		(the default of 0 or False means unlimited reuse)
+		(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
@@ -144,10 +144,12 @@ class PooledDB:
 
 	"""
 
+	version = __version__
+
 	def __init__(self, creator,
 		mincached=0, maxcached=0,
 		maxshared=0, maxconnections=0, blocking=0,
-		maxusage=0, setsession=None,
+		maxusage=0, setsession=None, failures=None,
 		*args, **kwargs):
 		"""Set up the DB-API 2 connection pool.
 
@@ -164,14 +166,17 @@ def __init__(self, creator,
 		maxconnections: maximum number of connections generally allowed
 			(0 means an arbitrary number of connections)
 		blocking: determines behavior when exceeding the maximum
-			(0 or False means report an error; otherwise
+			(0 or any false value means report an error; otherwise
 			block and wait until the number of connections decreases)
 		maxusage: maximum number of reuses of a single connection
-			(0 or False means unlimited reuse)
+			(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 ..."]
+		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
 		args, kwargs: the parameters that shall be passed to the creator
 			function or the connection constructor of the DB-API 2 module
 
@@ -189,6 +194,7 @@ def __init__(self, creator,
 		self._args, self._kwargs = args, kwargs
 		self._maxusage = maxusage
 		self._setsession = setsession
+		self._failures = failures
 		if maxcached:
 			if maxcached < mincached:
 				maxcached = mincached
@@ -221,7 +227,8 @@ def wait():
 	def steady_connection(self):
 		"""Get a steady, unpooled DB-API 2 connection."""
 		return connect(self._creator,
-			self._maxusage, self._setsession, *self._args, **self._kwargs)
+			self._maxusage, self._setsession, self._failures, 1,
+				*self._args, **self._kwargs)
 
 	def connection(self, shareable=1):
 		""""Get a steady, cached DB-API 2 connection from the pool.

DBUtils/PooledPg.py

@@ -35,10 +35,10 @@
 	maxconnections: maximum number of connections generally allowed
 		(the default value of 0 means any number of connections)
 	blocking: determines behavior when exceeding the maximum
-		(the default of 0 or False means report an error; otherwise
+		(the default of 0 or false means report an error; otherwise
 		block and wait until the number of connections decreases)
 	maxusage: maximum number of reuses of a single connection
-		(the default of 0 or False means unlimited reuse)
+		(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
@@ -125,6 +125,8 @@ class PooledPg:
 
 	"""
 
+	version = __version__
+
 	def __init__(self,
 		mincached=0, maxcached=0,
 		maxconnections=0, blocking=0,
@@ -139,10 +141,10 @@ def __init__(self,
 		maxconnections: maximum number of connections generally allowed
 			(0 means an arbitrary number of connections)
 		blocking: determines behavior when exceeding the maximum
-			(0 or False means report an error; otherwise
+			(0 or any false value means report an error; otherwise
 			block and wait until the number of connections decreases)
 		maxusage: maximum number of reuses of a single connection
-			(0 or False means unlimited reuse)
+			(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
@@ -172,7 +174,7 @@ def __init__(self,
 
 	def steady_connection(self):
 		"""Get a steady, unpooled PostgreSQL connection."""
-		return SteadyPgConnection(self._maxusage, self._setsession,
+		return SteadyPgConnection(self._maxusage, self._setsession, 1,
 			*self._args, **self._kwargs)
 
 	def connection(self):

DBUtils/SimplePooledDB.py

@@ -121,6 +121,8 @@ class PooledDB:
 
 	"""
 
+	version = __version__
+
 	def __init__(self, dbapi, maxconnections, *args, **kwargs):
 		"""Set up the database connection pool.