Improve documentation

diff --git a/docs/client.rst b/docs/client.rst
index 481b7c3b9a06c3b44ccaa87897820174083c3288..75d5d917329fc71699009bf87f8c049fd19b5341 100644 (file)
--- a/docs/client.rst
+++ b/docs/client.rst
@@ -3,6 +3,8 @@
 The client object
 =================
 
+.. _client-state:
+
 Storing and restoring client state
 ----------------------------------
 
@@ -14,7 +16,7 @@ across invocations. This includes
  * The User Parameter Data (UPD) with information about the user account and allowed actions
 
 .. autoclass:: fints.client.FinTS3Client
-   :members: __init__, deconstruct, set_data
+   :members: deconstruct, set_data
    :noindex:
    :undoc-members:
 
@@ -66,6 +68,7 @@ For transactions involving TANs it may be required by the bank to issue both ste
 within the same dialog. In this case it's mandatory to use a standing dialog, because otherwise each
 step would be issued in its own, implicit, dialog.
 
+.. _client-dialog-state:
 
 Storing and restoring dialog state
 ----------------------------------

diff --git a/docs/debits.rst b/docs/debits.rst
index d49a7a4ce270004273518c485fa5a4a910c288e9..d9eec205c0ca9c230dc65b65fd07781795a728ef 100644 (file)
--- a/docs/debits.rst
+++ b/docs/debits.rst
@@ -9,8 +9,8 @@ You can submit a SEPA debit XML file to the bank with the ``sepa_debit`` method:
 
 You should then enter a TAN, read our chapter :ref:`tans` to find out more.
 
-Example
--------
+Full example
+------------
 
 You can easily generate XML using the ``sepaxml`` python library:
 
@@ -40,3 +40,38 @@ You can easily generate XML using the ``sepaxml`` python library:
         "description": "FinTS Test transaction",
     })
     pain_message = sepa.export().decode()
+
+    client = FinTS3PinTanClient(...)
+
+    accounts = client.get_sepa_accounts()
+    account = accounts[0]
+
+    mechanisms = client.get_tan_mechanisms()
+    mechanism = mechanisms[client.get_current_tan_mechanism()]
+    if mechanism.description_required == fints.formals.DescriptionRequired.MUST:
+        usage_option, media = client.get_tan_media()
+
+        client.set_tan_medium(media[0])
+
+    res = client.sepa_debit(
+        account=accounts[0],
+        data=pain_message,
+        multiple=False,
+        control_sum=Decimal('1.00'),
+        pain_descriptor='urn:iso:std:iso:20022:tech:xsd:pain.008.002.02'
+    )
+
+    if isinstance(res, NeedTANResponse):
+        print(res.challenge)
+
+        if getattr(res, 'challenge_hhduc', None):
+            try:
+                terminal_flicker_unix(res.challenge_hhduc)
+            except KeyboardInterrupt:
+                pass
+
+        tan = input('Please enter TAN:')
+        res = client.send_tan(res, tan)
+
+    print(res.status)
+    print(res.responses)

diff --git a/docs/reading.rst b/docs/reading.rst
index 506c3f7e2dad3e65a7737960a21f2935aafb713e..1782d3f473b4fb38f99f3867094c11c004c82edc 100644 (file)
--- a/docs/reading.rst
+++ b/docs/reading.rst
@@ -9,7 +9,6 @@ The most simple method allows you to get all bank accounts that your user has ac
 .. autoclass:: fints.client.FinTS3Client
    :noindex:
    :members: get_sepa_accounts
-   :noindex:
 
 This method will return a list of named tuples of the following type:
 
@@ -61,7 +60,6 @@ Fetching holdings
 You can fetch the holdings of an account with the ``get_holdings`` method:
 
 .. autoclass:: fints.client.FinTS3Client
-   :noindex:
    :members: get_holdings
    :noindex:
 

diff --git a/docs/tans.rst b/docs/tans.rst
index b1be0d1682e29bb4a9691746acef465da453c830..fa5990cb835e01d1422b20c7aa8dfc779e37c6c0 100644 (file)
--- a/docs/tans.rst
+++ b/docs/tans.rst
@@ -3,6 +3,11 @@
 Working with TANs
 =================
 
+Many operations in FinTS will require a form of two-step authentication, called TANs. TANs are
+mostly required for operations that move money or change details of a bank account. TANs can be
+generated with a multidue of methods, including paper lists, smartcard readers, SMS messages, and
+smartphone apps.
+
 TAN methods
 -----------
 
@@ -16,48 +21,24 @@ The returned dictionary maps identifiers (generally: three-digit numerals) to in
 :func:`~fints.formals.TwoStepParametersCommon` subclass with varying fields, depending on the
 version of the two-step process and the bank.
 
-.. autoclass:: fints.formals.TwoStepParameters3
-   :noindex:
-   :undoc-members:
-   :members:
-   :inherited-members:
-   :member-order: bysource
-   :exclude-members: is_unset, naive_parse, print_nested
+The `name` field of theese objects provides a user-friendly name of the TAN mechanism that you
+can display to the user to choose from. To select a TAN mechanism, you can use
+:func:`~fints.client.FinTS3PinTanClient.set_tan_mechanism`, which takes the identifier used as
+key in the :func:`~fints.client.FinTS3PinTanClient.get_tan_mechanisms` return value.
 
-.. autoclass:: fints.formals.TwoStepParameters5
-   :noindex:
-   :undoc-members:
-   :members:
-   :inherited-members:
-   :member-order: bysource
-   :exclude-members: is_unset, naive_parse, print_nested
-
-The `name` field provides a user-friendly name of the TAN mechanism that you can display to the user
-to choose from.
-
-To select a TAN mechanism/query the currently selected TAN mechanism use the appropriate functions which
-take/return the identifier used as key in the `get_tan_mechanisms` return value.
-
-.. autoclass:: fints.client.FinTS3PinTanClient
-   :members: get_tan_mechanisms, set_tan_mechanism, get_current_tan_mechanism
-   :noindex:
-   :undoc-members:
+If the ``description_required`` attribute for the TAN mechanism is :attr:`~fints.formals.DescriptionRequired.MUST`,
+you will need to get a list of TAN media with :func:`~fints.client.FinTS3PinTanClient.get_tan_media` and select the
+appropriate one with :func:`~fints.client.FinTS3PinTanClient.set_tan_medium`.
 
-.. warning:: If the ``description_required`` attribute for the TAN mechanism is :attr:`~fints.formals.DescriptionRequired.MUST`,
-             you will need to get a list of TAN media with `get_tan_media()` and select the appropriate
-             one with `set_tan_medium()`.
+You may not change the active TAN mechanism or TAN medium within a standing dialog (see :ref:`client-dialog-state`).
 
-## FIXME The TAN media stuff is probably wrongly documented (and badly tested)
+The selection of the active TAN mechanism/medium is stored with the persistent client data (see :ref:`client-state`).
 
 .. autoclass:: fints.client.FinTS3PinTanClient
-   :members: get_tan_media, set_tan_medium
+   :members: get_tan_mechanisms, set_tan_mechanism, get_current_tan_mechanism, get_tan_media, set_tan_medium
    :noindex:
    :undoc-members:
 
-
-You may not change the active TAN mechanism or TAN medium within a standing dialog. (See XXX)
-The selection of the active TAN mechanism/medium is stored with the persistent client data. (See XXX)
-
 TAN challenges
 --------------
 
@@ -109,7 +90,7 @@ For example:
 
 .. code-block:: python
 
-    tan = input('Bitte die TAN eingeben.')
+    tan = input('Please enter the TAN code: ')
     result = client.send_tan(result, tan)
 
 
@@ -143,7 +124,7 @@ You SHOULD use this facility together with the client and dialog state restorati
 
     tan_request = NeedRetryResponse.from_data(tan_data)
     print("TAN request: {}".format(tan_request.challenge))
-    tan = input('Enter TAN')
+    tan = input('Enter TAN: ')
 
 .. code-block:: python
    :caption: Third step
@@ -155,3 +136,23 @@ You SHOULD use this facility together with the client and dialog state restorati
 
     print(response.status)
     print(response.responses)
+
+
+Reference
+---------
+
+.. autoclass:: fints.formals.TwoStepParameters3
+   :noindex:
+   :undoc-members:
+   :members:
+   :inherited-members:
+   :member-order: bysource
+   :exclude-members: is_unset, naive_parse, print_nested
+
+.. autoclass:: fints.formals.TwoStepParameters5
+   :noindex:
+   :undoc-members:
+   :members:
+   :inherited-members:
+   :member-order: bysource
+   :exclude-members: is_unset, naive_parse, print_nested

diff --git a/docs/transfers.rst b/docs/transfers.rst
index d2d990df720edfe961275e407b905c7cb9a86be7..4e56dfce39def69df7db148caf018273d11deb3e 100644 (file)
--- a/docs/transfers.rst
+++ b/docs/transfers.rst
@@ -21,8 +21,8 @@ If you want to use advanced methods, you can supply your own SEPA XML:
    :members: sepa_transfer
    :noindex:
 
-Example
--------
+Full example
+------------
 
 .. code-block:: python
 

diff --git a/fints/client.py b/fints/client.py
index 6fc86ac68560aac186b37197da8f932841c930fa..19ba9272aa72f6e48b668a960c05c9ad4f2d8d71 100644 (file)
--- a/fints/client.py
+++ b/fints/client.py
@@ -732,7 +732,7 @@ class FinTS3Client:
         :param control_sum: Sum of all debits (required if there are multiple)
         :param currency: Debit currency
         :param book_as_single: Kindly ask the bank to put multiple transactions as separate lines on the bank statement (defaults to ``False``)
-        :param pain_descriptor: URN of the PAIN message schema used.
+        :param pain_descriptor: URN of the PAIN message schema used. Defaults to ``urn:iso:std:iso:20022:tech:xsd:pain.008.003.01``.
         :return: Returns either a NeedRetryResponse or TransactionResponse (with data['task_id'] set, if available)
         """