[Date Prev][Date Next][Thread Prev][Thread Next][Date Index][Thread Index]
[taler-taler-util] branch master updated (35bc3d7 -> 262b998)
|
From: |
gnunet |
|
Subject: |
[taler-taler-util] branch master updated (35bc3d7 -> 262b998) |
|
Date: |
Fri, 11 Feb 2022 01:45:22 +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 35bc3d7 regenerate doc.{html,txt}
new f50b0e3 touch up ‘Amount’, ‘SignedAmount’ section
new c28684f change markup for Amount ctor args, properties from / to =
new 31c967a touch up ‘GnunetLogger’ section
new 4d3b4e6 include "+ fraction" in subheading
new 2c0b6e7 add vertical space to example blocks
new 1fd2db7 add documentation for payto.py
new 262b998 regenerate doc.{html,txt}
The 7 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 | 212 +++++++++++++++++++++++++++++++++++++++++++----------------
doc/doc.org | 104 +++++++++++++++++++++++++----
doc/doc.txt | 128 ++++++++++++++++++++++++++++++------
3 files changed, 355 insertions(+), 89 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.org b/doc/doc.org
index e0905db..81b242a 100644
--- a/doc/doc.org
+++ b/doc/doc.org
@@ -19,7 +19,7 @@ Several of these derive from the =Exception= class, and two
of them derive from the =collections.defaultdict= class.
The rest are /leaf classes/.
-*** amount (currency + value)
+*** amount (currency + value + fraction)
- CurrencyMismatchError(Exception)
- AmountOverflowError(Exception)
@@ -47,11 +47,17 @@ The rest are /leaf classes/.
- SectionDict(collections.defaultdict)
- TalerConfig
-* classes =Amount=, =SignedAmount=
+* 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
@@ -62,15 +68,17 @@ the constructor throws an =AmountOverflowError= exception.
*** 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
: (10, 50000000)
@@ -79,7 +87,7 @@ You can use classmethod =parse= to read a string as an
=Amount= object.
This function can throw =AmountFormatError= if the string is malformed,
and =AmountOverflowError= if the fraction portion is too long.
-: >>> amount.Amount.parse ("KUDOS:10.12345678")
+: >>> Amount.parse ("KUDOS:10.12345678")
: Amount(currency='KUDOS', value=10, fraction=12345678)
An =Amount= object supports addition and subtraction.
@@ -88,7 +96,9 @@ a =CurrencyMismatchError= exception.
: >>> 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)
@@ -108,10 +118,13 @@ output.
: >>> str (amt)
: 'KUDOS:10.5'
+:
: >>> amt.stringify()
: 'KUDOS:10.5'
+:
: >>> amt.stringify(pretty=True)
: '10.5 KUDOS'
+:
: >>> (amt + amt).stringify(pretty=True)
: '21 KUDOS'
@@ -128,6 +141,7 @@ if both currencies are not the same.
: >>> amt > another
: True
+:
: >>> amt == another
: False
@@ -139,8 +153,10 @@ You can derive a =SignedAmount= from a simple =Amount=
with the
=as_signed= method.
: >>> p = amt.as_signed ()
+:
: >>> p.is_positive
: True
+:
: >>> p.amount
: Amount(currency='KUDOS', value=10, fraction=50000000)
@@ -148,8 +164,10 @@ A =SignedAmount= object supports addition, subtraction,
and comparison
(equality and inequality) with another =SignedAmount= object.
: >>> q = another.as_signed ()
+:
: >>> (p - q).is_positive
: True
+:
: >>> (q - p).is_positive
: False
@@ -158,6 +176,7 @@ The =stringify= method, like that for =Amount=, takes
optional keyword
: >>> (p - q).stringify (pretty=False)
: '+KUDOS:5.49999958'
+:
: >>> (q - p).stringify (pretty=True)
: '-5.49999958 KUDOS'
@@ -165,14 +184,16 @@ The classmethod =parse= recognizes a leading =+= or =-=,
and
additionally accepts a plain =CURRENCY:VALUE.FRACTION= form as a
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))
Lastly, a =SignedAmount= object can flip its sign using a unary minus.
: >>> n = q - p
+:
: >>> n.is_positive
: False
+:
: >>> (- n).is_positive
: True
@@ -247,8 +268,9 @@ then the expansion might be:
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")
*** method =log=
@@ -257,3 +279,57 @@ 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)
+: INFO:ui:user clicked button
+
+* ‘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 ([[class =Amount=]])
+
+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)
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 <=
- [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, 2022/02/10