Add section on advanced usage to docs (#45)

Author: Cito

docs/main.de.html

@@ -44,12 +44,13 @@ <h1 class="title">Benutzeranleitung für DBUtils</h1>
 <li><p><a class="reference internal" href="#pooleddb-pooled-db-1" id="toc-entry-15">PooledDB (pooled_db)</a></p></li>
 </ul>
 </li>
-<li><p><a class="reference internal" href="#anmerkungen" id="toc-entry-16">Anmerkungen</a></p></li>
-<li><p><a class="reference internal" href="#zukunft" id="toc-entry-17">Zukunft</a></p></li>
-<li><p><a class="reference internal" href="#fehlermeldungen-und-feedback" id="toc-entry-18">Fehlermeldungen und Feedback</a></p></li>
-<li><p><a class="reference internal" href="#links" id="toc-entry-19">Links</a></p></li>
-<li><p><a class="reference internal" href="#autoren" id="toc-entry-20">Autoren</a></p></li>
-<li><p><a class="reference internal" href="#copyright-und-lizenz" id="toc-entry-21">Copyright und Lizenz</a></p></li>
+<li><p><a class="reference internal" href="#besonderheiten-bei-der-benutzung" id="toc-entry-16">Besonderheiten bei der Benutzung</a></p></li>
+<li><p><a class="reference internal" href="#anmerkungen" id="toc-entry-17">Anmerkungen</a></p></li>
+<li><p><a class="reference internal" href="#zukunft" id="toc-entry-18">Zukunft</a></p></li>
+<li><p><a class="reference internal" href="#fehlermeldungen-und-feedback" id="toc-entry-19">Fehlermeldungen und Feedback</a></p></li>
+<li><p><a class="reference internal" href="#links" id="toc-entry-20">Links</a></p></li>
+<li><p><a class="reference internal" href="#autoren" id="toc-entry-21">Autoren</a></p></li>
+<li><p><a class="reference internal" href="#copyright-und-lizenz" id="toc-entry-22">Copyright und Lizenz</a></p></li>
 </ul>
 </nav>
 <section id="zusammenfassung">
@@ -435,6 +436,27 @@ <h3>PooledDB (pooled_db)</h3>
 wieder an den Verbindungspool zurückgegeben wird.</p>
 </section>
 </section>
+<section id="besonderheiten-bei-der-benutzung">
+<h2>Besonderheiten bei der Benutzung</h2>
+<p>Manchmal möchte man Datenbankverbindung besonders vorbereiten, bevor sie
+von DBUtils verwendet werden, und dies ist nicht immer durch Verwendung
+der passenden Parameter möglich. Zum Beispiel kann es <span class="docutils literal">pyodb</span> erfordern,
+dass man die Methode <span class="docutils literal">setencoding()</span> der Datenbankverbindung aufruft.
+Sie können dies erreichen, indem Sie eine modifizierte Version der
+Funktion <span class="docutils literal">connect()</span> verwenden und diese als <span class="docutils literal">creator</span> (dem ersten
+Argument) an <span class="docutils literal">PersistentDB</span> oder <span class="docutils literal">PooledDB</span> übergeben, etwa so:</p>
+<pre class="literal-block">from pyodbc import connect
+from dbutils.pooled_db import PooledDB
+
+def creator():
+    con = connect(...)
+    con.setdecoding(...)
+    return con
+
+creator.dbapi = pyodbc
+
+db_pool = PooledDB(creator, mincached=5)</pre>
+</section>
 <section id="anmerkungen">
 <h2>Anmerkungen</h2>
 <p>Wenn Sie einen der bekannten &quot;Object-Relational Mapper&quot; <a class="reference external" href="http://sqlobject.org/">SQLObject</a> oder

docs/main.de.rst

@@ -461,6 +461,29 @@ ausgesetzt wird, und dass die Verbindung zurückgerollt wird, bevor sie
 wieder an den Verbindungspool zurückgegeben wird.
 
 
+Besonderheiten bei der Benutzung
+================================
+Manchmal möchte man Datenbankverbindung besonders vorbereiten, bevor sie
+von DBUtils verwendet werden, und dies ist nicht immer durch Verwendung
+der passenden Parameter möglich. Zum Beispiel kann es ``pyodb`` erfordern,
+dass man die Methode ``setencoding()`` der Datenbankverbindung aufruft.
+Sie können dies erreichen, indem Sie eine modifizierte Version der
+Funktion ``connect()`` verwenden und diese als ``creator`` (dem ersten
+Argument) an ``PersistentDB`` oder ``PooledDB`` übergeben, etwa so::
+
+    from pyodbc import connect
+    from dbutils.pooled_db import PooledDB
+
+    def creator():
+        con = connect(...)
+        con.setdecoding(...)
+        return con
+
+    creator.dbapi = pyodbc
+
+    db_pool = PooledDB(creator, mincached=5)
+
+
 Anmerkungen
 ===========
 Wenn Sie einen der bekannten "Object-Relational Mapper" SQLObject_ oder

docs/main.html

@@ -44,12 +44,13 @@ <h1 class="title">DBUtils User's Guide</h1>
 <li><p><a class="reference internal" href="#pooleddb-pooled-db-1" id="toc-entry-15">PooledDB (pooled_db)</a></p></li>
 </ul>
 </li>
-<li><p><a class="reference internal" href="#notes" id="toc-entry-16">Notes</a></p></li>
-<li><p><a class="reference internal" href="#future" id="toc-entry-17">Future</a></p></li>
-<li><p><a class="reference internal" href="#bug-reports-and-feedback" id="toc-entry-18">Bug reports and feedback</a></p></li>
-<li><p><a class="reference internal" href="#links" id="toc-entry-19">Links</a></p></li>
-<li><p><a class="reference internal" href="#credits" id="toc-entry-20">Credits</a></p></li>
-<li><p><a class="reference internal" href="#copyright-and-license" id="toc-entry-21">Copyright and License</a></p></li>
+<li><p><a class="reference internal" href="#advanced-usage" id="toc-entry-16">Advanced Usage</a></p></li>
+<li><p><a class="reference internal" href="#notes" id="toc-entry-17">Notes</a></p></li>
+<li><p><a class="reference internal" href="#future" id="toc-entry-18">Future</a></p></li>
+<li><p><a class="reference internal" href="#bug-reports-and-feedback" id="toc-entry-19">Bug reports and feedback</a></p></li>
+<li><p><a class="reference internal" href="#links" id="toc-entry-20">Links</a></p></li>
+<li><p><a class="reference internal" href="#credits" id="toc-entry-21">Credits</a></p></li>
+<li><p><a class="reference internal" href="#copyright-and-license" id="toc-entry-22">Copyright and License</a></p></li>
 </ul>
 </nav>
 <section id="synopsis">
@@ -396,6 +397,26 @@ <h3>PooledDB (pooled_db)</h3>
 back before being given back to the connection pool.</p>
 </section>
 </section>
+<section id="advanced-usage">
+<h2>Advanced Usage</h2>
+<p>Sometimes you may want to prepare connections before they are used by
+DBUtils, in ways that are not possible by just using the right parameters.
+For instance, <span class="docutils literal">pyodbc</span> may require to configure connections by calling
+the <span class="docutils literal">setencoding()</span> method of the connection. You can do this by passing
+a modified <span class="docutils literal">connect()</span> function to <span class="docutils literal">PersistentDB</span> or <span class="docutils literal">PooledDB</span> as
+<span class="docutils literal">creator</span> (the first argument), like this:</p>
+<pre class="literal-block">from pyodbc import connect
+from dbutils.pooled_db import PooledDB
+
+def creator():
+    con = connect(...)
+    con.setdecoding(...)
+    return con
+
+creator.dbapi = pyodbc
+
+db_pool = PooledDB(creator, mincached=5)</pre>
+</section>
 <section id="notes">
 <h2>Notes</h2>
 <p>If you are using one of the popular object-relational mappers <a class="reference external" href="http://www.sqlobject.org/">SQLObject</a>

docs/main.rst

@@ -421,6 +421,28 @@ until the end of the transaction, and that the connection will be rolled
 back before being given back to the connection pool.
 
 
+Advanced Usage
+==============
+Sometimes you may want to prepare connections before they are used by
+DBUtils, in ways that are not possible by just using the right parameters.
+For instance, ``pyodbc`` may require to configure connections by calling
+the ``setencoding()`` method of the connection. You can do this by passing
+a modified ``connect()`` function to ``PersistentDB`` or ``PooledDB`` as
+``creator`` (the first argument), like this::
+
+    from pyodbc import connect
+    from dbutils.pooled_db import PooledDB
+
+    def creator():
+        con = connect(...)
+        con.setdecoding(...)
+        return con
+
+    creator.dbapi = pyodbc
+
+    db_pool = PooledDB(creator, mincached=5)
+
+
 Notes
 =====
 If you are using one of the popular object-relational mappers SQLObject_