add documentation for payto.py

1 files changed, 53 insertions, 0 deletions

diff --git a/doc/doc.org b/doc/doc.org
index 60779b4..81b242a 100644
--- a/doc/doc.org
+++ b/doc/doc.org
@@ -280,3 +280,56 @@ the same name as the string log level).
 
 : >>> l.log ("user clicked button", l.INFO)
 : INFO:ui:user clicked button
+
+* ‘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 ([[class =Amount=]])
+
+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)