[Date Prev][Date Next][Thread Prev][Thread Next][Date Index][Thread Index]
[taler-taler-util] 07/07: regenerate doc.{html,txt}
|
From: |
gnunet |
|
Subject: |
[taler-taler-util] 07/07: regenerate doc.{html,txt} |
|
Date: |
Fri, 11 Feb 2022 01:45:29 +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 262b998bcc714ede4e1b816327a6dede4d03fbdc
Author: Thien-Thi Nguyen <ttn@gnu.org>
AuthorDate: Thu Feb 10 19:45:12 2022 -0500
regenerate doc.{html,txt}
---
doc/doc.html | 212 +++++++++++++++++++++++++++++++++++++++++++----------------
doc/doc.txt | 128 ++++++++++++++++++++++++++++++------
2 files changed, 265 insertions(+), 75 deletions(-)
diff --git a/doc/doc.html b/doc/doc.html
index ba1c046..8a8bfa3 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 17:57 -->
+<!-- 2022-02-10 gio 19:44 -->
<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,29 +247,30 @@ for the JavaScript code in this tag.
<h2>Table of Contents</h2>
<div id="text-table-of-contents">
<ul>
-<li><a href="#orgd6eca49">1. classes overview</a>
+<li><a href="#orgca83dbe">1. classes overview</a>
<ul>
-<li><a href="#orged123c6">1.1. amount (currency + value)</a></li>
-<li><a href="#orgcb24ca2">1.2. logging</a></li>
-<li><a href="#org7ff0a2e">1.3. ‘payto’ URI particularities</a></li>
-<li><a href="#org88b1f10">1.4. configuration</a></li>
+<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>
</ul>
</li>
-<li><a href="#org322086d">2. classes <code>Amount</code>,
<code>SignedAmount</code></a>
+<li><a href="#org1f4e090">2. classes for handling currency plus value plus
fraction</a>
<ul>
-<li><a href="#orgcf6310f">2.1. class <code>Amount</code></a></li>
-<li><a href="#orgeedb87a">2.2. class <code>SignedAmount</code></a></li>
+<li><a href="#orgc5c5b05">2.1. class <code>Amount</code></a></li>
+<li><a href="#org75fe6af">2.2. class <code>SignedAmount</code></a></li>
</ul>
</li>
-<li><a href="#org287a274">3. classes <code>LogDefinition</code>,
<code>GnunetLoglevel</code></a></li>
-<li><a href="#org7c1b43d">4. class <code>GnunetLogger</code></a>
+<li><a href="#orgc5d0f9f">3. classes <code>LogDefinition</code>,
<code>GnunetLoglevel</code></a></li>
+<li><a href="#orga09fc8a">4. class <code>GnunetLogger</code></a>
<ul>
-<li><a href="#org324e052">4.1. log definition, environment variables</a></li>
-<li><a href="#org4f2f7a6">4.2. environment variable
<code>GNUNET_FORCE_LOGFILE</code></a></li>
-<li><a href="#orgfe85beb">4.3. constructor</a></li>
-<li><a href="#orgf59bde3">4.4. method <code>log</code></a></li>
+<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>
</ul>
</li>
+<li><a href="#org9a25003">5. ‘payto’ URI parsing</a></li>
</ul>
</div>
</div>
@@ -286,8 +287,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-orgd6eca49" class="outline-2">
-<h2 id="orgd6eca49"><span class="section-number-2">1</span> classes
overview</h2>
+<div id="outline-container-orgca83dbe" class="outline-2">
+<h2 id="orgca83dbe"><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)
@@ -301,8 +302,8 @@ The rest are <i>leaf classes</i>.
</p>
</div>
-<div id="outline-container-orged123c6" class="outline-3">
-<h3 id="orged123c6"><span class="section-number-3">1.1</span> amount (currency
+ value)</h3>
+<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 class="outline-text-3" id="text-1-1">
<ul class="org-ul">
<li>CurrencyMismatchError(Exception)</li>
@@ -314,8 +315,8 @@ The rest are <i>leaf classes</i>.
</div>
</div>
-<div id="outline-container-orgcb24ca2" class="outline-3">
-<h3 id="orgcb24ca2"><span class="section-number-3">1.2</span> logging</h3>
+<div id="outline-container-org44f0451" class="outline-3">
+<h3 id="org44f0451"><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>
@@ -325,8 +326,8 @@ The rest are <i>leaf classes</i>.
</div>
</div>
-<div id="outline-container-org7ff0a2e" class="outline-3">
-<h3 id="org7ff0a2e"><span class="section-number-3">1.3</span> ‘payto’ URI
particularities</h3>
+<div id="outline-container-org6c994e8" class="outline-3">
+<h3 id="org6c994e8"><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>
@@ -335,8 +336,8 @@ The rest are <i>leaf classes</i>.
</div>
</div>
-<div id="outline-container-org88b1f10" class="outline-3">
-<h3 id="org88b1f10"><span class="section-number-3">1.4</span>
configuration</h3>
+<div id="outline-container-org25aab70" class="outline-3">
+<h3 id="org25aab70"><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>
@@ -350,13 +351,24 @@ The rest are <i>leaf classes</i>.
</div>
</div>
-<div id="outline-container-org322086d" class="outline-2">
-<h2 id="org322086d"><span class="section-number-2">2</span> classes
<code>Amount</code>, <code>SignedAmount</code></h2>
+<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 class="outline-text-2" id="text-2">
<p>
-These classes handle Taler <i>amounts</i>, objects referred to in the format
-<code>CURRENCY:VALUE.FRACTION</code>, where <code>CURRENCY</code> is the
currency designation
-abbreviation (e.g., "KUDOS"), and <code>VALUE</code> and <code>FRACTION</code>
are integers.
+The <code>Amount</code> and <code>SignedAmount</code> handle Taler
<i>amounts</i>,
+objects that combine a <code>CURRENCY</code> (e.g., "KUDOS")
+with a <code>VALUE</code> and <code>FRACTION</code> (both integers).
+An amount is written as follows:
+</p>
+
+<pre class="example">
+CURRENCY:VALUE.FRACTION
+</pre>
+
+
+<p>
+Note the <code>:</code> (colon) and <code>.</code> (period).
+This is also known as the <code>CUR:X.Y</code> format.
</p>
<p>
@@ -369,24 +381,26 @@ the constructor throws an
<code>AmountOverflowError</code> exception.
</p>
</div>
-<div id="outline-container-orgcf6310f" class="outline-3">
-<h3 id="orgcf6310f"><span class="section-number-3">2.1</span> class
<code>Amount</code></h3>
+<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 class="outline-text-3" id="text-2-1">
<p>
-The constructor takes three args: <i>currency</i>, <i>value</i>,
<i>fraction</i>.
+The constructor takes three args: <code>currency</code>, <code>value</code>,
<code>fraction</code>.
</p>
<pre class="example">
->>> from taler.util import amount
+>>> from taler.util.amount import Amount, SignedAmount
+
# KUDOS 10.50
->>> amt = amount.Amount ("KUDOS", 10, 50000000)
+>>> amt = Amount ("KUDOS", 10, 50000000)
+
>>> amt
Amount(currency='KUDOS', value=10, fraction=50000000)
</pre>
<p>
-<code>Amount</code> has three getter properties: <i>currency</i>,
<i>value</i>, <i>fraction</i>.
+<code>Amount</code> has three getter properties: <code>currency</code>,
<code>value</code>, <code>fraction</code>.
</p>
<pre class="example">
@@ -402,7 +416,7 @@ and <code>AmountOverflowError</code> if the fraction
portion is too long.
</p>
<pre class="example">
->>> amount.Amount.parse ("KUDOS:10.12345678")
+>>> Amount.parse ("KUDOS:10.12345678")
Amount(currency='KUDOS', value=10, fraction=12345678)
</pre>
@@ -416,7 +430,9 @@ a <code>CurrencyMismatchError</code> exception.
<pre class="example">
>>> amt + amt
Amount(currency='KUDOS', value=21, fraction=0)
->>> another = amount.Amount ("KUDOS", 5, 42)
+
+>>> another = Amount ("KUDOS", 5, 42)
+
>>> amt - another
Amount(currency='KUDOS', value=5, fraction=49999958)
</pre>
@@ -446,10 +462,13 @@ output.
<pre class="example">
>>> str (amt)
'KUDOS:10.5'
+
>>> amt.stringify()
'KUDOS:10.5'
+
>>> amt.stringify(pretty=True)
'10.5 KUDOS'
+
>>> (amt + amt).stringify(pretty=True)
'21 KUDOS'
</pre>
@@ -476,14 +495,15 @@ if both currencies are not the same.
<pre class="example">
>>> amt > another
True
+
>>> amt == another
False
</pre>
</div>
</div>
-<div id="outline-container-orgeedb87a" class="outline-3">
-<h3 id="orgeedb87a"><span class="section-number-3">2.2</span> class
<code>SignedAmount</code></h3>
+<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 class="outline-text-3" id="text-2-2">
<p>
A <code>SignedAmount</code> object is an <i>amount with a sign</i>.
@@ -494,8 +514,10 @@ You can derive a <code>SignedAmount</code> from a simple
<code>Amount</code> wit
<pre class="example">
>>> p = amt.as_signed ()
+
>>> p.is_positive
True
+
>>> p.amount
Amount(currency='KUDOS', value=10, fraction=50000000)
</pre>
@@ -508,8 +530,10 @@ A <code>SignedAmount</code> object supports addition,
subtraction, and compariso
<pre class="example">
>>> q = another.as_signed ()
+
>>> (p - q).is_positive
True
+
>>> (q - p).is_positive
False
</pre>
@@ -523,6 +547,7 @@ The <code>stringify</code> method, like that for
<code>Amount</code>, takes opti
<pre class="example">
>>> (p - q).stringify (pretty=False)
'+KUDOS:5.49999958'
+
>>> (q - p).stringify (pretty=True)
'-5.49999958 KUDOS'
</pre>
@@ -535,7 +560,7 @@ positive <code>SignedAmount</code>.
</p>
<pre class="example">
->>> amount.SignedAmount.parse ("-KUDOS:2.34")
+>>> SignedAmount.parse ("-KUDOS:2.34")
SignedAmount(is_positive=False, amount=Amount(currency='KUDOS', value=2,
fraction=34000000))
</pre>
@@ -546,8 +571,10 @@ Lastly, a <code>SignedAmount</code> object can flip its
sign using a unary minus
<pre class="example">
>>> n = q - p
+
>>> n.is_positive
False
+
>>> (- n).is_positive
True
</pre>
@@ -555,8 +582,8 @@ True
</div>
</div>
-<div id="outline-container-org287a274" class="outline-2">
-<h2 id="org287a274"><span class="section-number-2">3</span> classes
<code>LogDefinition</code>, <code>GnunetLoglevel</code></h2>
+<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 class="outline-text-2" id="text-3">
<p>
These two classes are deliberately undocumented (until further notice).
@@ -565,8 +592,8 @@ They exist primarily to support the
<code>GnunetLogger</code> class.
</div>
</div>
-<div id="outline-container-org7c1b43d" class="outline-2">
-<h2 id="org7c1b43d"><span class="section-number-2">4</span> class
<code>GnunetLogger</code></h2>
+<div id="outline-container-orga09fc8a" class="outline-2">
+<h2 id="orga09fc8a"><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
@@ -576,8 +603,8 @@ It supports the usual list of <i>log levels</i>:
</p>
</div>
-<div id="outline-container-org324e052" class="outline-3">
-<h3 id="org324e052"><span class="section-number-3">4.1</span> log definition,
environment variables</h3>
+<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 class="outline-text-3" id="text-4-1">
<p>
What to log is controlled by a <i>log definition</i>, lists of
@@ -638,8 +665,8 @@ variable <code>GNUNET_FORCE_LOGFILE</code>.
</div>
</div>
-<div id="outline-container-org4f2f7a6" class="outline-3">
-<h3 id="org4f2f7a6"><span class="section-number-3">4.2</span> environment
variable <code>GNUNET_FORCE_LOGFILE</code></h3>
+<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 class="outline-text-3" id="text-4-2">
<p>
The filename specified by <code>GNUNET_FORCE_LOGFILE</code> can
@@ -673,22 +700,23 @@ then the expansion might be:
</div>
</div>
-<div id="outline-container-orgfe85beb" class="outline-3">
-<h3 id="orgfe85beb"><span class="section-number-3">4.3</span> constructor</h3>
+<div id="outline-container-org9663b14" class="outline-3">
+<h3 id="org9663b14"><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")
+>>> from taler.util.gnunet_log import GnunetLogger
+
+>>> l = GnunetLogger ("ui")
</pre>
</div>
</div>
-<div id="outline-container-orgf59bde3" class="outline-3">
-<h3 id="orgf59bde3"><span class="section-number-3">4.4</span> method
<code>log</code></h3>
+<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 class="outline-text-3" id="text-4-4">
<p>
The <code>log</code> method takes two arguments, <code>message</code> (a
string)
@@ -698,14 +726,86 @@ the same name as the string log level).
<pre class="example">
>>> l.log ("user clicked button", l.INFO)
+INFO:ui:user clicked button
</pre>
</div>
</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 class="outline-text-2" id="text-5">
+<p>
+The <code>PaytoParse</code> class has only one entry point, its constructor.
+The argument is <code>payto_uri</code>, a string in the <i>payto URI scheme</i>
+that has exactly two components in the <i>upath</i> portion.
+See RFC 8905 (<a
href="https://datatracker.ietf.org/doc/html/rfc8905";>https://datatracker.ietf.org/doc/html/rfc8905</a>)
for more info.
+If parsing fails, the constructor throws a <code>PaytoFormatError</code>
exception.
+</p>
+
+<p>
+On successful parse, the object has the following properties:
+</p>
+
+<dl class="org-dl">
+<dt><code>target</code></dt><dd>destination of the payment</dd>
+<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>
+</dl>
+
+<p>
+Note that <code>amount</code> may be <code>None</code> if none was specified.
+</p>
+
+<pre class="example">
+>>> from taler.util.payto import PaytoParse
+
+# from RFC 8905
+>>> uri =
"payto://iban/DE75512108001245126199?amount=EUR:200.0&message=hello"
+
+>>> p = PaytoParse (uri)
+Traceback (most recent call last):
+ File "<stdin>", line 1, in <module>
+ File "/home/ttn/build/GNU/T/taler-util/taler/util/payto.py", line 41, in
__init__
+ raise PaytoFormatError(f"Bad Payto URI: {payto_uri}")
+taler.util.payto.PaytoFormatError: Bad Payto URI:
payto://iban/DE75512108001245126199?amount=EUR:200.0&message=hello
+</pre>
+
+
+<p>
+This example shows that the <i>single-component</i> IBAN fails to parse
+(even though that is a valid RFC 8905 ‘payto’ URI).
+It's necessary to use the <i>two-component</i> IBAN.
+</p>
+
+<pre class="example">
+>>> uri =
"payto://iban/SOGEDEFFXXX/DE75512108001245126199?amount=EUR:200.0&message=hello"
+
+>>> p = PaytoParse (uri)
+
+>>> p.target
+'DE75512108001245126199'
+
+>>> p.bank
+'SOGEDEFFXXX'
+
+>>> p.authority
+'iban'
+
+>>> p.message
+'hello'
+
+>>> p.amount
+Amount(currency='EUR', value=200, fraction=0)
+</pre>
+</div>
+</div>
</div>
<div id="postamble" class="status">
<p class="author">Author: Taler Contributors</p>
-<p class="date">Created: 2022-02-10 gio 17:57</p>
+<p class="date">Created: 2022-02-10 gio 19:44</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 28eda85..b3b3350 100644
--- a/doc/doc.txt
+++ b/doc/doc.txt
@@ -9,11 +9,11 @@ Table of Contents
─────────────────
1. classes overview
-.. 1. amount (currency + value)
+.. 1. amount (currency + value + fraction)
.. 2. logging
.. 3. ‘payto’ URI particularities
.. 4. configuration
-2. classes ‘Amount’, ‘SignedAmount’
+2. classes for handling currency plus value plus fraction
.. 1. class ‘Amount’
.. 2. class ‘SignedAmount’
3. classes ‘LogDefinition’, ‘GnunetLoglevel’
@@ -22,6 +22,7 @@ Table of Contents
.. 2. environment variable ‘GNUNET_FORCE_LOGFILE’
.. 3. constructor
.. 4. method ‘log’
+5. ‘payto’ URI parsing
The Taler-Util library provides several classes that deal with various
@@ -45,8 +46,8 @@ Ongoing discussion: <https://bugs.gnunet.org/view.php?id=6649>
classes/.
-1.1 amount (currency + value)
-─────────────────────────────
+1.1 amount (currency + value + fraction)
+────────────────────────────────────────
• CurrencyMismatchError(Exception)
• AmountOverflowError(Exception)
@@ -81,13 +82,20 @@ Ongoing discussion:
<https://bugs.gnunet.org/view.php?id=6649>
• TalerConfig
-2 classes ‘Amount’, ‘SignedAmount’
-══════════════════════════════════
+2 classes for handling currency plus value plus fraction
+════════════════════════════════════════════════════════
- These classes handle Taler /amounts/, objects referred to in the
- format ‘CURRENCY:VALUE.FRACTION’, where ‘CURRENCY’ is the currency
- designation abbreviation (e.g., "KUDOS"), and ‘VALUE’ and ‘FRACTION’
- are integers.
+ The ‘Amount’ and ‘SignedAmount’ handle Taler /amounts/, objects that
+ combine a ‘CURRENCY’ (e.g., "KUDOS") with a ‘VALUE’ and ‘FRACTION’
+ (both integers). An amount is written as follows:
+
+ ┌────
+ │ CURRENCY:VALUE.FRACTION
+ └────
+
+
+ Note the ‘:’ (colon) and ‘.’ (period). This is also known as the
+ ‘CUR:X.Y’ format.
The maximum ‘VALUE’ is 2^52 (i.e., 4503599627370496). The ‘FRACTION’
can be at most 8 digits (i.e., smallest non-zero ‘FRACTION’ of ‘1’
@@ -100,18 +108,20 @@ Ongoing discussion:
<https://bugs.gnunet.org/view.php?id=6649>
2.1 class ‘Amount’
──────────────────
- The constructor takes three args: /currency/, /value/, /fraction/.
+ The constructor takes three args: ‘currency’, ‘value’, ‘fraction’.
┌────
- │ >>> from taler.util import amount
+ │ >>> from taler.util.amount import Amount, SignedAmount
+ │
│ # KUDOS 10.50
- │ >>> amt = amount.Amount ("KUDOS", 10, 50000000)
+ │ >>> amt = Amount ("KUDOS", 10, 50000000)
+ │
│ >>> amt
│ Amount(currency='KUDOS', value=10, fraction=50000000)
└────
- ‘Amount’ has three getter properties: /currency/, /value/, /fraction/.
+ ‘Amount’ has three getter properties: ‘currency’, ‘value’, ‘fraction’.
┌────
│ >>> amt.value, amt.fraction
@@ -125,7 +135,7 @@ Ongoing discussion:
<https://bugs.gnunet.org/view.php?id=6649>
long.
┌────
- │ >>> amount.Amount.parse ("KUDOS:10.12345678")
+ │ >>> Amount.parse ("KUDOS:10.12345678")
│ Amount(currency='KUDOS', value=10, fraction=12345678)
└────
@@ -137,7 +147,9 @@ Ongoing discussion:
<https://bugs.gnunet.org/view.php?id=6649>
┌────
│ >>> amt + amt
│ Amount(currency='KUDOS', value=21, fraction=0)
- │ >>> another = amount.Amount ("KUDOS", 5, 42)
+ │
+ │ >>> another = Amount ("KUDOS", 5, 42)
+ │
│ >>> amt - another
│ Amount(currency='KUDOS', value=5, fraction=49999958)
└────
@@ -164,10 +176,13 @@ Ongoing discussion:
<https://bugs.gnunet.org/view.php?id=6649>
┌────
│ >>> str (amt)
│ 'KUDOS:10.5'
+ │
│ >>> amt.stringify()
│ 'KUDOS:10.5'
+ │
│ >>> amt.stringify(pretty=True)
│ '10.5 KUDOS'
+ │
│ >>> (amt + amt).stringify(pretty=True)
│ '21 KUDOS'
└────
@@ -189,6 +204,7 @@ Ongoing discussion:
<https://bugs.gnunet.org/view.php?id=6649>
┌────
│ >>> amt > another
│ True
+ │
│ >>> amt == another
│ False
└────
@@ -203,8 +219,10 @@ Ongoing discussion:
<https://bugs.gnunet.org/view.php?id=6649>
┌────
│ >>> p = amt.as_signed ()
+ │
│ >>> p.is_positive
│ True
+ │
│ >>> p.amount
│ Amount(currency='KUDOS', value=10, fraction=50000000)
└────
@@ -215,8 +233,10 @@ Ongoing discussion:
<https://bugs.gnunet.org/view.php?id=6649>
┌────
│ >>> q = another.as_signed ()
+ │
│ >>> (p - q).is_positive
│ True
+ │
│ >>> (q - p).is_positive
│ False
└────
@@ -228,6 +248,7 @@ Ongoing discussion:
<https://bugs.gnunet.org/view.php?id=6649>
┌────
│ >>> (p - q).stringify (pretty=False)
│ '+KUDOS:5.49999958'
+ │
│ >>> (q - p).stringify (pretty=True)
│ '-5.49999958 KUDOS'
└────
@@ -238,7 +259,7 @@ Ongoing discussion:
<https://bugs.gnunet.org/view.php?id=6649>
positive ‘SignedAmount’.
┌────
- │ >>> amount.SignedAmount.parse ("-KUDOS:2.34")
+ │ >>> SignedAmount.parse ("-KUDOS:2.34")
│ SignedAmount(is_positive=False, amount=Amount(currency='KUDOS', value=2,
fraction=34000000))
└────
@@ -247,8 +268,10 @@ Ongoing discussion:
<https://bugs.gnunet.org/view.php?id=6649>
┌────
│ >>> n = q - p
+ │
│ >>> n.is_positive
│ False
+ │
│ >>> (- n).is_positive
│ True
└────
@@ -353,8 +376,9 @@ Ongoing discussion:
<https://bugs.gnunet.org/view.php?id=6649>
The ‘GnunetLogger’ constructor takes one argument, ‘component’.
┌────
- │ >>> from taler.util import gnunet_log
- │ >>> l = gnunet_log.GnunetLogger ("ui")
+ │ >>> from taler.util.gnunet_log import GnunetLogger
+ │
+ │ >>> l = GnunetLogger ("ui")
└────
@@ -367,4 +391,70 @@ Ongoing discussion:
<https://bugs.gnunet.org/view.php?id=6649>
┌────
│ >>> l.log ("user clicked button", l.INFO)
+ │ INFO:ui:user clicked button
+ └────
+
+
+5 ‘payto’ URI parsing
+═════════════════════
+
+ The ‘PaytoParse’ class has only one entry point, its constructor. The
+ argument is ‘payto_uri’, a string in the /payto URI scheme/ that has
+ exactly two components in the /upath/ portion. See RFC 8905
+ (<https://datatracker.ietf.org/doc/html/rfc8905>) for more info. If
+ parsing fails, the constructor throws a ‘PaytoFormatError’ exception.
+
+ On successful parse, the object has the following properties:
+
+ ‘target’
+ destination of the payment
+ ‘bank’
+ bank handling the payment
+ ‘authority’
+ payment type (e.g., ‘iban’)
+ ‘message’
+ short human-readable description of the payment
+ ‘amount’
+ in ‘CUR:X.Y’ format (2.1)
+
+ Note that ‘amount’ may be ‘None’ if none was specified.
+
+ ┌────
+ │ >>> from taler.util.payto import PaytoParse
+ │
+ │ # from RFC 8905
+ │ >>> uri =
"payto://iban/DE75512108001245126199?amount=EUR:200.0&message=hello"
+ │
+ │ >>> p = PaytoParse (uri)
+ │ Traceback (most recent call last):
+ │ File "<stdin>", line 1, in <module>
+ │ File "/home/ttn/build/GNU/T/taler-util/taler/util/payto.py", line 41, in
__init__
+ │ raise PaytoFormatError(f"Bad Payto URI: {payto_uri}")
+ │ taler.util.payto.PaytoFormatError: Bad Payto URI:
payto://iban/DE75512108001245126199?amount=EUR:200.0&message=hello
+ └────
+
+
+ This example shows that the /single-component/ IBAN fails to parse
+ (even though that is a valid RFC 8905 ‘payto’ URI). It's necessary to
+ use the /two-component/ IBAN.
+
+ ┌────
+ │ >>> uri =
"payto://iban/SOGEDEFFXXX/DE75512108001245126199?amount=EUR:200.0&message=hello"
+ │
+ │ >>> p = PaytoParse (uri)
+ │
+ │ >>> p.target
+ │ 'DE75512108001245126199'
+ │
+ │ >>> p.bank
+ │ 'SOGEDEFFXXX'
+ │
+ │ >>> p.authority
+ │ 'iban'
+ │
+ │ >>> p.message
+ │ 'hello'
+ │
+ │ >>> p.amount
+ │ Amount(currency='EUR', value=200, fraction=0)
└────
--
To stop receiving notification emails like this one, please contact
gnunet@gnunet.org.
- [taler-taler-util] branch master updated (35bc3d7 -> 262b998), gnunet, 2022/02/10
- [taler-taler-util] 02/07: change markup for Amount ctor args, properties from / to =, gnunet, 2022/02/10
- [taler-taler-util] 04/07: include "+ fraction" in subheading, gnunet, 2022/02/10
- [taler-taler-util] 03/07: touch up ‘GnunetLogger’ section, gnunet, 2022/02/10
- [taler-taler-util] 01/07: touch up ‘Amount’, ‘SignedAmount’ section, gnunet, 2022/02/10
- [taler-taler-util] 05/07: add vertical space to example blocks, gnunet, 2022/02/10
- [taler-taler-util] 06/07: add documentation for payto.py, gnunet, 2022/02/10
- [taler-taler-util] 07/07: regenerate doc.{html,txt},
gnunet <=