Minor improvements, some additions to the documentation.

Author: Cito

DBUtils/Docs/UsersGuide.de.html

@@ -357,21 +357,22 @@ <h2><a id="id2" name="id2">PooledDB</a></h2>
 erzeugt, oder ein DB-API-2-Datenbankadapter-Modul</p>
 </li>
 <li><p class="first"><tt class="docutils literal"><span class="pre">mincached</span></tt> : die anfängliche Anzahl inaktiver Verbindungen, die auf
-Vorrat gehalten werden sollen (der Standardwert <tt class="docutils literal"><span class="pre">0</span></tt> bedeutet, dass
-beim Start keine Verbindungen geöffnet werden)</p>
+Vorrat gehalten werden sollen (der Standardwert <tt class="docutils literal"><span class="pre">0</span></tt> bedeutet, dass beim
+Start keine Verbindungen geöffnet werden)</p>
 </li>
 <li><p class="first"><tt class="docutils literal"><span class="pre">maxcached</span></tt>: Obergrenze für die Anzahl inaktiver Verbindungen, die auf
-Vorrat gehalten werden sollen (der Standardwert <tt class="docutils literal"><span class="pre">0</span></tt> bedeutet unbegrenzte
-Größe des Vorratsspeichers)</p>
+Vorrat gehalten werden sollen (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 Größe des Vorratsspeichers)</p>
 </li>
 <li><p class="first"><tt class="docutils literal"><span class="pre">maxshared</span></tt>: Obergrenze für die Anzahl gemeinsam genutzer Verbindungen
-(der Standardwert <tt class="docutils literal"><span class="pre">0</span></tt> bedeutet, dass alle Verbindungen dediziert sind)</p>
+(der Standardwert <tt class="docutils literal"><span class="pre">0</span></tt> oder <tt class="docutils literal"><span class="pre">None</span></tt> bedeutet, dass alle Verbindungen
+dediziert sind)</p>
 <p>Wenn diese Obergrenze erreicht wird, werden Verbindungen wiederverwendet,
 wenn diese als wiederverwendbar angefordert werden.</p>
 </li>
 <li><p class="first"><tt class="docutils literal"><span class="pre">maxconnections</span></tt>: Obergrenze für die Anzahl an Datenbankverbindungen,
 die insgesamt überhaupt erlaubt werden sollen (der Standardwert <tt class="docutils literal"><span class="pre">0</span></tt>
-bedeutet unbegrenzte Anzahl von Datenbankverbindungen)</p>
+oder <tt class="docutils literal"><span class="pre">None</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 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
@@ -478,6 +479,17 @@ <h1><a id="anmerkungen" name="anmerkungen">Anmerkungen</a></h1>
 ihre eigenen Mechanismen zum Pooling von Datenbankverbindungen eingebaut.
 Tatsächlich hat <a class="reference" href="http://www.sqlobject.org/2/">SQLObject 2</a> (<a class="reference" href="http://www.sqlobject.org/sqlapi/">SQL-API</a>) das Pooling in eine separate Schicht
 ausgelagert, in der Code von DBUtils verwendet wird.</p>
+<p>Wenn Sie eine Lösung verwenden wie den Apache-Webserver mit <a class="reference" href="http://www.modpython.org">mod_python</a>
+oder <a class="reference" href="http://code.google.com/p/modwsgi/">mod_wsgi</a>, dann sollten Sie bedenken, dass Ihr Python-Code normalerweise
+im Kontext der Kindprozesse des Webservers läuft. Wenn Sie also das
+<tt class="docutils literal"><span class="pre">PooledDB</span></tt>-Modul einsetzen, und mehrere dieser Kindprozesse laufen, dann
+werden Sie ebensoviele Pools mit Datenbankverbindungen erhalten. Wenn diese
+Prozesse viele Threads laufen lassen,  dann mag dies eine sinnvoller Ansatz
+sein, wenn aber diese Prozesse nicht mehr als einen Worker-Thread starten,
+wie im Fall des Multi-Processing Moduls &quot;prefork&quot; für den Apache-Webserver,
+dann sollten Sie auf eine Middleware für das Connection-Pooling zurückgreifen,
+die Multi-Processing unterstützt, wie zum Beispiel <a class="reference" href="http://pgpool.projects.postgresql.org">pgpool</a> oder <a class="reference" href="http://pgbouncer.projects.postgresql.org">pgbouncer</a>
+für die PostgreSQL-Datenbank.</p>
 </div>
 <div class="section">
 <h1><a id="zukunft" name="zukunft">Zukunft</a></h1>
@@ -514,12 +526,14 @@ <h1><a id="links" name="links">Links</a></h1>
 <ul class="simple">
 <li><a class="reference" href="http://www.webwareforpython.org/DBUtils">DBUtils</a></li>
 <li><a class="reference" href="http://www.python.org">Python</a></li>
-<li><a class="reference" href="http://www.webwareforpython.org">Webware for Python</a> framework</li>
+<li><a class="reference" href="http://www.webwareforpython.org">Webware for Python</a> Framework</li>
 <li>Python <a class="reference" href="http://www.python.org/dev/peps/pep-0249/">DB-API 2</a></li>
-<li><a class="reference" href="http://www.postgresql.org">PostgreSQL</a> database</li>
-<li><a class="reference" href="http://www.pygresql.org">PyGreSQL</a> adapter</li>
-<li><a class="reference" href="http://www.sqlobject.org">SQLObject</a> object-relational mapper</li>
-<li><a class="reference" href="http://www.sqlalchemy.org">SQLAlchemy</a> object-relational mapper</li>
+<li><a class="reference" href="http://www.postgresql.org">PostgreSQL</a> Datenbank</li>
+<li><a class="reference" href="http://www.pygresql.org">PyGreSQL</a> Python-Adapter for PostgreSQL</li>
+<li><a class="reference" href="http://pgpool.projects.postgresql.org">pgpool</a> Middleware für Connection-Pooling mit PostgreSQL</li>
+<li><a class="reference" href="http://pgbouncer.projects.postgresql.org">pgbouncer</a> Middleware für Connection-Pooling mit PostgreSQL</li>
+<li><a class="reference" href="http://www.sqlobject.org">SQLObject</a> Objekt-relationaler Mapper</li>
+<li><a class="reference" href="http://www.sqlalchemy.org">SQLAlchemy</a> Objekt-relationaler Mapper</li>
 </ul>
 </div>
 <div class="section">
@@ -533,7 +547,8 @@ <h1><a id="autoren" name="autoren">Autoren</a></h1>
 <tr class="field"><th class="field-name">Beiträge:</th><td class="field-body">DBUtils benutzt Code, Anmerkungen und Vorschläge von
 Ian Bicking, Chuck Esterbrook (Webware for Python), Dan Green (DBTools),
 Jay Love, Michael Palmer, Tom Schwaller, Geoffrey Talvola,
-Warren Smith (DbConnectionPool) and Ezio Vernacotola.</td>
+Warren Smith (DbConnectionPool), Ezio Vernacotola,
+Jehiah Czebotar, Matthew Harriger und Gregory Piñero.</td>
 </tr>
 </tbody>
 </table>

DBUtils/Docs/UsersGuide.de.txt

@@ -319,22 +319,23 @@ Parameter angeben müssen:
   erzeugt, oder ein DB-API-2-Datenbankadapter-Modul
 
 * ``mincached`` : die anfängliche Anzahl inaktiver Verbindungen, die auf
-  Vorrat gehalten werden sollen (der Standardwert ``0`` bedeutet, dass
-  beim Start keine Verbindungen geöffnet werden)
+  Vorrat gehalten werden sollen (der Standardwert ``0`` bedeutet, dass beim
+  Start keine Verbindungen geöffnet werden)
 
 * ``maxcached``: Obergrenze für die Anzahl inaktiver Verbindungen, die auf
-  Vorrat gehalten werden sollen (der Standardwert ``0`` bedeutet unbegrenzte
-  Größe des Vorratsspeichers)
+  Vorrat gehalten werden sollen (der Standardwert ``0`` oder ``None`` bedeutet
+  unbegrenzte Größe des Vorratsspeichers)
 
 * ``maxshared``: Obergrenze für die Anzahl gemeinsam genutzer Verbindungen
-  (der Standardwert ``0`` bedeutet, dass alle Verbindungen dediziert sind)
+  (der Standardwert ``0`` oder ``None`` bedeutet, dass alle Verbindungen
+  dediziert sind)
 
   Wenn diese Obergrenze erreicht wird, werden Verbindungen wiederverwendet,
   wenn diese als wiederverwendbar angefordert werden.
 
 * ``maxconnections``: Obergrenze für die Anzahl an Datenbankverbindungen,
   die insgesamt überhaupt erlaubt werden sollen (der Standardwert ``0``
-  bedeutet unbegrenzte Anzahl von Datenbankverbindungen)
+  oder ``None`` bedeutet unbegrenzte Anzahl von Datenbankverbindungen)
 
 * ``blocking``: bestimmt das Verhalten bei Überschreitung dieser Obergrenze
 
@@ -446,6 +447,18 @@ ihre eigenen Mechanismen zum Pooling von Datenbankverbindungen eingebaut.
 Tatsächlich hat `SQLObject 2`_ (SQL-API_) das Pooling in eine separate Schicht
 ausgelagert, in der Code von DBUtils verwendet wird.
 
+Wenn Sie eine Lösung verwenden wie den Apache-Webserver mit mod_python_
+oder mod_wsgi_, dann sollten Sie bedenken, dass Ihr Python-Code normalerweise
+im Kontext der Kindprozesse des Webservers läuft. Wenn Sie also das
+``PooledDB``-Modul einsetzen, und mehrere dieser Kindprozesse laufen, dann
+werden Sie ebensoviele Pools mit Datenbankverbindungen erhalten. Wenn diese
+Prozesse viele Threads laufen lassen,  dann mag dies eine sinnvoller Ansatz
+sein, wenn aber diese Prozesse nicht mehr als einen Worker-Thread starten,
+wie im Fall des Multi-Processing Moduls "prefork" für den Apache-Webserver,
+dann sollten Sie auf eine Middleware für das Connection-Pooling zurückgreifen,
+die Multi-Processing unterstützt, wie zum Beispiel pgpool_ oder pgbouncer_
+für die PostgreSQL-Datenbank.
+
 
 Zukunft
 =======
@@ -484,12 +497,14 @@ Einige Links zu verwandter und alternativer Software:
 
 * DBUtils_
 * Python_
-* `Webware for Python`_ framework
+* `Webware for Python`_ Framework
 * Python `DB-API 2`_
-* PostgreSQL_ database
-* PyGreSQL_ adapter
-* SQLObject_ object-relational mapper
-* SQLAlchemy_ object-relational mapper
+* PostgreSQL_ Datenbank
+* PyGreSQL_ Python-Adapter for PostgreSQL
+* pgpool_ Middleware für Connection-Pooling mit PostgreSQL
+* pgbouncer_ Middleware für Connection-Pooling mit PostgreSQL
+* SQLObject_ Objekt-relationaler Mapper
+* SQLAlchemy_ Objekt-relationaler Mapper
 
 .. _DBUtils: http://www.webwareforpython.org/DBUtils
 .. _Python: http://www.python.org
@@ -503,6 +518,11 @@ Einige Links zu verwandter und alternativer Software:
 .. _SQLObject 2: http://www.sqlobject.org/2/
 .. _SQL-API: http://www.sqlobject.org/sqlapi/
 .. _SQLAlchemy: http://www.sqlalchemy.org
+.. _Apache: http://httpd.apache.org
+.. _mod_python: http://www.modpython.org
+.. _mod_wsgi: http://code.google.com/p/modwsgi/
+.. _pgpool: http://pgpool.projects.postgresql.org
+.. _pgbouncer: http://pgbouncer.projects.postgresql.org
 
 
 Autoren
@@ -513,7 +533,8 @@ Autoren
 :Beiträge: DBUtils benutzt Code, Anmerkungen und Vorschläge von
   Ian Bicking, Chuck Esterbrook (Webware for Python), Dan Green (DBTools),
   Jay Love, Michael Palmer, Tom Schwaller, Geoffrey Talvola,
-  Warren Smith (DbConnectionPool) and Ezio Vernacotola.
+  Warren Smith (DbConnectionPool), Ezio Vernacotola,
+  Jehiah Czebotar, Matthew Harriger und Gregory Piñero.
 
 
 Copyright und Lizenz

DBUtils/Docs/UsersGuide.html

@@ -337,15 +337,15 @@ <h2><a id="id2" name="id2">PooledDB</a></h2>
 (the default of <tt class="docutils literal"><span class="pre">0</span></tt> means no connections are made at startup)</p>
 </li>
 <li><p class="first"><tt class="docutils literal"><span class="pre">maxcached</span></tt>: the maximum number of idle connections in the pool
-(the default value of <tt class="docutils literal"><span class="pre">0</span></tt> means unlimited pool size)</p>
+(the default value of <tt class="docutils literal"><span class="pre">0</span></tt> or <tt class="docutils literal"><span class="pre">None</span></tt> means unlimited pool size)</p>
 </li>
 <li><p class="first"><tt class="docutils literal"><span class="pre">maxshared</span></tt>: maximum number of shared connections allowed
-(the default value of <tt class="docutils literal"><span class="pre">0</span></tt> means all connections are dedicated)</p>
+(the default value of <tt class="docutils literal"><span class="pre">0</span></tt> or <tt class="docutils literal"><span class="pre">None</span></tt> means all connections are dedicated)</p>
 <p>When this maximum number is reached, connections are shared if they
 have been requested as shareable.</p>
 </li>
 <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>
+(the default value of <tt class="docutils literal"><span class="pre">0</span></tt> or <tt class="docutils literal"><span class="pre">None</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</p>
 <p>If this is set to true, block and wait until the number of
@@ -442,6 +442,17 @@ <h1><a id="notes" name="notes">Notes</a></h1>
 or <a class="reference" href="http://www.sqlalchemy.org">SQLAlchemy</a>, you won't need DBUtils, since they come with their own
 connection pools. <a class="reference" href="http://www.sqlobject.org/2/">SQLObject 2</a> (<a class="reference" href="http://www.sqlobject.org/sqlapi/">SQL-API</a>) is actually borrowing some code
 from DBUtils to split the pooling out into a separate layer.</p>
+<p>Also note that when you are using a solution like the Apache webserver
+with <a class="reference" href="http://www.modpython.org">mod_python</a> or <a class="reference" href="http://code.google.com/p/modwsgi/">mod_wsgi</a>, then your Python code will be usually run
+in the context of the webserver's child processes. So if you are using
+the <tt class="docutils literal"><span class="pre">PooledDB</span></tt> module, and several of these child processes are running,
+you will have as much database connection pools. If these processes are
+running many threads, this may still be a reasonable approach, but if these
+processes don't spawn more than one worker thread, as in the case of Apache's
+&quot;prefork&quot; multi-processing module, this approach does not make sense.
+If you're running such a configuration, you should resort to a middleware
+for connection pooling that supports multi-processing, such as <a class="reference" href="http://pgpool.projects.postgresql.org">pgpool</a>
+or <a class="reference" href="http://pgbouncer.projects.postgresql.org/">pgbouncer</a> for the PostgreSQL database.</p>
 </div>
 <div class="section">
 <h1><a id="future" name="future">Future</a></h1>
@@ -480,7 +491,9 @@ <h1><a id="links" name="links">Links</a></h1>
 <li><a class="reference" href="http://www.webwareforpython.org">Webware for Python</a> framework</li>
 <li>Python <a class="reference" href="http://www.python.org/dev/peps/pep-0249/">DB-API 2</a></li>
 <li><a class="reference" href="http://www.postgresql.org">PostgreSQL</a> database</li>
-<li><a class="reference" href="http://www.pygresql.org">PyGreSQL</a> adapter</li>
+<li><a class="reference" href="http://www.pygresql.org">PyGreSQL</a> Python adapter for PostgreSQL</li>
+<li><a class="reference" href="http://pgpool.projects.postgresql.org">pgpool</a> middleware for PostgreSQL connection pooling</li>
+<li><a class="reference" href="http://pgbouncer.projects.postgresql.org/">pgbouncer</a> lightweight PostgreSQL connection pooling</li>
 <li><a class="reference" href="http://www.sqlobject.org">SQLObject</a> object-relational mapper</li>
 <li><a class="reference" href="http://www.sqlalchemy.org">SQLAlchemy</a> object-relational mapper</li>
 </ul>
@@ -496,7 +509,8 @@ <h1><a id="credits" name="credits">Credits</a></h1>
 <tr class="field"><th class="field-name">Contributions:</th><td class="field-body">DBUtils uses code, input and suggestions made by
 Ian Bicking, Chuck Esterbrook (Webware for Python), Dan Green (DBTools),
 Jay Love, Michael Palmer, Tom Schwaller, Geoffrey Talvola,
-Warren Smith (DbConnectionPool) and Ezio Vernacotola.</td>
+Warren Smith (DbConnectionPool), Ezio Vernacotola,
+Jehiah Czebotar, Matthew Harriger and Gregory Piñero.</td>
 </tr>
 </tbody>
 </table>

DBUtils/Docs/UsersGuide.txt

@@ -298,16 +298,16 @@ following parameters:
   (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`` means unlimited pool size)
+  (the default value of ``0`` or ``None`` means unlimited pool size)
 
 * ``maxshared``: maximum number of shared connections allowed
-  (the default value of ``0`` means all connections are dedicated)
+  (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`` means any number of connections)
+  (the default value of ``0`` or ``None`` means any number of connections)
 
 * ``blocking``: determines behavior when exceeding the maximum
 
@@ -409,6 +409,18 @@ or SQLAlchemy_, you won't need DBUtils, since they come with their own
 connection pools. `SQLObject 2`_ (SQL-API_) is actually borrowing some code
 from DBUtils to split the pooling out into a separate layer.
 
+Also note that when you are using a solution like the Apache webserver
+with mod_python_ or mod_wsgi_, then your Python code will be usually run
+in the context of the webserver's child processes. So if you are using
+the ``PooledDB`` module, and several of these child processes are running,
+you will have as much database connection pools. If these processes are
+running many threads, this may still be a reasonable approach, but if these
+processes don't spawn more than one worker thread, as in the case of Apache's
+"prefork" multi-processing module, this approach does not make sense.
+If you're running such a configuration, you should resort to a middleware
+for connection pooling that supports multi-processing, such as pgpool_
+or pgbouncer_ for the PostgreSQL database.
+
 
 Future
 ======
@@ -449,7 +461,9 @@ Some links to related and alternative software:
 * `Webware for Python`_ framework
 * Python `DB-API 2`_
 * PostgreSQL_ database
-* PyGreSQL_ adapter
+* PyGreSQL_ Python adapter for PostgreSQL
+* pgpool_ middleware for PostgreSQL connection pooling
+* pgbouncer_ lightweight PostgreSQL connection pooling
 * SQLObject_ object-relational mapper
 * SQLAlchemy_ object-relational mapper
 
@@ -465,6 +479,11 @@ Some links to related and alternative software:
 .. _SQLObject 2: http://www.sqlobject.org/2/
 .. _SQL-API: http://www.sqlobject.org/sqlapi/
 .. _SQLAlchemy: http://www.sqlalchemy.org
+.. _Apache: http://httpd.apache.org
+.. _mod_python: http://www.modpython.org
+.. _mod_wsgi: http://code.google.com/p/modwsgi/
+.. _pgpool: http://pgpool.projects.postgresql.org
+.. _pgbouncer: http://pgbouncer.projects.postgresql.org/
 
 
 Credits
@@ -475,7 +494,8 @@ Credits
 :Contributions: DBUtils uses code, input and suggestions made by
   Ian Bicking, Chuck Esterbrook (Webware for Python), Dan Green (DBTools),
   Jay Love, Michael Palmer, Tom Schwaller, Geoffrey Talvola,
-  Warren Smith (DbConnectionPool) and Ezio Vernacotola.
+  Warren Smith (DbConnectionPool), Ezio Vernacotola,
+  Jehiah Czebotar, Matthew Harriger and Gregory Piñero.
 
 
 Copyright and License