diff options
Diffstat (limited to 'doc/doc.txt')
| -rw-r--r-- | doc/doc.txt | 128 |
1 files changed, 109 insertions, 19 deletions
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) └──── |