[Date Prev][Date Next][Thread Prev][Thread Next][Date Index][Thread Index]
[taler-taler-util] branch master updated: Add WIP documentation (https:/
|
From: |
gnunet |
|
Subject: |
[taler-taler-util] branch master updated: Add WIP documentation (https://bugs.gnunet.org/view.php?id=6649) |
|
Date: |
Thu, 10 Feb 2022 16:19:53 +0100 |
This is an automated email from the git hooks/post-receive script.
ttn pushed a commit to branch master
in repository taler-util.
The following commit(s) were added to refs/heads/master by this push:
new ef8e148 Add WIP documentation
(https://bugs.gnunet.org/view.php?id=6649)
ef8e148 is described below
commit ef8e148d3672f776503b19eb47e9b161d1c61091
Author: Thien-Thi Nguyen <ttn@gnu.org>
AuthorDate: Thu Feb 10 10:19:17 2022 -0500
Add WIP documentation (https://bugs.gnunet.org/view.php?id=6649)
---
doc/README | 10 ++
doc/doc.html | 555 +++++++++++++++++++++++++++++++++++++++++++++++++++++++++++
doc/doc.org | 176 +++++++++++++++++++
doc/doc.txt | 248 ++++++++++++++++++++++++++
4 files changed, 989 insertions(+)
diff --git a/doc/README b/doc/README
new file mode 100644
index 0000000..84592ef
--- /dev/null
+++ b/doc/README
@@ -0,0 +1,10 @@
+This directory contains WIP documentation for the Taler-Util library.
+
+The source is doc.org.
+
+It's the temporary format while we figure out where this
+documentation should eventually live (and be published).
+
+Ongoing discussion: https://bugs.gnunet.org/view.php?id=6649
+
+Thus, the output files doc.txt and doc.html are also temporary.
diff --git a/doc/doc.html b/doc/doc.html
new file mode 100644
index 0000000..fbe6930
--- /dev/null
+++ b/doc/doc.html
@@ -0,0 +1,555 @@
+<?xml version="1.0" encoding="utf-8"?>
+<!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Strict//EN"
+"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 10:18 -->
+<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>
+<meta name="generator" content="Org mode" />
+<meta name="author" content="Thien-Thi Nguyen" />
+<style type="text/css">
+ <!--/*--><![CDATA[/*><!--*/
+ .title { text-align: center;
+ margin-bottom: .2em; }
+ .subtitle { text-align: center;
+ font-size: medium;
+ font-weight: bold;
+ margin-top:0; }
+ .todo { font-family: monospace; color: red; }
+ .done { font-family: monospace; color: green; }
+ .priority { font-family: monospace; color: orange; }
+ .tag { background-color: #eee; font-family: monospace;
+ padding: 2px; font-size: 80%; font-weight: normal; }
+ .timestamp { color: #bebebe; }
+ .timestamp-kwd { color: #5f9ea0; }
+ .org-right { margin-left: auto; margin-right: 0px; text-align: right; }
+ .org-left { margin-left: 0px; margin-right: auto; text-align: left; }
+ .org-center { margin-left: auto; margin-right: auto; text-align: center; }
+ .underline { text-decoration: underline; }
+ #postamble p, #preamble p { font-size: 90%; margin: .2em; }
+ p.verse { margin-left: 3%; }
+ pre {
+ border: 1px solid #ccc;
+ box-shadow: 3px 3px 3px #eee;
+ padding: 8pt;
+ font-family: monospace;
+ overflow: auto;
+ margin: 1.2em;
+ }
+ pre.src {
+ position: relative;
+ overflow: visible;
+ padding-top: 1.2em;
+ }
+ pre.src:before {
+ display: none;
+ position: absolute;
+ background-color: white;
+ top: -10px;
+ right: 10px;
+ padding: 3px;
+ border: 1px solid black;
+ }
+ pre.src:hover:before { display: inline;}
+ /* Languages per Org manual */
+ pre.src-asymptote:before { content: 'Asymptote'; }
+ pre.src-awk:before { content: 'Awk'; }
+ pre.src-C:before { content: 'C'; }
+ /* pre.src-C++ doesn't work in CSS */
+ pre.src-clojure:before { content: 'Clojure'; }
+ pre.src-css:before { content: 'CSS'; }
+ pre.src-D:before { content: 'D'; }
+ pre.src-ditaa:before { content: 'ditaa'; }
+ pre.src-dot:before { content: 'Graphviz'; }
+ pre.src-calc:before { content: 'Emacs Calc'; }
+ pre.src-emacs-lisp:before { content: 'Emacs Lisp'; }
+ pre.src-fortran:before { content: 'Fortran'; }
+ pre.src-gnuplot:before { content: 'gnuplot'; }
+ pre.src-haskell:before { content: 'Haskell'; }
+ pre.src-hledger:before { content: 'hledger'; }
+ pre.src-java:before { content: 'Java'; }
+ pre.src-js:before { content: 'Javascript'; }
+ pre.src-latex:before { content: 'LaTeX'; }
+ pre.src-ledger:before { content: 'Ledger'; }
+ pre.src-lisp:before { content: 'Lisp'; }
+ pre.src-lilypond:before { content: 'Lilypond'; }
+ pre.src-lua:before { content: 'Lua'; }
+ pre.src-matlab:before { content: 'MATLAB'; }
+ pre.src-mscgen:before { content: 'Mscgen'; }
+ pre.src-ocaml:before { content: 'Objective Caml'; }
+ pre.src-octave:before { content: 'Octave'; }
+ pre.src-org:before { content: 'Org mode'; }
+ pre.src-oz:before { content: 'OZ'; }
+ pre.src-plantuml:before { content: 'Plantuml'; }
+ pre.src-processing:before { content: 'Processing.js'; }
+ pre.src-python:before { content: 'Python'; }
+ pre.src-R:before { content: 'R'; }
+ pre.src-ruby:before { content: 'Ruby'; }
+ pre.src-sass:before { content: 'Sass'; }
+ pre.src-scheme:before { content: 'Scheme'; }
+ pre.src-screen:before { content: 'Gnu Screen'; }
+ pre.src-sed:before { content: 'Sed'; }
+ pre.src-sh:before { content: 'shell'; }
+ pre.src-sql:before { content: 'SQL'; }
+ pre.src-sqlite:before { content: 'SQLite'; }
+ /* additional languages in org.el's org-babel-load-languages alist */
+ pre.src-forth:before { content: 'Forth'; }
+ pre.src-io:before { content: 'IO'; }
+ pre.src-J:before { content: 'J'; }
+ pre.src-makefile:before { content: 'Makefile'; }
+ pre.src-maxima:before { content: 'Maxima'; }
+ pre.src-perl:before { content: 'Perl'; }
+ pre.src-picolisp:before { content: 'Pico Lisp'; }
+ pre.src-scala:before { content: 'Scala'; }
+ pre.src-shell:before { content: 'Shell Script'; }
+ pre.src-ebnf2ps:before { content: 'ebfn2ps'; }
+ /* additional language identifiers per "defun org-babel-execute"
+ in ob-*.el */
+ pre.src-cpp:before { content: 'C++'; }
+ pre.src-abc:before { content: 'ABC'; }
+ pre.src-coq:before { content: 'Coq'; }
+ pre.src-groovy:before { content: 'Groovy'; }
+ /* additional language identifiers from org-babel-shell-names in
+ ob-shell.el: ob-shell is the only babel language using a lambda to put
+ the execution function name together. */
+ pre.src-bash:before { content: 'bash'; }
+ pre.src-csh:before { content: 'csh'; }
+ pre.src-ash:before { content: 'ash'; }
+ pre.src-dash:before { content: 'dash'; }
+ pre.src-ksh:before { content: 'ksh'; }
+ pre.src-mksh:before { content: 'mksh'; }
+ pre.src-posh:before { content: 'posh'; }
+ /* Additional Emacs modes also supported by the LaTeX listings package */
+ pre.src-ada:before { content: 'Ada'; }
+ pre.src-asm:before { content: 'Assembler'; }
+ pre.src-caml:before { content: 'Caml'; }
+ pre.src-delphi:before { content: 'Delphi'; }
+ pre.src-html:before { content: 'HTML'; }
+ pre.src-idl:before { content: 'IDL'; }
+ pre.src-mercury:before { content: 'Mercury'; }
+ pre.src-metapost:before { content: 'MetaPost'; }
+ pre.src-modula-2:before { content: 'Modula-2'; }
+ pre.src-pascal:before { content: 'Pascal'; }
+ pre.src-ps:before { content: 'PostScript'; }
+ pre.src-prolog:before { content: 'Prolog'; }
+ pre.src-simula:before { content: 'Simula'; }
+ pre.src-tcl:before { content: 'tcl'; }
+ pre.src-tex:before { content: 'TeX'; }
+ pre.src-plain-tex:before { content: 'Plain TeX'; }
+ pre.src-verilog:before { content: 'Verilog'; }
+ pre.src-vhdl:before { content: 'VHDL'; }
+ pre.src-xml:before { content: 'XML'; }
+ pre.src-nxml:before { content: 'XML'; }
+ /* add a generic configuration mode; LaTeX export needs an additional
+ (add-to-list 'org-latex-listings-langs '(conf " ")) in .emacs */
+ pre.src-conf:before { content: 'Configuration File'; }
+
+ table { border-collapse:collapse; }
+ caption.t-above { caption-side: top; }
+ caption.t-bottom { caption-side: bottom; }
+ td, th { vertical-align:top; }
+ th.org-right { text-align: center; }
+ th.org-left { text-align: center; }
+ th.org-center { text-align: center; }
+ td.org-right { text-align: right; }
+ td.org-left { text-align: left; }
+ td.org-center { text-align: center; }
+ dt { font-weight: bold; }
+ .footpara { display: inline; }
+ .footdef { margin-bottom: 1em; }
+ .figure { padding: 1em; }
+ .figure p { text-align: center; }
+ .equation-container {
+ display: table;
+ text-align: center;
+ width: 100%;
+ }
+ .equation {
+ vertical-align: middle;
+ }
+ .equation-label {
+ display: table-cell;
+ text-align: right;
+ vertical-align: middle;
+ }
+ .inlinetask {
+ padding: 10px;
+ border: 2px solid gray;
+ margin: 10px;
+ background: #ffffcc;
+ }
+ #org-div-home-and-up
+ { text-align: right; font-size: 70%; white-space: nowrap; }
+ textarea { overflow-x: auto; }
+ .linenr { font-size: smaller }
+ .code-highlighted { background-color: #ffff00; }
+ .org-info-js_info-navigation { border-style: none; }
+ #org-info-js_console-label
+ { font-size: 10px; font-weight: bold; white-space: nowrap; }
+ .org-info-js_search-highlight
+ { background-color: #ffff00; color: #000000; font-weight: bold; }
+ .org-svg { width: 90%; }
+ /*]]>*/-->
+</style>
+<script type="text/javascript">
+/*
+@licstart The following is the entire license notice for the
+JavaScript code in this tag.
+
+Copyright (C) 2012-2020 Free Software Foundation, Inc.
+
+The JavaScript code in this tag is free software: you can
+redistribute it and/or modify it under the terms of the GNU
+General Public License (GNU GPL) as published by the Free Software
+Foundation, either version 3 of the License, or (at your option)
+any later version. The code is distributed WITHOUT ANY WARRANTY;
+without even the implied warranty of MERCHANTABILITY or FITNESS
+FOR A PARTICULAR PURPOSE. See the GNU GPL for more details.
+
+As additional permission under GNU GPL version 3 section 7, you
+may distribute non-source (e.g., minimized or compacted) forms of
+that code without the copy of the GNU GPL normally required by
+section 4, provided you include this license notice and a URL
+through which recipients can access the Corresponding Source.
+
+
+@licend The above is the entire license notice
+for the JavaScript code in this tag.
+*/
+<!--/*--><![CDATA[/*><!--*/
+ function CodeHighlightOn(elem, id)
+ {
+ var target = document.getElementById(id);
+ if(null != target) {
+ elem.cacheClassElem = elem.className;
+ elem.cacheClassTarget = target.className;
+ target.className = "code-highlighted";
+ elem.className = "code-highlighted";
+ }
+ }
+ function CodeHighlightOff(elem, id)
+ {
+ var target = document.getElementById(id);
+ if(elem.cacheClassElem)
+ elem.className = elem.cacheClassElem;
+ if(elem.cacheClassTarget)
+ target.className = elem.cacheClassTarget;
+ }
+/*]]>*///-->
+</script>
+</head>
+<body>
+<div id="content">
+<h1 class="title">Taler-Util Library</h1>
+<div id="table-of-contents">
+<h2>Table of Contents</h2>
+<div id="text-table-of-contents">
+<ul>
+<li><a href="#orgd78f678">1. classes overview</a>
+<ul>
+<li><a href="#orgda92b68">1.1. amount (currency + value)</a></li>
+<li><a href="#org4a5e10a">1.2. logging</a></li>
+<li><a href="#org9b2f3ca">1.3. ‘payto’ URI particularities</a></li>
+<li><a href="#org673ce64">1.4. configuration</a></li>
+</ul>
+</li>
+<li><a href="#org8a6eab3">2. classes <code>Amount</code>,
<code>SignedAmount</code></a>
+<ul>
+<li><a href="#orgc6e89e9">2.1. class <code>Amount</code></a></li>
+<li><a href="#org1c9854a">2.2. class <code>SignedAmount</code></a></li>
+</ul>
+</li>
+</ul>
+</div>
+</div>
+<p>
+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.
+</p>
+
+<p>
+This file is in Org Mode format and can be processed (by Emacs)
+to produce HTML, etc. When we figure out <b>where</b> to put this
+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-orgd78f678" class="outline-2">
+<h2 id="orgd78f678"><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)
+is also how the source code is organized.
+</p>
+
+<p>
+Several of these derive from the <code>Exception</code> class, and two
+of them derive from the <code>collections.defaultdict</code> class.
+The rest are <i>leaf classes</i>.
+</p>
+</div>
+
+<div id="outline-container-orgda92b68" class="outline-3">
+<h3 id="orgda92b68"><span class="section-number-3">1.1</span> amount (currency
+ value)</h3>
+<div class="outline-text-3" id="text-1-1">
+<ul class="org-ul">
+<li>CurrencyMismatchError(Exception)</li>
+<li>AmountOverflowError(Exception)</li>
+<li>AmountFormatError(Exception)</li>
+<li>Amount</li>
+<li>SignedAmount</li>
+</ul>
+</div>
+</div>
+
+<div id="outline-container-org4a5e10a" class="outline-3">
+<h3 id="org4a5e10a"><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>
+<li>GnunetLoglevel</li>
+<li>GnunetLogger</li>
+</ul>
+</div>
+</div>
+
+<div id="outline-container-org9b2f3ca" class="outline-3">
+<h3 id="org9b2f3ca"><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>
+<li>PaytoParse</li>
+</ul>
+</div>
+</div>
+
+<div id="outline-container-org673ce64" class="outline-3">
+<h3 id="org673ce64"><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>
+<li>ExpansionSyntaxError(Exception)</li>
+<li>Entry</li>
+<li>OptionDict(collections.defaultdict)</li>
+<li>SectionDict(collections.defaultdict)</li>
+<li>TalerConfig</li>
+</ul>
+</div>
+</div>
+</div>
+
+<div id="outline-container-org8a6eab3" class="outline-2">
+<h2 id="org8a6eab3"><span class="section-number-2">2</span> classes
<code>Amount</code>, <code>SignedAmount</code></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.
+</p>
+
+<p>
+The maximum <code>VALUE</code> is 2<sup>52</sup> (i.e., 4503599627370496).
+The <code>FRACTION</code> can be at most 8 digits (i.e., smallest non-zero
+<code>FRACTION</code> of <code>1</code> represents the number 0.00000001, and
the largest
+<code>FRACTION</code> of 99999999 represents the number 0.99999999).
+If an amount is specified that exceeds these limits,
+the constructor throws an <code>AmountOverflowError</code> exception.
+</p>
+</div>
+
+<div id="outline-container-orgc6e89e9" class="outline-3">
+<h3 id="orgc6e89e9"><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>.
+</p>
+
+<pre class="example">
+>>> import taler.util.amount as Amount
+# KUDOS 10.50
+>>> amt = Amount.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>.
+</p>
+
+<pre class="example">
+>>> amt.value, amt.fraction
+(10, 50000000)
+</pre>
+
+
+<p>
+You can use classmethod <code>parse</code> to read a string as an
<code>Amount</code> object.
+This function can throw <code>AmountFormatError</code> if the string is
malformed,
+and <code>AmountOverflowError</code> if the fraction portion is too long.
+</p>
+
+<pre class="example">
+>>> Amount.Amount.parse ("KUDOS:10.12345678")
+Amount(currency='KUDOS', value=10, fraction=12345678)
+</pre>
+
+
+<p>
+An <code>Amount</code> object supports addition and subtraction.
+The <code>currency</code> property must match, otherwise the operation throws
+a <code>CurrencyMismatchError</code> exception.
+</p>
+
+<pre class="example">
+>>> amt + amt
+Amount(currency='KUDOS', value=21, fraction=0)
+>>> another = Amount.Amount ("KUDOS", 5, 42)
+>>> amt - another
+Amount(currency='KUDOS', value=5, fraction=49999958)
+</pre>
+
+
+<p>
+Note, however, that a subtraction that results in a numerically negative
+<code>value</code> causes the operation to throw an
<code>AmountOverflowError</code> exception.
+</p>
+
+<pre class="example">
+>>> 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
+</pre>
+
+
+<p>
+The method <code>stringify</code> (which is also used in the
<code>__str__</code> definition)
+takes optional keyword <code>pretty</code> (default <code>False</code>) that
changes the
+output.
+</p>
+
+<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>
+
+
+<p>
+The method <code>is_zero</code> returns <code>True</code> if the
<code>Amount</code> object has a zero
+<code>value</code> component and a zero <code>fraction</code> component.
+</p>
+
+<pre class="example">
+>>> amt.is_zero ()
+False
+</pre>
+
+
+<p>
+An <code>Amount</code> object can be numerically compared with another
<code>Amount</code>
+for both equality and inequality.
+Comparison can throw a <code>CurrencyMismatchError</code> exception
+if both currencies are not the same.
+</p>
+
+<pre class="example">
+>>> amt > another
+True
+>>> amt == another
+False
+</pre>
+</div>
+</div>
+
+<div id="outline-container-org1c9854a" class="outline-3">
+<h3 id="org1c9854a"><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>.
+It has properties <code>is_positive</code> and <code>amount</code>.
+You can derive a <code>SignedAmount</code> from a simple <code>Amount</code>
with the
+<code>as_signed</code> method.
+</p>
+
+<pre class="example">
+>>> p = amt.as_signed ()
+>>> p.is_positive
+True
+>>> p.amount
+Amount(currency='KUDOS', value=10, fraction=50000000)
+</pre>
+
+
+<p>
+A <code>SignedAmount</code> object supports addition, subtraction, and
comparison
+(equality and inequality) with another <code>SignedAmount</code> object.
+</p>
+
+<pre class="example">
+>>> q = another.as_signed ()
+>>> (p - q).is_positive
+True
+>>> (q - p).is_positive
+False
+</pre>
+
+
+<p>
+The <code>stringify</code> method, like that for <code>Amount</code>, takes
optional keyword
+<code>pretty</code>. It always prefixes the output with either <code>+</code>
or <code>-</code>.
+</p>
+
+<pre class="example">
+>>> (p - q).stringify (pretty=False)
+'+KUDOS:5.49999958'
+>>> (q - p).stringify (pretty=True)
+'-5.49999958 KUDOS'
+</pre>
+
+
+<p>
+The classmethod <code>parse</code> recognizes a leading <code>+</code> or
<code>-</code>, and
+additionally accepts a plain <code>CURRENCY:VALUE.FRACTION</code> form as a
+positive <code>SignedAmount</code>.
+</p>
+
+<pre class="example">
+>>> Amount.SignedAmount.parse ("-KUDOS:2.34")
+SignedAmount(is_positive=False, amount=Amount(currency='KUDOS', value=2,
fraction=34000000))
+</pre>
+
+
+<p>
+Lastly, a <code>SignedAmount</code> object can flip its sign using a unary
minus.
+</p>
+
+<pre class="example">
+>>> n = q - p
+>>> n.is_positive
+False
+>>> (- n).is_positive
+True
+</pre>
+</div>
+</div>
+</div>
+</div>
+<div id="postamble" class="status">
+<p class="author">Author: Thien-Thi Nguyen</p>
+<p class="date">Created: 2022-02-10 gio 10:18</p>
+<p class="validation"><a
href="http://validator.w3.org/check?uri=referer";>Validate</a></p>
+</div>
+</body>
+</html>
diff --git a/doc/doc.org b/doc/doc.org
new file mode 100644
index 0000000..84702ae
--- /dev/null
+++ b/doc/doc.org
@@ -0,0 +1,176 @@
+#+TITLE: Taler-Util Library
+
+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
+
+* 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/.
+
+*** amount (currency + value)
+
+- CurrencyMismatchError(Exception)
+- AmountOverflowError(Exception)
+- AmountFormatError(Exception)
+- Amount
+- SignedAmount
+
+*** logging
+
+- LogDefinition
+- GnunetLoglevel
+- GnunetLogger
+
+*** ‘payto’ URI particularities
+
+- PaytoFormatError(Exception)
+- PaytoParse
+
+*** configuration
+
+- ConfigurationError(Exception)
+- ExpansionSyntaxError(Exception)
+- Entry
+- OptionDict(collections.defaultdict)
+- SectionDict(collections.defaultdict)
+- TalerConfig
+
+* classes =Amount=, =SignedAmount=
+
+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 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.
+
+*** class =Amount=
+
+The constructor takes three args: /currency/, /value/, /fraction/.
+
+: >>> import taler.util.amount as Amount
+: # KUDOS 10.50
+: >>> amt = Amount.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.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.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
+
+*** 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=.
+
+: >>> Amount.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
diff --git a/doc/doc.txt b/doc/doc.txt
new file mode 100644
index 0000000..1b7f6d7
--- /dev/null
+++ b/doc/doc.txt
@@ -0,0 +1,248 @@
+ ━━━━━━━━━━━━━━━━━━━━
+ TALER-UTIL LIBRARY
+
+ Thien-Thi Nguyen
+ ━━━━━━━━━━━━━━━━━━━━
+
+
+Table of Contents
+─────────────────
+
+1. classes overview
+.. 1. amount (currency + value)
+.. 2. logging
+.. 3. ‘payto’ URI particularities
+.. 4. configuration
+2. classes ‘Amount’, ‘SignedAmount’
+.. 1. class ‘Amount’
+.. 2. class ‘SignedAmount’
+
+
+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)
+─────────────────────────────
+
+ • 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 ‘Amount’, ‘SignedAmount’
+══════════════════════════════════
+
+ 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 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/.
+
+ ┌────
+ │ >>> import taler.util.amount as Amount
+ │ # KUDOS 10.50
+ │ >>> amt = Amount.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.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.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’.
+
+ ┌────
+ │ >>> Amount.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
+ └────
--
To stop receiving notification emails like this one, please contact
gnunet@gnunet.org.
| [Prev in Thread] |
Current Thread |
[Next in Thread] |
- [taler-taler-util] branch master updated: Add WIP documentation (https://bugs.gnunet.org/view.php?id=6649),
gnunet <=