[Date Prev][Date Next][Thread Prev][Thread Next][Date Index][Thread Index]
[taler-taler-util] 02/02: regenerate doc.{html,txt}
|
From: |
gnunet |
|
Subject: |
[taler-taler-util] 02/02: regenerate doc.{html,txt} |
|
Date: |
Tue, 15 Feb 2022 14:21:39 +0100 |
This is an automated email from the git hooks/post-receive script.
ttn pushed a commit to branch master
in repository taler-util.
commit 932f8dc2f0f58c715f0de48af7341a5c4e07c634
Author: Thien-Thi Nguyen <ttn@gnu.org>
AuthorDate: Tue Feb 15 08:21:14 2022 -0500
regenerate doc.{html,txt}
---
doc/doc.html | 351 +++++++++++++++++++++++++++++++++++++++++++++++++----------
doc/doc.txt | 182 +++++++++++++++++++++++++++++--
2 files changed, 470 insertions(+), 63 deletions(-)
diff --git a/doc/doc.html b/doc/doc.html
index 8a8bfa3..1f2774d 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 19:44 -->
+<!-- 2022-02-15 mar 08:20 -->
<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,30 +247,43 @@ for the JavaScript code in this tag.
<h2>Table of Contents</h2>
<div id="text-table-of-contents">
<ul>
-<li><a href="#orgca83dbe">1. classes overview</a>
+<li><a href="#org02f1529">1. classes overview</a>
<ul>
-<li><a href="#org5d66d83">1.1. amount (currency + value + fraction)</a></li>
-<li><a href="#org44f0451">1.2. logging</a></li>
-<li><a href="#org6c994e8">1.3. ‘payto’ URI particularities</a></li>
-<li><a href="#org25aab70">1.4. configuration</a></li>
+<li><a href="#orgf8d22b2">1.1. amount (currency + value + fraction)</a></li>
+<li><a href="#orge70d263">1.2. logging</a></li>
+<li><a href="#org69c7ded">1.3. ‘payto’ URI particularities</a></li>
+<li><a href="#orga275dd5">1.4. configuration</a></li>
</ul>
</li>
-<li><a href="#org1f4e090">2. classes for handling currency plus value plus
fraction</a>
+<li><a href="#org3c63bce">2. classes for handling currency plus value plus
fraction</a>
<ul>
-<li><a href="#orgc5c5b05">2.1. class <code>Amount</code></a></li>
-<li><a href="#org75fe6af">2.2. class <code>SignedAmount</code></a></li>
+<li><a href="#org8038926">2.1. class <code>Amount</code></a></li>
+<li><a href="#org8292d6a">2.2. class <code>SignedAmount</code></a></li>
</ul>
</li>
-<li><a href="#orgc5d0f9f">3. classes <code>LogDefinition</code>,
<code>GnunetLoglevel</code></a></li>
-<li><a href="#orga09fc8a">4. class <code>GnunetLogger</code></a>
+<li><a href="#org195d8b6">3. classes <code>LogDefinition</code>,
<code>GnunetLoglevel</code></a></li>
+<li><a href="#org7de92e5">4. class <code>GnunetLogger</code></a>
<ul>
-<li><a href="#org39a01ca">4.1. log definition, environment variables</a></li>
-<li><a href="#org2f6906d">4.2. environment variable
<code>GNUNET_FORCE_LOGFILE</code></a></li>
-<li><a href="#org9663b14">4.3. constructor</a></li>
-<li><a href="#org2f746c8">4.4. method <code>log</code></a></li>
+<li><a href="#org7009ddc">4.1. log definition, environment variables</a></li>
+<li><a href="#org1798ccd">4.2. environment variable
<code>GNUNET_FORCE_LOGFILE</code></a></li>
+<li><a href="#org06b279d">4.3. constructor</a></li>
+<li><a href="#org80aed03">4.4. method <code>log</code></a></li>
+</ul>
+</li>
+<li><a href="#orgf7c8bc6">5. ‘payto’ URI parsing</a></li>
+<li><a href="#org072c5f1">6. class <code>TalerConfig</code></a>
+<ul>
+<li><a href="#org0599319">6.1. reading</a></li>
+<li><a href="#orga822452">6.2. value types</a></li>
+<li><a href="#org7064493">6.3. retrieving values</a>
+<ul>
+<li><a href="#orgc5df650">6.3.1. specific values</a></li>
+<li><a href="#orga41143a">6.3.2. entire set</a></li>
+</ul>
+</li>
+<li><a href="#orge6a4a6a">6.4. usage as a program</a></li>
</ul>
</li>
-<li><a href="#org9a25003">5. ‘payto’ URI parsing</a></li>
</ul>
</div>
</div>
@@ -287,8 +300,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-orgca83dbe" class="outline-2">
-<h2 id="orgca83dbe"><span class="section-number-2">1</span> classes
overview</h2>
+<div id="outline-container-org02f1529" class="outline-2">
+<h2 id="org02f1529"><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)
@@ -296,14 +309,13 @@ is also how the source code is organized.
</p>
<p>
-Several of these derive from the <code>Exception</code> class, and two
-of them derive from the <code>collections.defaultdict</code> class.
+Several of these derive from the <code>Exception</code> class.
The rest are <i>leaf classes</i>.
</p>
</div>
-<div id="outline-container-org5d66d83" class="outline-3">
-<h3 id="org5d66d83"><span class="section-number-3">1.1</span> amount (currency
+ value + fraction)</h3>
+<div id="outline-container-orgf8d22b2" class="outline-3">
+<h3 id="orgf8d22b2"><span class="section-number-3">1.1</span> amount (currency
+ value + fraction)</h3>
<div class="outline-text-3" id="text-1-1">
<ul class="org-ul">
<li>CurrencyMismatchError(Exception)</li>
@@ -315,8 +327,8 @@ The rest are <i>leaf classes</i>.
</div>
</div>
-<div id="outline-container-org44f0451" class="outline-3">
-<h3 id="org44f0451"><span class="section-number-3">1.2</span> logging</h3>
+<div id="outline-container-orge70d263" class="outline-3">
+<h3 id="orge70d263"><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>
@@ -326,8 +338,8 @@ The rest are <i>leaf classes</i>.
</div>
</div>
-<div id="outline-container-org6c994e8" class="outline-3">
-<h3 id="org6c994e8"><span class="section-number-3">1.3</span> ‘payto’ URI
particularities</h3>
+<div id="outline-container-org69c7ded" class="outline-3">
+<h3 id="org69c7ded"><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>
@@ -336,23 +348,18 @@ The rest are <i>leaf classes</i>.
</div>
</div>
-<div id="outline-container-org25aab70" class="outline-3">
-<h3 id="org25aab70"><span class="section-number-3">1.4</span>
configuration</h3>
+<div id="outline-container-orga275dd5" class="outline-3">
+<h3 id="orga275dd5"><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>
-<li>ExpansionSyntaxError(Exception)</li>
-<li>Entry</li>
-<li>OptionDict(collections.defaultdict)</li>
-<li>SectionDict(collections.defaultdict)</li>
<li>TalerConfig</li>
</ul>
</div>
</div>
</div>
-<div id="outline-container-org1f4e090" class="outline-2">
-<h2 id="org1f4e090"><span class="section-number-2">2</span> classes for
handling currency plus value plus fraction</h2>
+<div id="outline-container-org3c63bce" class="outline-2">
+<h2 id="org3c63bce"><span class="section-number-2">2</span> classes for
handling currency plus value plus fraction</h2>
<div class="outline-text-2" id="text-2">
<p>
The <code>Amount</code> and <code>SignedAmount</code> handle Taler
<i>amounts</i>,
@@ -381,8 +388,8 @@ the constructor throws an <code>AmountOverflowError</code>
exception.
</p>
</div>
-<div id="outline-container-orgc5c5b05" class="outline-3">
-<h3 id="orgc5c5b05"><span class="section-number-3">2.1</span> class
<code>Amount</code></h3>
+<div id="outline-container-org8038926" class="outline-3">
+<h3 id="org8038926"><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: <code>currency</code>, <code>value</code>,
<code>fraction</code>.
@@ -502,8 +509,8 @@ False
</div>
</div>
-<div id="outline-container-org75fe6af" class="outline-3">
-<h3 id="org75fe6af"><span class="section-number-3">2.2</span> class
<code>SignedAmount</code></h3>
+<div id="outline-container-org8292d6a" class="outline-3">
+<h3 id="org8292d6a"><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>.
@@ -582,8 +589,8 @@ True
</div>
</div>
-<div id="outline-container-orgc5d0f9f" class="outline-2">
-<h2 id="orgc5d0f9f"><span class="section-number-2">3</span> classes
<code>LogDefinition</code>, <code>GnunetLoglevel</code></h2>
+<div id="outline-container-org195d8b6" class="outline-2">
+<h2 id="org195d8b6"><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).
@@ -592,8 +599,8 @@ They exist primarily to support the
<code>GnunetLogger</code> class.
</div>
</div>
-<div id="outline-container-orga09fc8a" class="outline-2">
-<h2 id="orga09fc8a"><span class="section-number-2">4</span> class
<code>GnunetLogger</code></h2>
+<div id="outline-container-org7de92e5" class="outline-2">
+<h2 id="org7de92e5"><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
@@ -603,8 +610,8 @@ It supports the usual list of <i>log levels</i>:
</p>
</div>
-<div id="outline-container-org39a01ca" class="outline-3">
-<h3 id="org39a01ca"><span class="section-number-3">4.1</span> log definition,
environment variables</h3>
+<div id="outline-container-org7009ddc" class="outline-3">
+<h3 id="org7009ddc"><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
@@ -665,8 +672,8 @@ variable <code>GNUNET_FORCE_LOGFILE</code>.
</div>
</div>
-<div id="outline-container-org2f6906d" class="outline-3">
-<h3 id="org2f6906d"><span class="section-number-3">4.2</span> environment
variable <code>GNUNET_FORCE_LOGFILE</code></h3>
+<div id="outline-container-org1798ccd" class="outline-3">
+<h3 id="org1798ccd"><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
@@ -700,8 +707,8 @@ then the expansion might be:
</div>
</div>
-<div id="outline-container-org9663b14" class="outline-3">
-<h3 id="org9663b14"><span class="section-number-3">4.3</span> constructor</h3>
+<div id="outline-container-org06b279d" class="outline-3">
+<h3 id="org06b279d"><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>.
@@ -715,8 +722,8 @@ The <code>GnunetLogger</code> constructor takes one
argument, <code>component</c
</div>
</div>
-<div id="outline-container-org2f746c8" class="outline-3">
-<h3 id="org2f746c8"><span class="section-number-3">4.4</span> method
<code>log</code></h3>
+<div id="outline-container-org80aed03" class="outline-3">
+<h3 id="org80aed03"><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)
@@ -732,8 +739,8 @@ INFO:ui:user clicked button
</div>
</div>
-<div id="outline-container-org9a25003" class="outline-2">
-<h2 id="org9a25003"><span class="section-number-2">5</span> ‘payto’ URI
parsing</h2>
+<div id="outline-container-orgf7c8bc6" class="outline-2">
+<h2 id="orgf7c8bc6"><span class="section-number-2">5</span> ‘payto’ URI
parsing</h2>
<div class="outline-text-2" id="text-5">
<p>
The <code>PaytoParse</code> class has only one entry point, its constructor.
@@ -752,7 +759,7 @@ On successful parse, the object has the following
properties:
<dt><code>bank</code></dt><dd>bank handling the payment</dd>
<dt><code>authority</code></dt><dd>payment type (e.g., <code>iban</code>)</dd>
<dt><code>message</code></dt><dd>short human-readable description of the
payment</dd>
-<dt><code>amount</code></dt><dd>in <code>CUR:X.Y</code> format (<a
href="#orgc5c5b05">2.1</a>)</dd>
+<dt><code>amount</code></dt><dd>in <code>CUR:X.Y</code> format (<a
href="#org8038926">2.1</a>)</dd>
</dl>
<p>
@@ -802,10 +809,244 @@ Amount(currency='EUR', value=200, fraction=0)
</pre>
</div>
</div>
+
+<div id="outline-container-org072c5f1" class="outline-2">
+<h2 id="org072c5f1"><span class="section-number-2">6</span> class
<code>TalerConfig</code></h2>
+<div class="outline-text-2" id="text-6">
+<p>
+The <code>TalerConfig</code> class represents a <i>Taler configuration</i>, a
set
+of <i>sections</i> with <i>options</i> and associated <i>values</i> (basically,
+a nested dictionary), and provides methods for initializing,
+and accessing those values, keyed by section and option.
+</p>
+
+<p>
+When a Taler configuration is written to a file (the usual case),
+it follows the typical Windows INI format.
+For more information, see the taler-config(5) manpage.
+</p>
+</div>
+
+<div id="outline-container-org0599319" class="outline-3">
+<h3 id="org0599319"><span class="section-number-3">6.1</span> reading</h3>
+<div class="outline-text-3" id="text-6-1">
+<p>
+The standard way to construct a <code>TalerConfig</code> object is to start
+with one of two initialization methods: <code>from_file</code> or
<code>from_env</code>.
+The former reads the configuration from a file, given its name.
+If no name is provided (it is <code>None</code>), <code>from_file</code> first
tries
+to find <code>taler.conf</code> in two directories:
+</p>
+
+<ul class="org-ul">
+<li>directory named by environment variable <code>XDG_CONFIG_HOME</code></li>
+
+<li><code>$HOME/.config</code> (where <code>HOME</code> is the user's home
directory)</li>
+</ul>
+
+<p>
+The <code>from_env</code> initialization method first determines a filename
+by consulting environment variable <code>TALER_CONFIG_FILE</code> and then
+uses <code>from_file</code> on that.
+</p>
+
+<p>
+Both initialization methods take keyword arg <code>load_defaults</code>
+(default <code>True</code>) that directs the method to also call
+the <code>load_defaults</code> method before reading the file.
+</p>
+
+<p>
+The <code>load_defaults</code> method takes no arguments.
+It looks in the canonical locations (directories) and
+uses method <code>load_dir</code> on them.
+Once it finds a specified dir, it stops searching.
+The canonical locations are:
+</p>
+
+<ul class="org-ul">
+<li>environment variable <code>TALER_BASE_CONFIG</code></li>
+
+<li><p>
+environment variable <code>TALER_PREFIX</code>, with any trailing component
+<code>lib</code> discarded, and suffixed with <code>share/taler/config.d</code>
+</p>
+
+<p>
+For example, if <code>TALER_PREFIX</code> is <code>/usr/local/lib</code>, then
+<code>load_defaults</code> would look in
<code>/usr/local/share/taler/config.d</code>.
+The same would result if <code>TALER_PREFIX</code> were <code>/usr/local</code>
+(the suffixing is unconditional).
+</p></li>
+
+<li><p>
+if module <code>talerpaths</code> exists and exports
<code>TALER_DATADIR</code>, then the
+directory named by suffixing its value with <code>share/taler/config.d</code>
+</p>
+
+<p>
+FIXME: Comment in code: "not clear if this is a good idea" –
+Maybe we should remove this functionality or leave it undocumented?
+</p></li>
+</ul>
+
+<p>
+If <code>load_defaults</code> cannot find something to load it logs a warning
+"no base directory found".
+</p>
+
+<p>
+The <code>load_dir</code> method takes one argument <code>dirname</code>, and
+uses <code>load_file</code> on all files that directory whose name ends
+with <code>.conf</code>.
+</p>
+
+<p>
+At its core, all file reading uses method <code>load_file</code>,
+which takes one argument, the <code>filename</code> to read.
+If <code>filename</code> cannot be found, <code>load_file</code> causes
+the process to exit with exit value <code>3</code>.
+</p>
+</div>
+</div>
+
+<div id="outline-container-orga822452" class="outline-3">
+<h3 id="orga822452"><span class="section-number-3">6.2</span> value types</h3>
+<div class="outline-text-3" id="text-6-2">
+<p>
+There are three types of values in a Taler configuration: <code>int</code>
(integer),
+<code>string</code> and <code>filename</code>.
+The <code>int</code> and <code>string</code> types are self-explanatory.
+The <code>filename</code> type is a string that has certain constructs
expanded:
+</p>
+
+<ul class="org-ul">
+<li><code>${X}</code></li>
+<li><code>${X:-Y}</code></li>
+<li><code>$X</code></li>
+</ul>
+
+<p>
+These mimic shell-style variable expansion.
+In all these constructs, the value of <code>X</code> replaces the construct.
+In the second one only, if the value of <code>X</code> is empty, use the
+value of <code>Y</code> instead.
+</p>
+
+<p>
+FIXME: Can the second type be nested (i.e., <code>${X:-${Y:-Z}}</code>)?
+</p>
+
+<p>
+For example, <code>${TMPDIR:-/tmp}/taler-test</code> expands to
<code>/var/tmp/taler-test</code>
+if environment variable <code>TMPDIR</code> has value <code>/var/tmp</code>,
otherwise
+simply <code>/tmp/taler-test</code>.
+</p>
+</div>
+</div>
+
+<div id="outline-container-org7064493" class="outline-3">
+<h3 id="org7064493"><span class="section-number-3">6.3</span> retrieving
values</h3>
+<div class="outline-text-3" id="text-6-3">
+<p>
+Once a Taler configuration is read, you can retrieve specific
+values from it, or display the entire set to stdout.
+</p>
+</div>
+
+<div id="outline-container-orgc5df650" class="outline-4">
+<h4 id="orgc5df650"><span class="section-number-4">6.3.1</span> specific
values</h4>
+<div class="outline-text-4" id="text-6-3-1">
+<p>
+Each type <i>foo</i> has a <code>value_foo</code> method (e.g.,
<code>value_int</code> for integer).
+The method takes two required arguments, the <code>section</code> and
<code>option</code>,
+both strings.
+Case does not matter.
+</p>
+
+<p>
+In addition to the required arguments, <code>value_string</code> accepts
+the following keyword arguments:
+</p>
+
+<dl class="org-dl">
+<dt><code>default</code></dt><dd>If the requested value is not found, return
this
+value instead. Default is no default. :-D</dd>
+
+<dt><code>required</code></dt><dd>If the requested value is not found, print
an error
+message and cause the process to exit with exit value <code>1</code>.</dd>
+
+<dt><code>warn</code></dt><dd>If the requested value is not found, log a
warning.
+If <code>default</code> is also given, return that, otherwise return
<code>None</code>.</dd>
+</dl>
+
+<p>
+(Both <code>value_int</code> and <code>value_filename</code> also accept these
keyword
+arguments, but they are ignored.)
+</p>
+</div>
+</div>
+
+<div id="outline-container-orga41143a" class="outline-4">
+<h4 id="orga41143a"><span class="section-number-4">6.3.2</span> entire set</h4>
+<div class="outline-text-4" id="text-6-3-2">
+<p>
+The <code>dump</code> method takes no arguments.
+It displays to stdout each section and its options (and values)
+in the format:
+</p>
+
+<pre class="example">
+[section]
+option = value # FIXME (what is location?)
+</pre>
+</div>
+</div>
+</div>
+
+<div id="outline-container-orge6a4a6a" class="outline-3">
+<h3 id="orge6a4a6a"><span class="section-number-3">6.4</span> usage as a
program</h3>
+<div class="outline-text-3" id="text-6-4">
+<p>
+FIXME: Is this supposed to be documented?
+Seems out of place in a library.
+Maybe it's there only for testing purposes?
+Another idea is to move it to its own utility program.
+</p>
+
+<p>
+If <code>talerconfig.py</code> is invoked from the command-line, it functions
+as a program that displays either a specific value or dumps the entire set,
+depending on the command-line args given.
+</p>
+
+<p>
+Options are:
+</p>
+
+<dl class="org-dl">
+<dt><code>-c, --config FILE</code></dt><dd>Read Taler configuration from
<code>FILE</code>.
+See <code>from_file</code> (above) for behavior if unspecified.</dd>
+
+<dt><code>-s, --section SECTION</code></dt><dd>Look for option in section
<code>SECTION</code>.</dd>
+
+<dt><code>-o, --option OPTION</code></dt><dd>Display value associated with
option <code>OPTION</code>.</dd>
+
+<dt><code>-f, --filename</code></dt><dd>If the value is a string, do
shell-style
+variable expansion (see above) on it.</dd>
+</dl>
+
+<p>
+If both <code>SECTION</code> and <code>OPTION</code> are omitted, display the
entire set
+of values using the <code>dump</code> method (see above).
+</p>
+</div>
+</div>
+</div>
</div>
<div id="postamble" class="status">
<p class="author">Author: Taler Contributors</p>
-<p class="date">Created: 2022-02-10 gio 19:44</p>
+<p class="date">Created: 2022-02-15 mar 08:20</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 b3b3350..82c32a3 100644
--- a/doc/doc.txt
+++ b/doc/doc.txt
@@ -23,6 +23,13 @@ Table of Contents
.. 3. constructor
.. 4. method ‘log’
5. ‘payto’ URI parsing
+6. class ‘TalerConfig’
+.. 1. reading
+.. 2. value types
+.. 3. retrieving values
+..... 1. specific values
+..... 2. entire set
+.. 4. usage as a program
The Taler-Util library provides several classes that deal with various
@@ -41,9 +48,8 @@ Ongoing discussion: <https://bugs.gnunet.org/view.php?id=6649>
These are grouped according to area of concern, which
(uncoincidentally) is also how the source code is organized.
- Several of these derive from the ‘Exception’ class, and two of them
- derive from the ‘collections.defaultdict’ class. The rest are /leaf
- classes/.
+ Several of these derive from the ‘Exception’ class. The rest are
+ /leaf classes/.
1.1 amount (currency + value + fraction)
@@ -74,11 +80,6 @@ Ongoing discussion:
<https://bugs.gnunet.org/view.php?id=6649>
1.4 configuration
─────────────────
- • ConfigurationError(Exception)
- • ExpansionSyntaxError(Exception)
- • Entry
- • OptionDict(collections.defaultdict)
- • SectionDict(collections.defaultdict)
• TalerConfig
@@ -458,3 +459,168 @@ Ongoing discussion:
<https://bugs.gnunet.org/view.php?id=6649>
│ >>> p.amount
│ Amount(currency='EUR', value=200, fraction=0)
└────
+
+
+6 class ‘TalerConfig’
+═════════════════════
+
+ The ‘TalerConfig’ class represents a /Taler configuration/, a set of
+ /sections/ with /options/ and associated /values/ (basically, a nested
+ dictionary), and provides methods for initializing, and accessing
+ those values, keyed by section and option.
+
+ When a Taler configuration is written to a file (the usual case), it
+ follows the typical Windows INI format. For more information, see the
+ taler-config(5) manpage.
+
+
+6.1 reading
+───────────
+
+ The standard way to construct a ‘TalerConfig’ object is to start with
+ one of two initialization methods: ‘from_file’ or ‘from_env’. The
+ former reads the configuration from a file, given its name. If no
+ name is provided (it is ‘None’), ‘from_file’ first tries to find
+ ‘taler.conf’ in two directories:
+
+ • directory named by environment variable ‘XDG_CONFIG_HOME’
+
+ • ‘$HOME/.config’ (where ‘HOME’ is the user's home directory)
+
+ The ‘from_env’ initialization method first determines a filename by
+ consulting environment variable ‘TALER_CONFIG_FILE’ and then uses
+ ‘from_file’ on that.
+
+ Both initialization methods take keyword arg ‘load_defaults’ (default
+ ‘True’) that directs the method to also call the ‘load_defaults’
+ method before reading the file.
+
+ The ‘load_defaults’ method takes no arguments. It looks in the
+ canonical locations (directories) and uses method ‘load_dir’ on them.
+ Once it finds a specified dir, it stops searching. The canonical
+ locations are:
+
+ • environment variable ‘TALER_BASE_CONFIG’
+
+ • environment variable ‘TALER_PREFIX’, with any trailing component
+ ‘lib’ discarded, and suffixed with ‘share/taler/config.d’
+
+ For example, if ‘TALER_PREFIX’ is ‘/usr/local/lib’, then
+ ‘load_defaults’ would look in ‘/usr/local/share/taler/config.d’.
+ The same would result if ‘TALER_PREFIX’ were ‘/usr/local’ (the
+ suffixing is unconditional).
+
+ • if module ‘talerpaths’ exists and exports ‘TALER_DATADIR’, then the
+ directory named by suffixing its value with ‘share/taler/config.d’
+
+ FIXME: Comment in code: "not clear if this is a good idea" – Maybe
+ we should remove this functionality or leave it undocumented?
+
+ If ‘load_defaults’ cannot find something to load it logs a warning "no
+ base directory found".
+
+ The ‘load_dir’ method takes one argument ‘dirname’, and uses
+ ‘load_file’ on all files that directory whose name ends with ‘.conf’.
+
+ At its core, all file reading uses method ‘load_file’, which takes one
+ argument, the ‘filename’ to read. If ‘filename’ cannot be found,
+ ‘load_file’ causes the process to exit with exit value ‘3’.
+
+
+6.2 value types
+───────────────
+
+ There are three types of values in a Taler configuration: ‘int’
+ (integer), ‘string’ and ‘filename’. The ‘int’ and ‘string’ types are
+ self-explanatory. The ‘filename’ type is a string that has certain
+ constructs expanded:
+
+ • ‘${X}’
+ • ‘${X:-Y}’
+ • ‘$X’
+
+ These mimic shell-style variable expansion. In all these constructs,
+ the value of ‘X’ replaces the construct. In the second one only, if
+ the value of ‘X’ is empty, use the value of ‘Y’ instead.
+
+ FIXME: Can the second type be nested (i.e., ‘${X:-${Y:-Z}}’)?
+
+ For example, ‘${TMPDIR:-/tmp}/taler-test’ expands to
+ ‘/var/tmp/taler-test’ if environment variable ‘TMPDIR’ has value
+ ‘/var/tmp’, otherwise simply ‘/tmp/taler-test’.
+
+
+6.3 retrieving values
+─────────────────────
+
+ Once a Taler configuration is read, you can retrieve specific values
+ from it, or display the entire set to stdout.
+
+
+6.3.1 specific values
+╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌
+
+ Each type /foo/ has a ‘value_foo’ method (e.g., ‘value_int’ for
+ integer). The method takes two required arguments, the ‘section’ and
+ ‘option’, both strings. Case does not matter.
+
+ In addition to the required arguments, ‘value_string’ accepts the
+ following keyword arguments:
+
+ ‘default’
+ If the requested value is not found, return this value instead.
+ Default is no default. :-D
+
+ ‘required’
+ If the requested value is not found, print an error message and
+ cause the process to exit with exit value ‘1’.
+
+ ‘warn’
+ If the requested value is not found, log a warning. If
+ ‘default’ is also given, return that, otherwise return ‘None’.
+
+ (Both ‘value_int’ and ‘value_filename’ also accept these keyword
+ arguments, but they are ignored.)
+
+
+6.3.2 entire set
+╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌
+
+ The ‘dump’ method takes no arguments. It displays to stdout each
+ section and its options (and values) in the format:
+
+ ┌────
+ │ [section]
+ │ option = value # FIXME (what is location?)
+ └────
+
+
+6.4 usage as a program
+──────────────────────
+
+ FIXME: Is this supposed to be documented? Seems out of place in a
+ library. Maybe it's there only for testing purposes? Another idea is
+ to move it to its own utility program.
+
+ If ‘talerconfig.py’ is invoked from the command-line, it functions as
+ a program that displays either a specific value or dumps the entire
+ set, depending on the command-line args given.
+
+ Options are:
+
+ ‘-c, --config FILE’
+ Read Taler configuration from ‘FILE’. See ‘from_file’ (above)
+ for behavior if unspecified.
+
+ ‘-s, --section SECTION’
+ Look for option in section ‘SECTION’.
+
+ ‘-o, --option OPTION’
+ Display value associated with option ‘OPTION’.
+
+ ‘-f, --filename’
+ If the value is a string, do shell-style variable expansion (see
+ above) on it.
+
+ If both ‘SECTION’ and ‘OPTION’ are omitted, display the entire set of
+ values using the ‘dump’ method (see above).
--
To stop receiving notification emails like this one, please contact
gnunet@gnunet.org.