path: root/doc/doc.txt

			  ━━━━━━━━━━━━━━━━━━━━
			   TALER-UTIL LIBRARY

			   Taler Contributors
			  ━━━━━━━━━━━━━━━━━━━━


Table of Contents
─────────────────

1. classes overview
.. 1. amount (currency + value + fraction)
.. 2. logging
.. 3. ‘payto’ URI particularities
.. 4. configuration
2. classes for handling currency plus value plus fraction
.. 1. class ‘Amount’
.. 2. class ‘SignedAmount’
3. classes ‘LogDefinition’, ‘GnunetLoglevel’
4. class ‘GnunetLogger’
.. 1. log definition, environment variables
.. 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
aspects of Taler programming in the Python language.  This is
documentation for the library.

This file is in Org Mode format and can be processed (by Emacs) to
produce HTML, etc.  When we figure out *where* to put this
documentation, we can convert it to Sphinx (or whatever) format.
Ongoing discussion: <https://bugs.gnunet.org/view.php?id=6649>


1 classes overview
══════════════════

  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/.


1.1 amount (currency + value + fraction)
────────────────────────────────────────

  • CurrencyMismatchError(Exception)
  • AmountOverflowError(Exception)
  • AmountFormatError(Exception)
  • Amount
  • SignedAmount


1.2 logging
───────────

  • LogDefinition
  • GnunetLoglevel
  • GnunetLogger


1.3 ‘payto’ URI particularities
───────────────────────────────

  • PaytoFormatError(Exception)
  • PaytoParse


1.4 configuration
─────────────────

  • ConfigurationError(Exception)
  • ExpansionSyntaxError(Exception)
  • Entry
  • OptionDict(collections.defaultdict)
  • SectionDict(collections.defaultdict)
  • TalerConfig


2 classes for handling currency plus value plus fraction
════════════════════════════════════════════════════════

  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’
  represents the number 0.00000001, and the largest ‘FRACTION’ of
  99999999 represents the number 0.99999999).  If an amount is specified
  that exceeds these limits, the constructor throws an
  ‘AmountOverflowError’ exception.


2.1 class ‘Amount’
──────────────────

  The constructor takes three args: ‘currency’, ‘value’, ‘fraction’.

  ┌────
  │ >>> from taler.util.amount import Amount, SignedAmount
  │
  │ # KUDOS 10.50
  │ >>> amt = Amount ("KUDOS", 10, 50000000)
  │
  │ >>> amt
  │ Amount(currency='KUDOS', value=10, fraction=50000000)
  └────


  ‘Amount’ has three getter properties: ‘currency’, ‘value’, ‘fraction’.

  ┌────
  │ >>> amt.value, amt.fraction
  │ (10, 50000000)
  └────


  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.parse ("KUDOS:10.12345678")
  │ Amount(currency='KUDOS', value=10, fraction=12345678)
  └────


  An ‘Amount’ object supports addition and subtraction.  The ‘currency’
  property must match, otherwise the operation throws a
  ‘CurrencyMismatchError’ exception.

  ┌────
  │ >>> amt + amt
  │ Amount(currency='KUDOS', value=21, fraction=0)
  │
  │ >>> another = Amount ("KUDOS", 5, 42)
  │
  │ >>> amt - another
  │ Amount(currency='KUDOS', value=5, fraction=49999958)
  └────


  Note, however, that a subtraction that results in a numerically
  negative ‘value’ causes the operation to throw an
  ‘AmountOverflowError’ exception.

  ┌────
  │ >>> another - amt
  │ Traceback (most recent call last):
  │   File "<stdin>", line 1, in <module>
  │   File ".../amount.py", line 124, in __sub__
  │     raise AmountOverflowError()
  │ taler.util.amount.AmountOverflowError
  └────


  The method ‘stringify’ (which is also used in the ‘__str__’
  definition) takes optional keyword ‘pretty’ (default ‘False’) that
  changes the 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'
  └────


  The method ‘is_zero’ returns ‘True’ if the ‘Amount’ object has a zero
  ‘value’ component and a zero ‘fraction’ component.

  ┌────
  │ >>> amt.is_zero ()
  │ False
  └────


  An ‘Amount’ object can be numerically compared with another ‘Amount’
  for both equality and inequality.  Comparison can throw a
  ‘CurrencyMismatchError’ exception if both currencies are not the same.

  ┌────
  │ >>> amt > another
  │ True
  │
  │ >>> amt == another
  │ False
  └────


2.2 class ‘SignedAmount’
────────────────────────

  A ‘SignedAmount’ object is an /amount with a sign/.  It has properties
  ‘is_positive’ and ‘amount’.  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)
  └────


  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
  └────


  The ‘stringify’ method, like that for ‘Amount’, takes optional keyword
  ‘pretty’.  It always prefixes the output with either ‘+’ or ‘-’.

  ┌────
  │ >>> (p - q).stringify (pretty=False)
  │ '+KUDOS:5.49999958'
  │
  │ >>> (q - p).stringify (pretty=True)
  │ '-5.49999958 KUDOS'
  └────


  The classmethod ‘parse’ recognizes a leading ‘+’ or ‘-’, and
  additionally accepts a plain ‘CURRENCY:VALUE.FRACTION’ form as a
  positive ‘SignedAmount’.

  ┌────
  │ >>> 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
  └────


3 classes ‘LogDefinition’, ‘GnunetLoglevel’
═══════════════════════════════════════════

  These two classes are deliberately undocumented (until further
  notice).  They exist primarily to support the ‘GnunetLogger’ class.


4 class ‘GnunetLogger’
══════════════════════

  The ‘GnunetLogger’ class wraps the native ‘logging’ module and
  provides two primary entry points: the constructor and the ‘log’
  method.  It supports the usual list of /log levels/: ‘ERROR’,
  ‘WARNING’, ‘INFO’, ‘DEBUG’.


4.1 log definition, environment variables
─────────────────────────────────────────

  What to log is controlled by a /log definition/, lists of which are
  taken from one or both environment variables when the ‘GnunetLogger’
  object is initialized:

  • ‘GNUNET_FORCE_LOG’
  • ‘GNUNET_LOG’

  A log definition looks like:

  ┌────
  │ [component];[file];[function];[from_line[-to_line]];loglevel
  └────


  The ‘component’, ‘file’, ‘function’, and line information portions are
  optional; the ‘loglevel’ is required.  No portion may contain the ‘;’
  (semicolon) or ‘/’ (slash) character.  When a portion is omitted, it
  defaults to /all/ of that item.  The line information can be a single
  line number or a range, written in ‘LOW-HIGH’ format – note ‘-’
  (hyphen).  For example, a minimal log definition could be:

  ┌────
  │ ;;;;ERROR
  └────


  This example definition matches all components, all files, all
  functions, and all lines, but only the ‘ERROR’ log level.

  Multiple log definitions are specified by separating them with a ‘/’
  (slash) character.

  ┌────
  │ network;;;ERROR/database;;;DEBUG
  └────


  The difference between ‘GNUNET_FORCE_LOG’ and ‘GNUNET_LOG’ is that the
  former takes priority over the latter, in case of conflict.  Also,
  logging done via ‘GNUNET_FORCE_LOG’ respects environment variable
  ‘GNUNET_FORCE_LOGFILE’.


4.2 environment variable ‘GNUNET_FORCE_LOGFILE’
───────────────────────────────────────────────

  The filename specified by ‘GNUNET_FORCE_LOGFILE’ can have special
  character sequences replaced (like a template):

  ‘{}’
        component
  ‘[]’
        process id
  ‘%Y’
        numeric year
  ‘%m’
        numeric month
  ‘%d’
        numeric day

  For example, if ‘GNUNET_FORCE_LOGFILE’ has value:

  ┌────
  │ /var/log/[].{}.%Y-%m-%d.error.log
  └────


  then the expansion might be:

  ┌────
  │ /var/log/14916.monolith.2022-02-10.error.log
  └────


4.3 constructor
───────────────

  The ‘GnunetLogger’ constructor takes one argument, ‘component’.

  ┌────
  │ >>> from taler.util.gnunet_log import GnunetLogger
  │
  │ >>> l = GnunetLogger ("ui")
  └────


4.4 method ‘log’
────────────────

  The ‘log’ method takes two arguments, ‘message’ (a string) 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
  └────


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)
  └────