Taler-Util Library

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

• LogDefinition
• GnunetLoglevel
• GnunetLogger

• PaytoFormatError(Exception)
• PaytoParse

• TalerConfig

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

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

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.

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

The GnunetLogger constructor takes one argument, component.

>>> from taler.util.gnunet_log import GnunetLogger

>>> l = GnunetLogger ("ui")

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

The standard way to construct a TalerConfig object is to start with one of two initialization methods: from_file or from_env. The former reads the configuration from a file, given its name. If no name is provided (it is None), from_file first tries to find taler.conf in two directories:

• directory named by environment variable XDG_CONFIG_HOME
• $HOME/.config (where HOME is the user's home directory)

The from_env initialization method first determines a filename by consulting environment variable TALER_CONFIG_FILE and then uses from_file on that.

Both initialization methods take keyword arg load_defaults (default True) that directs the method to also call the load_defaults method before reading the file.

The load_defaults method takes no arguments. It looks in the canonical locations (directories) and uses method load_dir on them. Once it finds a specified dir, it stops searching. The canonical locations are:

• environment variable TALER_BASE_CONFIG

• environment variable TALER_PREFIX, with any trailing component lib discarded, and suffixed with share/taler/config.d

  For example, if TALER_PREFIX is /usr/local/lib, then load_defaults would look in /usr/local/share/taler/config.d. The same would result if TALER_PREFIX were /usr/local (the suffixing is unconditional).

If load_defaults cannot find something to load it logs a warning "no base directory found".

The load_dir method takes one argument dirname, and uses load_file on all files that directory whose name ends with .conf.

At its core, all file reading uses method load_file, which takes one argument, the filename to read. If filename cannot be found, load_file causes the process to exit with exit value 3.

There are three types of values in a Taler configuration: int (integer), string and filename. The int and string types are self-explanatory. The filename type is a string that has certain constructs expanded:

• ${X}
• ${X:-Y}
• $X

These mimic shell-style variable expansion. In all these constructs, the value of X replaces the construct. In the second one only, if the value of X is empty, use the value of Y instead. Also, the second type can be nested, i.e., ${X:-${Y:-Z}}. That is, if X is empty, try Y, and if Y is empty, try Z.

For example, ${TMPDIR:-/tmp}/taler-test expands to /var/tmp/taler-test if environment variable TMPDIR has value /var/tmp, otherwise simply /tmp/taler-test.

Once a Taler configuration is read, you can retrieve specific values from it, or display the entire set to stdout.

[section]
option = value # filename & line number pair