[Date Prev][Date Next][Thread Prev][Thread Next][Date Index][Thread Index]
[taler-taler-util] branch master updated (de04cff -> 932f8dc)
|
From: |
gnunet |
|
Subject: |
[taler-taler-util] branch master updated (de04cff -> 932f8dc) |
|
Date: |
Tue, 15 Feb 2022 14:21:37 +0100 |
This is an automated email from the git hooks/post-receive script.
ttn pushed a change to branch master
in repository taler-util.
from de04cff Don't bother documenting some classes in talerconfig.py
new 943817d add documentation for talerconfig.py
new 932f8dc regenerate doc.{html,txt}
The 2 revisions listed above as "new" are entirely new to this
repository and will be described in separate emails. The revisions
listed as "add" were already present in the repository and have only
been added to this reference.
Summary of changes:
doc/doc.html | 351 +++++++++++++++++++++++++++++++++++++++++++++++++----------
doc/doc.org | 149 +++++++++++++++++++++++++
doc/doc.txt | 182 +++++++++++++++++++++++++++++--
3 files changed, 619 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.org b/doc/doc.org
index fe4231b..ca727f3 100644
--- a/doc/doc.org
+++ b/doc/doc.org
@@ -327,3 +327,152 @@ It's necessary to use the /two-component/ IBAN.
:
: >>> p.amount
: Amount(currency='EUR', value=200, fraction=0)
+
+* 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.
+
+*** 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=.
+
+*** 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=.
+
+*** retrieving values
+
+Once a Taler configuration is read, you can retrieve specific
+values from it, or display the entire set to stdout.
+
+***** 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.)
+
+***** 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?)
+
+*** 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).
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.
- [taler-taler-util] branch master updated (de04cff -> 932f8dc),
gnunet <=