Added alias method "dedicated_connection" for "connection(shareable=False)". Exceptions in destructors are now caught and silently ignored. These can occur when instances are not yet fully initialized or referenced objects are already destroyed.

Author: Cito

DBUtils/Docs/UsersGuide.de.html

@@ -15,8 +15,8 @@ <h1 class="title">Benutzeranleitung für DBUtils</h1>
 <col class="docinfo-content" />
 <tbody valign="top">
 <tr><th class="docinfo-name">Version:</th>
-<td>0.9.4</td></tr>
-<tr class="field"><th class="docinfo-name">Released:</th><td class="field-body">07/07/07</td>
+<td>1.0pre</td></tr>
+<tr class="field"><th class="docinfo-name">Released:</th><td class="field-body">09/25/08</td>
 </tr>
 <tr class="field"><th class="docinfo-name">Translations:</th><td class="field-body"><a class="reference" href="UsersGuide.html">English</a> German <a class="reference" href="UsersGuide.zh.html">Chinese</a></td>
 </tr>
@@ -302,13 +302,20 @@ <h2><a id="id1" name="id1">PersistentDB</a></h2>
 erzeugt, oder ein DB-API-2-Datenbankadapter-Modul</p>
 </li>
 <li><p class="first"><tt class="docutils literal"><span class="pre">maxusage</span></tt>: Obergrenze dafür, wie oft eine einzelne Verbindung
-wiederverwendet werden darf (der Standardwert <tt class="docutils literal"><span class="pre">0</span></tt> oder <tt class="docutils literal"><span class="pre">False</span></tt>
+wiederverwendet werden darf (der Standardwert <tt class="docutils literal"><span class="pre">0</span></tt> oder <tt class="docutils literal"><span class="pre">None</span></tt>
 bedeutet unbegrenzte Wiederverwendung)</p>
 <p>Sobald diese Obergrenze erreicht wird, wird die Verbindung zurückgesetzt.</p>
 </li>
 <li><p class="first"><tt class="docutils literal"><span class="pre">setsession</span></tt>: eine optionale Liste von SQL-Befehlen zur Initialisierung
 der Datenbanksitzung, z.B. <tt class="docutils literal"><span class="pre">[&quot;set</span> <span class="pre">datestyle</span> <span class="pre">to</span> <span class="pre">german&quot;,</span> <span class="pre">...]</span></tt></p>
 </li>
+<li><p class="first"><tt class="docutils literal"><span class="pre">failures</span></tt>: 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>
+<li><p class="first"><tt class="docutils literal"><span class="pre">closeable</span></tt>: wenn dies auf <tt class="docutils literal"><span class="pre">True</span></tt> gesetzt wird, dann wird das Schließen
+von Verbindungen erlaubt, normalerweise wird es jedoch ignoriert</p>
+</li>
 <li><p class="first">Die als <tt class="docutils literal"><span class="pre">creator</span></tt> angegebene Funktion oder die Funktion <tt class="docutils literal"><span class="pre">connect</span></tt>
 des DB-API-2-Datenbankadapter-Moduls erhalten alle weiteren Parameter,
 wie <tt class="docutils literal"><span class="pre">host</span></tt>, <tt class="docutils literal"><span class="pre">database</span></tt>, <tt class="docutils literal"><span class="pre">user</span></tt>, <tt class="docutils literal"><span class="pre">password</span></tt> usw. Sie können einige
@@ -336,8 +343,8 @@ <h2><a id="id1" name="id1">PersistentDB</a></h2>
 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 <tt class="docutils literal"><span class="pre">persist._closeable</span></tt>
-auf <tt class="docutils literal"><span class="pre">True</span></tt> setzen.</p>
+endet. Sie können dieses Verhalten ändern, indem Sie den Parameter namens
+<tt class="docutils literal"><span class="pre">closeable</span></tt> setzen.</p>
 </div>
 <div class="section">
 <h2><a id="id2" name="id2">PooledDB</a></h2>
@@ -366,20 +373,24 @@ <h2><a id="id2" name="id2">PooledDB</a></h2>
 die insgesamt überhaupt erlaubt werden sollen (der Standardwert <tt class="docutils literal"><span class="pre">0</span></tt>
 bedeutet unbegrenzte Anzahl von Datenbankverbindungen)</p>
 </li>
-<li><p class="first"><tt class="docutils literal"><span class="pre">blocking</span></tt>: bestimmt das Verhalten, wenn diese Obergrenze überschritten
-wird (der Standardwert <tt class="docutils literal"><span class="pre">0</span></tt> oder <tt class="docutils literal"><span class="pre">False</span></tt> bedeutet, dass eine Fehlermeldung
-ausgegeben wird, andernfalls wird blockiert und gewartet, bis die Anzahl
-an Datenbankverbindungen wieder abnimmt)</p>
+<li><p class="first"><tt class="docutils literal"><span class="pre">blocking</span></tt>: bestimmt das Verhalten bei Überschreitung dieser Obergrenze</p>
+<p>Wenn dies auf <tt class="docutils literal"><span class="pre">True</span></tt> gesetzt wird, dann wird so lange gewartet, bis die
+Anzahl an Datenbankverbindungen wieder abnimmt, normalerweise wird jedoch
+sofort eine Fehlermeldung ausgegeben.</p>
 </li>
 <li><p class="first"><tt class="docutils literal"><span class="pre">maxusage</span></tt>: Obergrenze dafür, wie oft eine einzelne Verbindung
-wiederverwendet werden darf (der Standardwert <tt class="docutils literal"><span class="pre">0</span></tt> oder <tt class="docutils literal"><span class="pre">False</span></tt>
+wiederverwendet werden darf (der Standardwert <tt class="docutils literal"><span class="pre">0</span></tt> oder <tt class="docutils literal"><span class="pre">None</span></tt>
 bedeutet unbegrenzte Wiederverwendung)</p>
 <p>Sobald diese Obergrenze erreicht wird, wird die Verbindung automatisch
 zurückgesetzt (geschlossen und wieder neu geöffnet).</p>
 </li>
 <li><p class="first"><tt class="docutils literal"><span class="pre">setsession</span></tt>: eine optionale Liste von SQL-Befehlen zur Initialisierung
 der Datenbanksitzung, z.B. <tt class="docutils literal"><span class="pre">[&quot;set</span> <span class="pre">datestyle</span> <span class="pre">to</span> <span class="pre">german&quot;,</span> <span class="pre">...]</span></tt></p>
 </li>
+<li><p class="first"><tt class="docutils literal"><span class="pre">failures</span></tt>: 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>
 <li><p class="first">Die als <tt class="docutils literal"><span class="pre">creator</span></tt> angegebene Funktion oder die Funktion <tt class="docutils literal"><span class="pre">connect</span></tt>
 des DB-API-2-Datenbankadapter-Moduls erhalten alle weiteren Parameter,
 wie <tt class="docutils literal"><span class="pre">host</span></tt>, <tt class="docutils literal"><span class="pre">database</span></tt>, <tt class="docutils literal"><span class="pre">user</span></tt>, <tt class="docutils literal"><span class="pre">password</span></tt> usw. Sie können einige
@@ -409,7 +420,11 @@ <h2><a id="id2" name="id2">PooledDB</a></h2>
 Eine dedizierte Datenbankverbindung, die garantiert nicht von anderen Threads
 mitgenutzt wird, fordern Sie wie folgt an:</p>
 <pre class="literal-block">
-db = pool.connection(0)
+db = pool.connection(shareable=False)
+</pre>
+<p>Stattdessen können Sie eine dedizierte Verbindung auch wie folgt erhalten:</p>
+<pre class="literal-block">
+db = pool.dedicated_connection()
 </pre>
 <p>Wenn Sie die Datenbankverbindung nicht mehr benötigen, sollten Sie diese sofort
 wieder mit <tt class="docutils literal"><span class="pre">db.close()</span></tt> an den Pool zurückgeben. Sie können auf die gleiche

DBUtils/Docs/UsersGuide.de.txt

@@ -385,7 +385,11 @@ gesetzt haben, und der zugrunde liegende DB-API-2-Datenbankadapter dies erlaubt.
 Eine dedizierte Datenbankverbindung, die garantiert nicht von anderen Threads
 mitgenutzt wird, fordern Sie wie folgt an::
 
-  db = pool.connection(0)
+  db = pool.connection(shareable=False)
+
+Stattdessen können Sie eine dedizierte Verbindung auch wie folgt erhalten::
+
+  db = pool.dedicated_connection()
 
 Wenn Sie die Datenbankverbindung nicht mehr benötigen, sollten Sie diese sofort
 wieder mit ``db.close()`` an den Pool zurückgeben. Sie können auf die gleiche

DBUtils/Docs/UsersGuide.html

@@ -15,8 +15,8 @@ <h1 class="title">DBUtils User's Guide</h1>
 <col class="docinfo-content" />
 <tbody valign="top">
 <tr><th class="docinfo-name">Version:</th>
-<td>0.9.4</td></tr>
-<tr class="field"><th class="docinfo-name">Released:</th><td class="field-body">07/07/07</td>
+<td>1.0pre</td></tr>
+<tr class="field"><th class="docinfo-name">Released:</th><td class="field-body">09/25/08</td>
 </tr>
 <tr class="field"><th class="docinfo-name">Translations:</th><td class="field-body">English <a class="reference" href="UsersGuide.de.html">German</a> <a class="reference" href="UsersGuide.zh.html">Chinese</a></td>
 </tr>
@@ -283,12 +283,19 @@ <h2><a id="id1" name="id1">PersistentDB</a></h2>
 connection objects or a DB-API 2 compliant database module</p>
 </li>
 <li><p class="first"><tt class="docutils literal"><span class="pre">maxusage</span></tt>: the maximum number of reuses of a single connection
-(the default of <tt class="docutils literal"><span class="pre">0</span></tt> or <tt class="docutils literal"><span class="pre">False</span></tt> means unlimited reuse)</p>
+(the default of <tt class="docutils literal"><span class="pre">0</span></tt> or <tt class="docutils literal"><span class="pre">None</span></tt> means unlimited reuse)</p>
 <p>Whenever the limit is reached, the connection will be reset.</p>
 </li>
 <li><p class="first"><tt class="docutils literal"><span class="pre">setsession</span></tt>: an optional list of SQL commands that may serve to
 prepare the session, e.g. <tt class="docutils literal"><span class="pre">[&quot;set</span> <span class="pre">datestyle</span> <span class="pre">to</span> <span class="pre">german&quot;,</span> <span class="pre">...]</span></tt></p>
 </li>
+<li><p class="first"><tt class="docutils literal"><span class="pre">failures</span></tt>: 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>
+<li><p class="first"><tt class="docutils literal"><span class="pre">closeable</span></tt>: if this is set to true, then closing connections will
+be allowed, but by default this will be silently ignored</p>
+</li>
 <li><p class="first">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
@@ -315,7 +322,7 @@ <h2><a id="id1" name="id1">PersistentDB</a></h2>
 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 <tt class="docutils literal"><span class="pre">persist._closeable</span></tt> to <tt class="docutils literal"><span class="pre">True</span></tt>.</p>
+You can change this behavior be setting the <tt class="docutils literal"><span class="pre">closeable</span></tt> parameter.</p>
 </div>
 <div class="section">
 <h2><a id="id2" name="id2">PooledDB</a></h2>
@@ -340,18 +347,22 @@ <h2><a id="id2" name="id2">PooledDB</a></h2>
 <li><p class="first"><tt class="docutils literal"><span class="pre">maxconnections</span></tt>: maximum number of connections generally allowed
 (the default value of <tt class="docutils literal"><span class="pre">0</span></tt> means any number of connections)</p>
 </li>
-<li><p class="first"><tt class="docutils literal"><span class="pre">blocking</span></tt>: determines behavior when exceeding the maximum
-(the default of <tt class="docutils literal"><span class="pre">0</span></tt> or <tt class="docutils literal"><span class="pre">False</span></tt> means report an error; otherwise
-block and wait until the number of connections decreases)</p>
+<li><p class="first"><tt class="docutils literal"><span class="pre">blocking</span></tt>: determines behavior when exceeding the maximum</p>
+<p>If this is set to true, block and wait until the number of
+connections decreases, but by default an error will be reported.</p>
 </li>
 <li><p class="first"><tt class="docutils literal"><span class="pre">maxusage</span></tt>: maximum number of reuses of a single connection
-(the default of <tt class="docutils literal"><span class="pre">0</span></tt> or <tt class="docutils literal"><span class="pre">False</span></tt> means unlimited reuse)</p>
+(the default of <tt class="docutils literal"><span class="pre">0</span></tt> or <tt class="docutils literal"><span class="pre">None</span></tt> means unlimited reuse)</p>
 <p>When this maximum usage number of the connection is reached,
 the connection is automatically reset (closed and reopened).</p>
 </li>
 <li><p class="first"><tt class="docutils literal"><span class="pre">setsession</span></tt>: an optional list of SQL commands that may serve to
 prepare the session, e.g. <tt class="docutils literal"><span class="pre">[&quot;set</span> <span class="pre">datestyle</span> <span class="pre">to</span> <span class="pre">german&quot;,</span> <span class="pre">...]</span></tt></p>
 </li>
+<li><p class="first"><tt class="docutils literal"><span class="pre">failures</span></tt>: 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>
 <li><p class="first">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
@@ -378,7 +389,11 @@ <h2><a id="id2" name="id2">PooledDB</a></h2>
 if you set a non-zero <tt class="docutils literal"><span class="pre">maxshared</span></tt> parameter and the DB-API 2 module allows
 this. If you want to have a dedicated connection, use:</p>
 <pre class="literal-block">
-db = pool.connection(0)
+db = pool.connection(shareable=False)
+</pre>
+<p>Instead of this, you can also get a dedicated connection as follows:</p>
+<pre class="literal-block">
+db = pool.dedicated_connection()
 </pre>
 <p>If you don't need it any more, you should immediately return it to the
 pool with <tt class="docutils literal"><span class="pre">db.close()</span></tt>. You can get another connection in the same way.</p>

DBUtils/Docs/UsersGuide.txt

@@ -353,7 +353,11 @@ 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(0)
+  db = pool.connection(shareable=False)
+
+Instead of this, you can also get a dedicated connection as follows::
+
+  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.

DBUtils/Docs/UsersGuide.zh.html

@@ -15,8 +15,8 @@ <h1 class="title">DBUtils 用户指南</h1>
 <col class="docinfo-content" />
 <tbody valign="top">
 <tr><th class="docinfo-name">版本:</th>
-<td>0.9.4</td></tr>
-<tr class="field"><th class="docinfo-name">发行版:</th><td class="field-body">07/07/07</td>
+<td>1.0pre</td></tr>
+<tr class="field"><th class="docinfo-name">发行版:</th><td class="field-body">09/25/08</td>
 </tr>
 <tr class="field"><th class="docinfo-name">翻译:</th><td class="field-body"><a class="reference" href="UsersGuide.html">English</a> <a class="reference" href="UsersGuide.de.html">German</a> Chinese</td>
 </tr>
@@ -242,7 +242,7 @@ <h2><a id="id12" name="id12">PooledDB</a></h2>
 <p>你可以使用这些连接有如原始的DB-API 2一样。而实际使用的是``SteadyDB``版本的强硬连接。</p>
 <p>请注意连接可以与其他线程共享，只要你设置 <tt class="docutils literal"><span class="pre">maxshared</span></tt> 参数为非零，并且DB-API 2模块也允许。如果你想要使用专用连接则使用:</p>
 <pre class="literal-block">
-db = pool.connection(0)
+db = pool.connection(shareable=False)
 </pre>
 <p>如果你不再需要这个连接了，则可以返回给连接池使用 <tt class="docutils literal"><span class="pre">db.close()</span></tt> 。你也可以使用相同的方法获取另一个连接。</p>
 <p><em>警告：</em> 在一个多线程环境，不要使用下面的方法:</p>

DBUtils/Docs/UsersGuide.zh.txt

@@ -222,7 +222,7 @@ PooledDB
 
 请注意连接可以与其他线程共享，只要你设置 ``maxshared`` 参数为非零，并且DB-API 2模块也允许。如果你想要使用专用连接则使用::
 
-    db = pool.connection(0)
+    db = pool.connection(shareable=False)
 
 如果你不再需要这个连接了，则可以返回给连接池使用 ``db.close()`` 。你也可以使用相同的方法获取另一个连接。
 

DBUtils/Examples/DBUtilsExample.py

@@ -125,14 +125,17 @@ def connection(self, shareable=True):
 				error = 'Cannot connect to the database.'
 		self.outputMsg(error, True)
 
+	def dedicated_connection(self):
+		return self.connection(False)
+
 	def sqlEncode(self, s):
 		if s is None:
 			return 'null'
 		s = s.replace('\\', '\\\\').replace('\'', '\\\'')
 		return "'%s'" % s
 
 	def createTables(self):
-		db = self.connection(False)
+		db = self.dedicated_connection()
 		if not db:
 			return
 		for table in tables:
@@ -160,7 +163,7 @@ def listSeminars(self):
 				id = [id]
 			cmd = ','.join(map(self.sqlEncode, id))
 			cmd = 'delete from seminars where id in (%s)' % cmd
-			db = self.connection(False)
+			db = self.dedicated_connection()
 			if not db:
 				return
 			try:
@@ -236,7 +239,7 @@ def listAttendees(self):
 			for i, n in places.items():
 				cmds.append("update seminars set places_left=places_left+%d "
 				"where id=%s" % (n, self.sqlEncode(i)))
-			db = self.connection(False)
+			db = self.dedicated_connection()
 			if not db:
 				return
 			try:
@@ -320,7 +323,7 @@ def newSeminar(self):
 			values[2] = None
 		if not values[3]:
 			values[3] = None
-		db = self.connection(0)
+		db = self.dedicated_connection()
 		if not db:
 			return
 		cmd = ('insert into seminars values (%s,%s,%s,%s)'
@@ -388,7 +391,7 @@ def newAttendee(self):
 		if not values[0] or not values[1]:
 			self.outputMsg('You must enter a name and a seminar!')
 			return
-		db = self.connection(0)
+		db = self.dedicated_connection()
 		if not db:
 			return
 		try:

DBUtils/PersistentDB.py

@@ -176,6 +176,10 @@ def connection(self, shareable=False):
 			self.thread.connection = con
 		return con
 
+	def dedicated_connection(self):
+		"""Alias for connection(shareable=False)."""
+		return self.connection()
+
 
 try: # import a class for representing thread-local objects
 	from threading import local