diff options
| author | Thien-Thi Nguyen <ttn@gnu.org> | 2022-02-10 19:45:12 -0500 |
|---|---|---|
| committer | Thien-Thi Nguyen <ttn@gnu.org> | 2022-02-10 19:45:12 -0500 |
| commit | 262b998bcc714ede4e1b816327a6dede4d03fbdc (patch) | |
| tree | 13cd520f81d182ba15031c1846fb70b88155998f | |
| parent | 1fd2db7e26c0078c3b013eab7a67f74355aa469f (diff) | |
| download | taler-util-262b998bcc714ede4e1b816327a6dede4d03fbdc.tar.gz taler-util-262b998bcc714ede4e1b816327a6dede4d03fbdc.tar.bz2 taler-util-262b998bcc714ede4e1b816327a6dede4d03fbdc.zip | |
regenerate doc.{html,txt}
| -rw-r--r-- | doc/doc.html | 212 | ||||
| -rw-r--r-- | 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) └──── |