Add InterfaceError to the default failures list (#36)

Author: Cito

dbutils/persistent_db.py

@@ -42,7 +42,8 @@
         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
+        if the default (OperationalError, InterfaceError, InternalError)
+        is not adequate for the used database module
     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,
@@ -155,7 +156,8 @@ def __init__(
             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
+            if the default (OperationalError, InterfaceError, InternalError)
+            is not adequate for the used database module
         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,

dbutils/pooled_db.py

@@ -57,7 +57,8 @@
         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
+        if the default (OperationalError, InterfaceError, InternalError)
+        is not adequate for the used database module
     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,
@@ -210,7 +211,8 @@ def __init__(
             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
+            if the default (OperationalError, InterfaceError, InternalError)
+            is not adequate for the used database module
         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,

dbutils/steady_db.py

@@ -117,7 +117,8 @@ def connect(
         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
+        (OperationalError, InternalError, Interface) is not adequate
+        for the used database module
     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,
@@ -258,16 +259,20 @@ def _create(self):
                 try:
                     self._failures = (
                         self._dbapi.OperationalError,
+                        self._dbapi.InterfaceError,
                         self._dbapi.InternalError)
                 except AttributeError:
                     try:
                         self._failures = (
                             self._creator.OperationalError,
+                            self._creator.InterfaceError,
                             self._creator.InternalError)
                     except AttributeError:
                         try:
                             self._failures = (
-                                con.OperationalError, con.InternalError)
+                                con.OperationalError,
+                                con.InterfaceError,
+                                con.InternalError)
                         except AttributeError:
                             raise AttributeError(
                                 "Could not determine failure exceptions"

docs/changelog.html

@@ -12,6 +12,13 @@
 <h1 class="title">Changelog for DBUtils</h1>
 
 <section id="section-1">
+<h2>3.0.1</h2>
+<p>DBUtils 3.0.1 was released on December 22, 2021.</p>
+<p>It includes <span class="docutils literal">InterfaceError</span> to the default list of exceptions
+for which the connection failover mechanism is applied.
+You can override this with the <span class="docutils literal">failures</span> parameter.</p>
+</section>
+<section id="section-2">
 <h2>3.0.0</h2>
 <p>DBUtils 3.0.0 was released on November 26, 2021.</p>
 <p>It is intended to be used with Python versions 3.6 to 3.10.</p>
@@ -20,31 +27,31 @@ <h2>3.0.0</h2>
 <li><p>Cease support for Python 2 and 3.5, minor optimizations.</p></li>
 </ul>
 </section>
-<section id="section-2">
+<section id="section-3">
 <h2>2.0.3</h2>
 <p>DBUtils 2.0.3 was released on November 26, 2021.</p>
 <p>Changes:</p>
 <ul class="simple">
 <li><p>Support Python version 3.10.</p></li>
 </ul>
 </section>
-<section id="section-3">
+<section id="section-4">
 <h2>2.0.2</h2>
 <p>DBUtils 2.0.2 was released on June 8, 2021.</p>
 <p>Changes:</p>
 <ul class="simple">
 <li><p>Allow using context managers for pooled connections.</p></li>
 </ul>
 </section>
-<section id="section-4">
+<section id="section-5">
 <h2>2.0.1</h2>
 <p>DBUtils 2.0.1 was released on April 8, 2021.</p>
 <p>Changes:</p>
 <ul class="simple">
 <li><p>Avoid &quot;name Exception is not defined&quot; when exiting.</p></li>
 </ul>
 </section>
-<section id="section-5">
+<section id="section-6">
 <h2>2.0</h2>
 <p>DBUtils 2.0 was released on September 26, 2020.</p>
 <p>It is intended to be used with Python versions 2.7 and 3.5 to 3.9.</p>
@@ -60,7 +67,7 @@ <h2>2.0</h2>
 <li><p>This changelog has been compiled from the former release notes.</p></li>
 </ul>
 </section>
-<section id="section-6">
+<section id="section-7">
 <h2>1.4</h2>
 <p>DBUtils 1.4 was released on September 26, 2020.</p>
 <p>It is intended to be used with Python versions 2.7 and 3.5 to 3.9.</p>
@@ -71,7 +78,7 @@ <h2>1.4</h2>
 inside a transaction.</p></li>
 </ul>
 </section>
-<section id="section-7">
+<section id="section-8">
 <h2>1.3</h2>
 <p>DBUtils 1.3 was released on March 3, 2018.</p>
 <p>It is intended to be used with Python versions 2.6, 2.7 and 3.4 to 3.7.</p>
@@ -80,12 +87,12 @@ <h2>1.3</h2>
 <li><p>This version now supports context handlers for connections and cursors.</p></li>
 </ul>
 </section>
-<section id="section-8">
+<section id="section-9">
 <h2>1.2</h2>
 <p>DBUtils 1.2 was released on February 5, 2017.</p>
 <p>It is intended to be used with Python versions 2.6, 2.7 and 3.0 to 3.6.</p>
 </section>
-<section id="section-9">
+<section id="section-10">
 <h2>1.1.1</h2>
 <p>DBUtils 1.1.1 was released on February 4, 2017.</p>
 <p>It is intended to be used with Python versions 2.3 to 2.7.</p>
@@ -99,7 +106,7 @@ <h2>1.1.1</h2>
 <li><p>Fixed a problem when running under Jython (reported by Vitaly Kruglikov).</p></li>
 </ul>
 </section>
-<section id="section-10">
+<section id="section-11">
 <h2>1.1</h2>
 <p>DBUtils 1.1 was released on August 14, 2011.</p>
 <p>Improvements:</p>
@@ -128,7 +135,7 @@ <h2>1.1</h2>
 <li><p>Fixed some minor issues with the <span class="docutils literal">DBUtilsExample</span> for Webware.</p></li>
 </ul>
 </section>
-<section id="section-11">
+<section id="section-12">
 <h2>1.0</h2>
 <p>DBUtils 1.0 was released on November 29, 2008.</p>
 <p>It is intended to be used with Python versions 2.2 to 2.6.</p>
@@ -161,7 +168,7 @@ <h2>1.0</h2>
 the MySQLdb module (problem reported by Gregory Pinero).</p></li>
 </ul>
 </section>
-<section id="section-12">
+<section id="section-13">
 <h2>0.9.4</h2>
 <p>DBUtils 0.9.4 was released on July 7, 2007.</p>
 <p>This release fixes a problem in the destructor code and has been supplemented
@@ -170,7 +177,7 @@ <h2>0.9.4</h2>
 in the last release, since you can now pass custom creator functions
 for database connections instead of DB-API 2 modules.</p>
 </section>
-<section id="section-13">
+<section id="section-14">
 <h2>0.9.3</h2>
 <p>DBUtils 0.9.3 was released on May 21, 2007.</p>
 <p>Changes:</p>
@@ -185,7 +192,7 @@ <h2>0.9.3</h2>
 Added Chinese translation of the User's Guide, kindly contributed by gashero.</p></li>
 </ul>
 </section>
-<section id="section-14">
+<section id="section-15">
 <h2>0.9.2</h2>
 <p>DBUtils 0.9.2 was released on September 22, 2006.</p>
 <p>It is intended to be used with Python versions 2.2 to 2.5.</p>
@@ -195,7 +202,7 @@ <h2>0.9.2</h2>
 storage engine. Accordingly, renamed <span class="docutils literal">SolidPg</span> to <span class="docutils literal">SteadyPg</span>.</p></li>
 </ul>
 </section>
-<section id="section-15">
+<section id="section-16">
 <h2>0.9.1</h2>
 <p>DBUtils 0.9.1 was released on May 8, 2006.</p>
 <p>It is intended to be used with Python versions 2.2 to 2.4.</p>
@@ -209,7 +216,7 @@ <h2>0.9.1</h2>
 <li><p>Improved the documentation and added a User's Guide.</p></li>
 </ul>
 </section>
-<section id="section-16">
+<section id="section-17">
 <h2>0.8.1 - 2005-09-13</h2>
 <p>DBUtils 0.8.1 was released on September 13, 2005.</p>
 <p>It is intended to be used with Python versions 2.0 to 2.4.</p>

docs/changelog.rst

@@ -1,6 +1,16 @@
 Changelog for DBUtils
 +++++++++++++++++++++
 
+
+3.0.1
+=====
+
+DBUtils 3.0.1 was released on December 22, 2021.
+
+It includes ``InterfaceError`` to the default list of exceptions
+for which the connection failover mechanism is applied.
+You can override this with the ``failures`` parameter.
+
 3.0.0
 =====
 

docs/main.de.html

@@ -282,9 +282,10 @@ <h3>PersistentDB (persistent_db)</h3>
 </li>
 <li><p><span class="docutils literal">setsession</span>: eine optionale Liste von SQL-Befehlen zur Initialisierung
 der Datenbanksitzung, z.B. <span class="docutils literal">[&quot;set datestyle to german&quot;, <span class="pre">...]</span></span></p></li>
-<li><p><span class="docutils literal">failures</span>: eine optionale Exception-Klasse oder ein Tupel von Exceptions
+<li><p><span class="docutils literal">failures</span>: 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</p></li>
+(OperationalError, InterfaceError, InternalError) für das verwendete
+Datenbankadapter-Modul nicht geeignet sein sollte</p></li>
 <li><p><span class="docutils literal">ping</span>: mit diesem Parameter kann eingestellt werden, wann Verbindungen
 mit der <span class="docutils literal">ping()</span>-Methode geprüft werden, falls eine solche vorhanden ist
 (<span class="docutils literal">0</span> = <span class="docutils literal">None</span> = nie, <span class="docutils literal">1</span> = Standardwert = immer wenn neu angefragt,
@@ -371,9 +372,10 @@ <h3>PooledDB (pooled_db)</h3>
 in den Verbindungspool zurückgegeben werden (<span class="docutils literal">False</span> oder <span class="docutils literal">None</span>
 um mit <span class="docutils literal">begin()</span> gestartete Transaktionen zurückzurollen, der Standardwert
 <span class="docutils literal">True</span> rollt sicherheitshalber mögliche Transaktionen immer zurück)</p></li>
-<li><p><span class="docutils literal">failures</span>: eine optionale Exception-Klasse oder ein Tupel von Exceptions
+<li><p><span class="docutils literal">failures</span>: 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</p></li>
+(OperationalError, InterfaceError, InternalError) für das verwendete
+Datenbankadapter-Modul nicht geeignet sein sollte</p></li>
 <li><p><span class="docutils literal">ping</span>: mit diesem Parameter kann eingestellt werden, wann Verbindungen
 mit der <span class="docutils literal">ping()</span>-Methode geprüft werden, falls eine solche vorhanden ist
 (<span class="docutils literal">0</span> = <span class="docutils literal">None</span> = nie, <span class="docutils literal">1</span> = Standardwert = immer wenn neu angefragt,

docs/main.de.rst

@@ -269,9 +269,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
+* ``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
+  (OperationalError, InterfaceError, InternalError) für das verwendete
+  Datenbankadapter-Modul nicht geeignet sein sollte
 
 * ``ping``: mit diesem Parameter kann eingestellt werden, wann Verbindungen
   mit der ``ping()``-Methode geprüft werden, falls eine solche vorhanden ist
@@ -378,9 +379,10 @@ Parameter angeben müssen:
   um mit ``begin()`` gestartete Transaktionen zurückzurollen, der Standardwert
   ``True`` rollt sicherheitshalber mögliche Transaktionen immer zurück)
 
-* ``failures``: eine optionale Exception-Klasse oder ein Tupel von Exceptions
+* ``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
+  (OperationalError, InterfaceError, InternalError) für das verwendete
+  Datenbankadapter-Modul nicht geeignet sein sollte
 
 * ``ping``: mit diesem Parameter kann eingestellt werden, wann Verbindungen
   mit der ``ping()``-Methode geprüft werden, falls eine solche vorhanden ist

docs/main.html

@@ -263,7 +263,8 @@ <h3>PersistentDB (persistent_db)</h3>
 prepare the session, e.g. <span class="docutils literal">[&quot;set datestyle to german&quot;, <span class="pre">...]</span></span></p></li>
 <li><p><span class="docutils literal">failures</span>: 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</p></li>
+if the default (OperationalError, InterfaceError, InternalError)
+is not adequate for the used database module</p></li>
 <li><p><span class="docutils literal">ping</span>: an optional flag controlling when connections are checked
 with the <span class="docutils literal">ping()</span> method if such a method is available
 (<span class="docutils literal">0</span> = <span class="docutils literal">None</span> = never, <span class="docutils literal">1</span> = default = whenever it is requested,
@@ -340,7 +341,8 @@ <h3>PooledDB (pooled_db)</h3>
 the default value <span class="docutils literal">True</span> always issues a rollback for safety's sake)</p></li>
 <li><p><span class="docutils literal">failures</span>: 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</p></li>
+if the default (OperationalError, InterfaceError, InternalError)
+is not adequate for the used database module</p></li>
 <li><p><span class="docutils literal">ping</span>: an optional flag controlling when connections are checked
 with the <span class="docutils literal">ping()</span> method if such a method is available
 (<span class="docutils literal">0</span> = <span class="docutils literal">None</span> = never, <span class="docutils literal">1</span> = default = whenever fetched from the pool,

docs/main.rst

@@ -250,7 +250,8 @@ of ``persistent_db``, passing the following parameters:
 
 * ``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
+  if the default (OperationalError, InterfaceError, InternalError)
+  is not adequate for the used database module
 
 * ``ping``: an optional flag controlling when connections are checked
   with the ``ping()`` method if such a method is available
@@ -347,7 +348,8 @@ following parameters:
 
 * ``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
+  if the default (OperationalError, InterfaceError, InternalError)
+  is not adequate for the used database module
 
 * ``ping``: an optional flag controlling when connections are checked
   with the ``ping()`` method if such a method is available

tests/mock_db.py

@@ -15,6 +15,10 @@ class OperationalError(DatabaseError):
     pass
 
 
+class InterfaceError(DatabaseError):
+    pass
+
+
 class InternalError(DatabaseError):
     pass
 

tests/test_steady_db.py

@@ -406,8 +406,12 @@ def test_connection_failures(self):
         db = SteadyDBconnect(dbapi, failures=dbapi.OperationalError)
         db.close()
         self.assertRaises(dbapi.InternalError, db.cursor)
-        db = SteadyDBconnect(
-            dbapi, failures=(dbapi.OperationalError, dbapi.InternalError))
+        db = SteadyDBconnect(dbapi, failures=(
+            dbapi.OperationalError, dbapi.InterfaceError))
+        db.close()
+        self.assertRaises(dbapi.InternalError, db.cursor)
+        db = SteadyDBconnect(dbapi, failures=(
+            dbapi.OperationalError, dbapi.InterfaceError, dbapi.InternalError))
         db.close()
         db.cursor()