[taler-taler-util] 01/02: add documentation for talerconfig.py

[gnunet]

This is an automated email from the git hooks/post-receive script.

ttn pushed a commit to branch master
in repository taler-util.

commit 943817d37b8dcaf26771879c415e7a8841ec3e1a
Author: Thien-Thi Nguyen <ttn@gnuvola.org>
AuthorDate: Tue Feb 15 08:19:56 2022 -0500

    add documentation for talerconfig.py
---
 doc/doc.org | 149 ++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++
 1 file changed, 149 insertions(+)

diff --git a/doc/doc.org b/doc/doc.org
index fe4231b..ca727f3 100644
--- a/doc/doc.org
+++ b/doc/doc.org
@@ -327,3 +327,152 @@ It's necessary to use the /two-component/ IBAN.
 :
 : >>> p.amount
 : Amount(currency='EUR', value=200, fraction=0)
+
+* class =TalerConfig=
+
+The =TalerConfig= class represents a /Taler configuration/, a set
+of /sections/ with /options/ and associated /values/ (basically,
+a nested dictionary), and provides methods for initializing,
+and accessing those values, keyed by section and option.
+
+When a Taler configuration is written to a file (the usual case),
+it follows the typical Windows INI format.
+For more information, see the taler-config(5) manpage.
+
+*** reading
+
+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 module =talerpaths= exists and exports =TALER_DATADIR=, then the
+  directory named by suffixing its value with =share/taler/config.d=
+
+  FIXME: Comment in code: "not clear if this is a good idea" --
+  Maybe we should remove this functionality or leave it undocumented?
+
+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=.
+
+*** value types
+
+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.
+
+FIXME: Can the second type be nested (i.e., =${X:-${Y:-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=.
+
+*** retrieving values
+
+Once a Taler configuration is read, you can retrieve specific
+values from it, or display the entire set to stdout.
+
+***** specific values
+
+Each type /foo/ has a =value_foo= method (e.g., =value_int= for integer).
+The method takes two required arguments, the =section= and =option=,
+both strings.
+Case does not matter.
+
+In addition to the required arguments, =value_string= accepts
+the following keyword arguments:
+
+- =default= :: If the requested value is not found, return this
+  value instead.  Default is no default.  :-D
+
+- =required= :: If the requested value is not found, print an error
+  message and cause the process to exit with exit value =1=.
+
+- =warn= :: If the requested value is not found, log a warning.
+  If =default= is also given, return that, otherwise return =None=.
+
+(Both =value_int= and =value_filename= also accept these keyword
+arguments, but they are ignored.)
+
+***** entire set
+
+The =dump= method takes no arguments.
+It displays to stdout each section and its options (and values)
+in the format:
+
+: [section]
+: option = value # FIXME (what is location?)
+
+*** usage as a program
+
+FIXME: Is this supposed to be documented?
+Seems out of place in a library.
+Maybe it's there only for testing purposes?
+Another idea is to move it to its own utility program.
+
+If =talerconfig.py= is invoked from the command-line, it functions
+as a program that displays either a specific value or dumps the entire set,
+depending on the command-line args given.
+
+Options are:
+
+- =-c, --config FILE= :: Read Taler configuration from =FILE=.
+  See =from_file= (above) for behavior if unspecified.
+
+- =-s, --section SECTION= :: Look for option in section =SECTION=.
+
+- =-o, --option OPTION= :: Display value associated with option =OPTION=.
+
+- =-f, --filename= :: If the value is a string, do shell-style
+  variable expansion (see above) on it.
+
+If both =SECTION= and =OPTION= are omitted, display the entire set
+of values using the =dump= method (see above).

-- 
To stop receiving notification emails like this one, please contact
gnunet@gnunet.org.