[Date Prev][Date Next][Thread Prev][Thread Next][Date Index][Thread Index]
[taler-taler-util] branch master updated: regenerate doc.{html,txt}
|
From: |
gnunet |
|
Subject: |
[taler-taler-util] branch master updated: regenerate doc.{html,txt} |
|
Date: |
Thu, 10 Feb 2022 23:48:48 +0100 |
This is an automated email from the git hooks/post-receive script.
ttn pushed a commit to branch master
in repository taler-util.
The following commit(s) were added to refs/heads/master by this push:
new 73dd4d4 regenerate doc.{html,txt}
73dd4d4 is described below
commit 73dd4d4b62e3d884a0501793cca30634d473879d
Author: Thien-Thi Nguyen <ttn@gnu.org>
AuthorDate: Thu Feb 10 17:48:40 2022 -0500
regenerate doc.{html,txt}
---
doc/doc.html | 209 +++++++++++++++++++++++++++++++++++++++++++++++++++--------
doc/doc.txt | 122 ++++++++++++++++++++++++++++++++++
2 files changed, 305 insertions(+), 26 deletions(-)
diff --git a/doc/doc.html b/doc/doc.html
index 1c765c7..0018a08 100644
--- a/doc/doc.html
+++ b/doc/doc.html
@@ -3,7 +3,7 @@
"http://www.w3.org/TR/xhtml1/DTD/xhtml1-strict.dtd";>
<html xmlns="http://www.w3.org/1999/xhtml"; lang="en" xml:lang="en">
<head>
-<!-- 2022-02-10 gio 14:04 -->
+<!-- 2022-02-10 gio 17:48 -->
<meta http-equiv="Content-Type" content="text/html;charset=utf-8" />
<meta name="viewport" content="width=device-width, initial-scale=1" />
<title>Taler-Util Library</title>
@@ -247,18 +247,27 @@ for the JavaScript code in this tag.
<h2>Table of Contents</h2>
<div id="text-table-of-contents">
<ul>
-<li><a href="#org9fd06cb">1. classes overview</a>
+<li><a href="#org2972670">1. classes overview</a>
<ul>
-<li><a href="#org6e7485b">1.1. amount (currency + value)</a></li>
-<li><a href="#org3a12cb9">1.2. logging</a></li>
-<li><a href="#orga412b06">1.3. ‘payto’ URI particularities</a></li>
-<li><a href="#orgb07a77b">1.4. configuration</a></li>
+<li><a href="#orga235919">1.1. amount (currency + value)</a></li>
+<li><a href="#org5cd8f74">1.2. logging</a></li>
+<li><a href="#orgad29f14">1.3. ‘payto’ URI particularities</a></li>
+<li><a href="#org9bdaa8b">1.4. configuration</a></li>
</ul>
</li>
-<li><a href="#org85d1f4c">2. classes <code>Amount</code>,
<code>SignedAmount</code></a>
+<li><a href="#org1e7fe6d">2. classes <code>Amount</code>,
<code>SignedAmount</code></a>
<ul>
-<li><a href="#org8c0b507">2.1. class <code>Amount</code></a></li>
-<li><a href="#orgccbc767">2.2. class <code>SignedAmount</code></a></li>
+<li><a href="#org468d42d">2.1. class <code>Amount</code></a></li>
+<li><a href="#org6bc67fd">2.2. class <code>SignedAmount</code></a></li>
+</ul>
+</li>
+<li><a href="#orgf88c526">3. classes <code>LogDefinition</code>,
<code>GnunetLoglevel</code></a></li>
+<li><a href="#org824f696">4. class <code>GnunetLogger</code></a>
+<ul>
+<li><a href="#org40a542b">4.1. log definition, environment variables</a></li>
+<li><a href="#orge4c4801">4.2. environment variable
<code>GNUNET_FORCE_LOGFILE</code></a></li>
+<li><a href="#org81a9aad">4.3. constructor</a></li>
+<li><a href="#orgfa85499">4.4. method <code>log</code></a></li>
</ul>
</li>
</ul>
@@ -277,8 +286,8 @@ documentation, we can convert it to Sphinx (or whatever)
format.
Ongoing discussion: <a
href="https://bugs.gnunet.org/view.php?id=6649";>https://bugs.gnunet.org/view.php?id=6649</a>
</p>
-<div id="outline-container-org9fd06cb" class="outline-2">
-<h2 id="org9fd06cb"><span class="section-number-2">1</span> classes
overview</h2>
+<div id="outline-container-org2972670" class="outline-2">
+<h2 id="org2972670"><span class="section-number-2">1</span> classes
overview</h2>
<div class="outline-text-2" id="text-1">
<p>
These are grouped according to area of concern, which (uncoincidentally)
@@ -292,8 +301,8 @@ The rest are <i>leaf classes</i>.
</p>
</div>
-<div id="outline-container-org6e7485b" class="outline-3">
-<h3 id="org6e7485b"><span class="section-number-3">1.1</span> amount (currency
+ value)</h3>
+<div id="outline-container-orga235919" class="outline-3">
+<h3 id="orga235919"><span class="section-number-3">1.1</span> amount (currency
+ value)</h3>
<div class="outline-text-3" id="text-1-1">
<ul class="org-ul">
<li>CurrencyMismatchError(Exception)</li>
@@ -305,8 +314,8 @@ The rest are <i>leaf classes</i>.
</div>
</div>
-<div id="outline-container-org3a12cb9" class="outline-3">
-<h3 id="org3a12cb9"><span class="section-number-3">1.2</span> logging</h3>
+<div id="outline-container-org5cd8f74" class="outline-3">
+<h3 id="org5cd8f74"><span class="section-number-3">1.2</span> logging</h3>
<div class="outline-text-3" id="text-1-2">
<ul class="org-ul">
<li>LogDefinition</li>
@@ -316,8 +325,8 @@ The rest are <i>leaf classes</i>.
</div>
</div>
-<div id="outline-container-orga412b06" class="outline-3">
-<h3 id="orga412b06"><span class="section-number-3">1.3</span> ‘payto’ URI
particularities</h3>
+<div id="outline-container-orgad29f14" class="outline-3">
+<h3 id="orgad29f14"><span class="section-number-3">1.3</span> ‘payto’ URI
particularities</h3>
<div class="outline-text-3" id="text-1-3">
<ul class="org-ul">
<li>PaytoFormatError(Exception)</li>
@@ -326,8 +335,8 @@ The rest are <i>leaf classes</i>.
</div>
</div>
-<div id="outline-container-orgb07a77b" class="outline-3">
-<h3 id="orgb07a77b"><span class="section-number-3">1.4</span>
configuration</h3>
+<div id="outline-container-org9bdaa8b" class="outline-3">
+<h3 id="org9bdaa8b"><span class="section-number-3">1.4</span>
configuration</h3>
<div class="outline-text-3" id="text-1-4">
<ul class="org-ul">
<li>ConfigurationError(Exception)</li>
@@ -341,8 +350,8 @@ The rest are <i>leaf classes</i>.
</div>
</div>
-<div id="outline-container-org85d1f4c" class="outline-2">
-<h2 id="org85d1f4c"><span class="section-number-2">2</span> classes
<code>Amount</code>, <code>SignedAmount</code></h2>
+<div id="outline-container-org1e7fe6d" class="outline-2">
+<h2 id="org1e7fe6d"><span class="section-number-2">2</span> classes
<code>Amount</code>, <code>SignedAmount</code></h2>
<div class="outline-text-2" id="text-2">
<p>
These classes handle Taler <i>amounts</i>, objects referred to in the format
@@ -360,8 +369,8 @@ the constructor throws an <code>AmountOverflowError</code>
exception.
</p>
</div>
-<div id="outline-container-org8c0b507" class="outline-3">
-<h3 id="org8c0b507"><span class="section-number-3">2.1</span> class
<code>Amount</code></h3>
+<div id="outline-container-org468d42d" class="outline-3">
+<h3 id="org468d42d"><span class="section-number-3">2.1</span> class
<code>Amount</code></h3>
<div class="outline-text-3" id="text-2-1">
<p>
The constructor takes three args: <i>currency</i>, <i>value</i>,
<i>fraction</i>.
@@ -473,8 +482,8 @@ False
</div>
</div>
-<div id="outline-container-orgccbc767" class="outline-3">
-<h3 id="orgccbc767"><span class="section-number-3">2.2</span> class
<code>SignedAmount</code></h3>
+<div id="outline-container-org6bc67fd" class="outline-3">
+<h3 id="org6bc67fd"><span class="section-number-3">2.2</span> class
<code>SignedAmount</code></h3>
<div class="outline-text-3" id="text-2-2">
<p>
A <code>SignedAmount</code> object is an <i>amount with a sign</i>.
@@ -545,10 +554,158 @@ True
</div>
</div>
</div>
+
+<div id="outline-container-orgf88c526" class="outline-2">
+<h2 id="orgf88c526"><span class="section-number-2">3</span> classes
<code>LogDefinition</code>, <code>GnunetLoglevel</code></h2>
+<div class="outline-text-2" id="text-3">
+<p>
+These two classes are deliberately undocumented (until further notice).
+They exist primarily to support the <code>GnunetLogger</code> class.
+</p>
+</div>
+</div>
+
+<div id="outline-container-org824f696" class="outline-2">
+<h2 id="org824f696"><span class="section-number-2">4</span> class
<code>GnunetLogger</code></h2>
+<div class="outline-text-2" id="text-4">
+<p>
+The <code>GnunetLogger</code> class wraps the native <code>logging</code>
module and provides
+two primary entry points: the constructor and the <code>log</code> method.
+It supports the usual list of <i>log levels</i>:
+<code>ERROR</code>, <code>WARNING</code>, <code>INFO</code>,
<code>DEBUG</code>.
+</p>
+</div>
+
+<div id="outline-container-org40a542b" class="outline-3">
+<h3 id="org40a542b"><span class="section-number-3">4.1</span> log definition,
environment variables</h3>
+<div class="outline-text-3" id="text-4-1">
+<p>
+What to log is controlled by a <i>log definition</i>, lists of
+which are taken from one or both environment variables when
+the <code>GnunetLogger</code> object is initialized:
+</p>
+
+<ul class="org-ul">
+<li><code>GNUNET_FORCE_LOG</code></li>
+<li><code>GNUNET_LOG</code></li>
+</ul>
+
+<p>
+A log definition looks like:
+</p>
+
+<pre class="example">
+[component];[file];[function];[from_line[-to_line]];loglevel
+</pre>
+
+
+<p>
+The <code>component</code>, <code>file</code>, <code>function</code>, and line
information portions
+are optional; the <code>loglevel</code> is required.
+No portion may contain the <code>;</code> (semicolon) or <code>/</code>
(slash) character.
+When a portion is omitted, it defaults to <i>all</i> of that item.
+The line information can be a single line number or a range,
+written in <code>LOW-HIGH</code> format – note <code>-</code> (hyphen).
+For example, a minimal log definition could be:
+</p>
+
+<pre class="example">
+;;;;ERROR
+</pre>
+
+
+<p>
+This example definition matches all components, all files, all
+functions, and all lines, but only the <code>ERROR</code> log level.
+</p>
+
+<p>
+Multiple log definitions are specified by separating them with a <code>/</code>
+(slash) character.
+</p>
+
+<pre class="example">
+network;;;ERROR/database;;;DEBUG
+</pre>
+
+
+<p>
+The difference between <code>GNUNET_FORCE_LOG</code> and
<code>GNUNET_LOG</code> is that the
+former takes priority over the latter, in case of conflict.
+Also, logging done via <code>GNUNET_FORCE_LOG</code> respects environment
+variable <code>GNUNET_FORCE_LOGFILE</code>.
+</p>
+</div>
+</div>
+
+<div id="outline-container-orge4c4801" class="outline-3">
+<h3 id="orge4c4801"><span class="section-number-3">4.2</span> environment
variable <code>GNUNET_FORCE_LOGFILE</code></h3>
+<div class="outline-text-3" id="text-4-2">
+<p>
+The filename specified by <code>GNUNET_FORCE_LOGFILE</code> can
+have special character sequences replaced (like a template):
+</p>
+
+<dl class="org-dl">
+<dt><code>{}</code></dt><dd>component</dd>
+<dt><code>[]</code></dt><dd>process id</dd>
+<dt><code>%Y</code></dt><dd>numeric year</dd>
+<dt><code>%m</code></dt><dd>numeric month</dd>
+<dt><code>%d</code></dt><dd>numeric day</dd>
+</dl>
+
+<p>
+For example, if <code>GNUNET_FORCE_LOGFILE</code> has value:
+</p>
+
+<pre class="example">
+/var/log/[].{}.%Y-%m-%d.error.log
+</pre>
+
+
+<p>
+then the expansion might be:
+</p>
+
+<pre class="example">
+/var/log/14916.monolith.2022-02-10.error.log
+</pre>
+</div>
+</div>
+
+<div id="outline-container-org81a9aad" class="outline-3">
+<h3 id="org81a9aad"><span class="section-number-3">4.3</span> constructor</h3>
+<div class="outline-text-3" id="text-4-3">
+<p>
+The <code>GnunetLogger</code> constructor takes one argument,
<code>component</code>.
+</p>
+
+<pre class="example">
+>>> from taler.util import gnunet_log
+>>> l = gnunet_log.GnunetLogger ("ui")
+</pre>
+</div>
+</div>
+
+<div id="outline-container-orgfa85499" class="outline-3">
+<h3 id="orgfa85499"><span class="section-number-3">4.4</span> method
<code>log</code></h3>
+<div class="outline-text-3" id="text-4-4">
+<p>
+The <code>log</code> method takes two arguments, <code>message</code> (a
string)
+and <code>message_loglevel</code> (a property of the <code>GnunetLogger</code>
class with
+the same name as the string log level).
+</p>
+
+<pre class="example">
+>>> l.log ("user clicked button", l.INFO)
+</pre>
+</div>
+</div>
+</div>
</div>
<div id="postamble" class="status">
<p class="author">Author: Thien-Thi Nguyen</p>
-<p class="date">Created: 2022-02-10 gio 14:04</p>
+<p class="date">Created: 2022-02-10 gio 17:48</p>
<p class="validation"><a
href="http://validator.w3.org/check?uri=referer";>Validate</a></p>
</div>
</body>
diff --git a/doc/doc.txt b/doc/doc.txt
index 6f818ca..e13040f 100644
--- a/doc/doc.txt
+++ b/doc/doc.txt
@@ -16,6 +16,12 @@ Table of Contents
2. classes ‘Amount’, ‘SignedAmount’
.. 1. class ‘Amount’
.. 2. class ‘SignedAmount’
+3. classes ‘LogDefinition’, ‘GnunetLoglevel’
+4. class ‘GnunetLogger’
+.. 1. log definition, environment variables
+.. 2. environment variable ‘GNUNET_FORCE_LOGFILE’
+.. 3. constructor
+.. 4. method ‘log’
The Taler-Util library provides several classes that deal with various
@@ -246,3 +252,119 @@ Ongoing discussion:
<https://bugs.gnunet.org/view.php?id=6649>
│ >>> (- n).is_positive
│ True
└────
+
+
+3 classes ‘LogDefinition’, ‘GnunetLoglevel’
+═══════════════════════════════════════════
+
+ These two classes are deliberately undocumented (until further
+ notice). They exist primarily to support the ‘GnunetLogger’ class.
+
+
+4 class ‘GnunetLogger’
+══════════════════════
+
+ The ‘GnunetLogger’ class wraps the native ‘logging’ module and
+ provides two primary entry points: the constructor and the ‘log’
+ method. It supports the usual list of /log levels/: ‘ERROR’,
+ ‘WARNING’, ‘INFO’, ‘DEBUG’.
+
+
+4.1 log definition, environment variables
+─────────────────────────────────────────
+
+ What to log is controlled by a /log definition/, lists of which are
+ taken from one or both environment variables when the ‘GnunetLogger’
+ object is initialized:
+
+ • ‘GNUNET_FORCE_LOG’
+ • ‘GNUNET_LOG’
+
+ A log definition looks like:
+
+ ┌────
+ │ [component];[file];[function];[from_line[-to_line]];loglevel
+ └────
+
+
+ The ‘component’, ‘file’, ‘function’, and line information portions are
+ optional; the ‘loglevel’ is required. No portion may contain the ‘;’
+ (semicolon) or ‘/’ (slash) character. When a portion is omitted, it
+ defaults to /all/ of that item. The line information can be a single
+ line number or a range, written in ‘LOW-HIGH’ format – note ‘-’
+ (hyphen). For example, a minimal log definition could be:
+
+ ┌────
+ │ ;;;;ERROR
+ └────
+
+
+ This example definition matches all components, all files, all
+ functions, and all lines, but only the ‘ERROR’ log level.
+
+ Multiple log definitions are specified by separating them with a ‘/’
+ (slash) character.
+
+ ┌────
+ │ network;;;ERROR/database;;;DEBUG
+ └────
+
+
+ The difference between ‘GNUNET_FORCE_LOG’ and ‘GNUNET_LOG’ is that the
+ former takes priority over the latter, in case of conflict. Also,
+ logging done via ‘GNUNET_FORCE_LOG’ respects environment variable
+ ‘GNUNET_FORCE_LOGFILE’.
+
+
+4.2 environment variable ‘GNUNET_FORCE_LOGFILE’
+───────────────────────────────────────────────
+
+ The filename specified by ‘GNUNET_FORCE_LOGFILE’ can have special
+ character sequences replaced (like a template):
+
+ ‘{}’
+ component
+ ‘[]’
+ process id
+ ‘%Y’
+ numeric year
+ ‘%m’
+ numeric month
+ ‘%d’
+ numeric day
+
+ For example, if ‘GNUNET_FORCE_LOGFILE’ has value:
+
+ ┌────
+ │ /var/log/[].{}.%Y-%m-%d.error.log
+ └────
+
+
+ then the expansion might be:
+
+ ┌────
+ │ /var/log/14916.monolith.2022-02-10.error.log
+ └────
+
+
+4.3 constructor
+───────────────
+
+ The ‘GnunetLogger’ constructor takes one argument, ‘component’.
+
+ ┌────
+ │ >>> from taler.util import gnunet_log
+ │ >>> l = gnunet_log.GnunetLogger ("ui")
+ └────
+
+
+4.4 method ‘log’
+────────────────
+
+ The ‘log’ method takes two arguments, ‘message’ (a string) and
+ ‘message_loglevel’ (a property of the ‘GnunetLogger’ class with the
+ same name as the string log level).
+
+ ┌────
+ │ >>> l.log ("user clicked button", l.INFO)
+ └────
--
To stop receiving notification emails like this one, please contact
gnunet@gnunet.org.