Skip to content

Commit

Permalink
Improve CSS style for the documentation
Browse files Browse the repository at this point in the history
  • Loading branch information
@Cito
Cito committed Nov 8, 2024
1 parent b01054b commit c68e3c9
Show file tree
Hide file tree
Showing 7 changed files with 58 additions and 143 deletions.
2 changes: 2 additions & 0 deletions dbutils/steady_db.py
View file
Original file line number Diff line number Diff line change
Expand Up @@ -651,6 +651,8 @@ def tough_method(*args, **kwargs):
if execute:
self._setsizes(cursor2)
method2 = getattr(cursor2, name)
# if the following call hangs,
# you may have forgotten to call begin()
result = method2(*args, **kwargs)
if execute:
self._clearsizes()
Expand Down
134 changes: 16 additions & 118 deletions docs/doc.css
View file
Original file line number Diff line number Diff line change
@@ -1,39 +1,13 @@
/*
Webware for Python (https://webwareforpython.github.io/w4py/)
Common style sheet for Webware's documentation pages
Style sheet for DBUtils documentation pages.
*/

/* First import default style for pages created with Docutils: */

@import url(docutils.css);

/* Customization for Webware goes here: */
/* Customization for DBUtils goes here: */

body {
background-color: #FFFFFF;
font-family: Verdana, Arial, Helvetica, sans-serif;
font-size: 10pt;
padding: 12pt;
}
table {
empty-cells: show;
border-collapse: collapse;
margin: 0 auto;
}
table.doc {
border-spacing: 2px;
border-collapse: separate;
border-style: none;
}
td, th {
font-family: Verdana, Arial, Helvetica, sans-serif;
font-size: 10pt;
}
table.doc td, table.doc th {
padding: 4px;
border-style: none;
}
p {
margin-top: 6pt;
margin-bottom: 6pt;
Expand All @@ -43,11 +17,9 @@ li {
margin-bottom: 6pt;
}
h1, h2 {
font-family: Verdana, Arial, Helvetica, sans-serif;
color: #002352;
}
h3, h4 {
font-family: Verdana, Arial, Helvetica, sans-serif;
color: #002352;
}
h1 {
Expand All @@ -59,119 +31,45 @@ h2 {
h3 {
font-size: 14pt;
}
h4 {
font-size: 12pt;
}
h5 {
font-size: 11pt;
}
h6 {
font-size: 10pt;
}
h1.titlebar {
padding: 4pt;
margin-bottom: 12pt;
text-align: center;
color: white;
background-color: #025;
}
h1.title, h1.header {
h1.title {
padding: 4pt;
margin-bottom: 12pt;
text-align: center;
border-bottom: 1pt solid #025;
padding-bottom: 8pt;
}
div.footer {
font-family: Tahoma, Arial, Helvetica, sans-serif;
font-size: 9pt;
text-align: center;
padding: 4pt;
margin-top: 16pt;
border-top: 1pt solid #025;
}
.left {
text-align: left;
}
.right {
text-align: right;
}
.center {
text-align: center;
}
.top {
vertical-align: top;
}
.nowrap {
white-space: nowrap;
}
.contents {
font-family: Tahoma, Arial, Helvetica, sans-serif;
}
.contents ul {
list-style: none;
margin-bottom: 24pt;
padding-left: 0em;
margin-left: 2em;
}
.contents ul li {
font-size: 11pt;
margin-bottom: 3pt;
font-size: 14pt;
margin-bottom: 2pt;
}
.contents ul ul {
list-style-type: none;
margin-top: 2pt;
margin-bottom: 2pt;
margin-top: 1pt;
margin-bottom: 1pt;
padding-left: 0em;
margin-left: 1.5em;
}
.contents ul ul li {
font-size: 10pt;
font-size: 13pt;
margin-bottom: 1pt;
}
.contents .topic-title {
font-size: 16pt;
}
span.name {
font-weight: bold;
}
span.filename {
font-family: Tahoma, Arial, Helvetica, sans-serif;
font-size: 9pt;
}
code, .literal, .literal-block, .pre, .py {
font-family: "Andale Mono", "Lucida Console", Monaco, "Courier New", Courier, monospace;
font-size: 10pt;
color: #052;
}
tt.literal, span.pre {
background-color: #FFFFFF;
}
pre.py, pre.literal-block {
margin: 0;
padding: 2pt 1pt 1pt 2pt;
background-color: #F0F0F8;
}
.typed {
font-weight: bold;
}
.error {
color: red;
.contents > p.topic-title {
font-size: 24pt;
}
.warning {
color: brown;
}

/* Configuration documentation: */

dl.config {
}
dt.config {
}
dd.config {
.admonition-title {
background-color: #F5F5DC;
padding: 1pt 3pt;
}
span.setting {
font-family: Tahoma, Arial, Helvetica, sans-serif;
font-size: 9pt;
font-weight: bold;
.admonition-title::before {
content: "⚠";
margin-right: .5em;
}
4 changes: 2 additions & 2 deletions docs/docutils.css
View file

Some generated files are not rendered by default. Learn more about how customized files appear on GitHub.

6 changes: 6 additions & 0 deletions docs/main.de.html
View file
Original file line number Diff line number Diff line change
Expand Up @@ -321,11 +321,14 @@ <h3>PersistentDB (persistent_db)</h3>
Stattdessen wird die Verbindung automatisch dann geschlossen, wenn der Thread
endet. Sie können dieses Verhalten ändern, indem Sie den Parameter namens
<span class="docutils literal">closeable</span> setzen.</p>
<aside class="admonition warning">
<p class="admonition-title">Warnung</p>
<p>Bitte beachten Sie, dass Transaktionen explizit durch Aufruf der Methode
<span class="docutils literal">begin()</span> eingeleitet werden müssen. Hierdurch wird sichergestellt, dass
das transparente Neueröffnen von Verbindungen bis zum Ende der Transaktion
ausgesetzt wird, und dass die Verbindung zurückgerollt wird, before sie vom
gleichen Thread erneut benutzt wird.</p>
</aside>
<p>Das Holen einer Verbindung kann etwas beschleunigt werden, indem man den
Parameter <span class="docutils literal">threadlocal</span> auf <span class="docutils literal">threading.local</span> setzt; dies könnte aber in
einigen Umgebungen nicht funktionieren (es ist zum Beispiel bekannt, dass
Expand Down Expand Up @@ -428,12 +431,15 @@ <h3>PooledDB (pooled_db)</h3>
with db.cursor() as cur:
cur.execute(...)
res = cur.fetchone()</pre>
<aside class="admonition warning">
<p class="admonition-title">Warnung</p>
<p>Bitte beachten Sie, dass Transaktionen explizit durch Aufruf der Methode
<span class="docutils literal">begin()</span> eingeleitet werden müssen. Hierdurch wird sichergestellt,
dass die Verbindung nicht mehr mit anderen Threads geteilt wird, dass das
transparente Neueröffnen von Verbindungen bis zum Ende der Transaktion
ausgesetzt wird, und dass die Verbindung zurückgerollt wird, bevor sie
wieder an den Verbindungspool zurückgegeben wird.</p>
</aside>
</section>
</section>
<section id="besonderheiten-bei-der-benutzung">
Expand Down
25 changes: 13 additions & 12 deletions docs/main.de.rst
View file
Original file line number Diff line number Diff line change
Expand Up @@ -317,11 +317,12 @@ Stattdessen wird die Verbindung automatisch dann geschlossen, wenn der Thread
endet. Sie können dieses Verhalten ändern, indem Sie den Parameter namens
``closeable`` setzen.

Bitte beachten Sie, dass Transaktionen explizit durch Aufruf der Methode
``begin()`` eingeleitet werden müssen. Hierdurch wird sichergestellt, dass
das transparente Neueröffnen von Verbindungen bis zum Ende der Transaktion
ausgesetzt wird, und dass die Verbindung zurückgerollt wird, before sie vom
gleichen Thread erneut benutzt wird.
.. warning::
Bitte beachten Sie, dass Transaktionen explizit durch Aufruf der Methode
``begin()`` eingeleitet werden müssen. Hierdurch wird sichergestellt, dass
das transparente Neueröffnen von Verbindungen bis zum Ende der Transaktion
ausgesetzt wird, und dass die Verbindung zurückgerollt wird, before sie vom
gleichen Thread erneut benutzt wird.

Das Holen einer Verbindung kann etwas beschleunigt werden, indem man den
Parameter ``threadlocal`` auf ``threading.local`` setzt; dies könnte aber in
Expand Down Expand Up @@ -452,13 +453,13 @@ Sie können dies auch durch Verwendung von Kontext-Managern vereinfachen::
cur.execute(...)
res = cur.fetchone()


Bitte beachten Sie, dass Transaktionen explizit durch Aufruf der Methode
``begin()`` eingeleitet werden müssen. Hierdurch wird sichergestellt,
dass die Verbindung nicht mehr mit anderen Threads geteilt wird, dass das
transparente Neueröffnen von Verbindungen bis zum Ende der Transaktion
ausgesetzt wird, und dass die Verbindung zurückgerollt wird, bevor sie
wieder an den Verbindungspool zurückgegeben wird.
.. warning::
Bitte beachten Sie, dass Transaktionen explizit durch Aufruf der Methode
``begin()`` eingeleitet werden müssen. Hierdurch wird sichergestellt,
dass die Verbindung nicht mehr mit anderen Threads geteilt wird, dass das
transparente Neueröffnen von Verbindungen bis zum Ende der Transaktion
ausgesetzt wird, und dass die Verbindung zurückgerollt wird, bevor sie
wieder an den Verbindungspool zurückgegeben wird.


Besonderheiten bei der Benutzung
Expand Down
8 changes: 7 additions & 1 deletion docs/main.html
View file
Original file line number Diff line number Diff line change
Expand Up @@ -298,10 +298,13 @@ <h3>PersistentDB (persistent_db)</h3>
contrary to the intent of having persistent connections. Instead,
the connection will be automatically closed when the thread dies.
You can change this behavior by setting the <span class="docutils literal">closeable</span> parameter.</p>
<aside class="admonition warning">
<p class="admonition-title">Warning</p>
<p>Note that you need to explicitly start transactions by calling the
<span class="docutils literal">begin()</span> method. This ensures that the transparent reopening will be
suspended until the end of the transaction, and that the connection
will be rolled back before being reused by the same thread.</p>
</aside>
<p>By setting the <span class="docutils literal">threadlocal</span> parameter to <span class="docutils literal">threading.local</span>, getting
connections may become a bit faster, but this may not work in all
environments (for instance, <span class="docutils literal">mod_wsgi</span> is known to cause problems
Expand Down Expand Up @@ -374,7 +377,7 @@ <h3>PooledDB (pooled_db)</h3>
<pre class="literal-block">db = pool.dedicated_connection()</pre>
<p>If you don't need it anymore, you should immediately return it to the
pool with <span class="docutils literal">db.close()</span>. You can get another connection in the same way.</p>
<p><em>Warning:</em> In a threaded environment, never do the following:</p>
<p>⚠ Warning: In a threaded environment, never do the following:</p>
<pre class="literal-block">pool.connection().cursor().execute(...)</pre>
<p>This would release the connection too early for reuse which may be fatal
if the connections are not thread-safe. Make sure that the connection
Expand All @@ -390,11 +393,14 @@ <h3>PooledDB (pooled_db)</h3>
with db.cursor() as cur:
cur.execute(...)
res = cur.fetchone()</pre>
<aside class="admonition warning">
<p class="admonition-title">Warning</p>
<p>Note that you need to explicitly start transactions by calling the
<span class="docutils literal">begin()</span> method. This ensures that the connection will not be shared
with other threads, that the transparent reopening will be suspended
until the end of the transaction, and that the connection will be rolled
back before being given back to the connection pool.</p>
</aside>
</section>
</section>
<section id="advanced-usage">
Expand Down
Loading

0 comments on commit c68e3c9

Please sign in to comment.