From: Raphael Michel Date: Mon, 3 Dec 2018 19:52:41 +0000 (+0100) Subject: Improve documentation X-Git-Tag: v2.0.0~1^2~5 X-Git-Url: http://git.ipfire.org/cgi-bin/gitweb.cgi?a=commitdiff_plain;h=0a73c5a9399d73c023a4a81bc81bda579e5afe32;p=thirdparty%2Fpython-fints.git Improve documentation --- diff --git a/docs/client.rst b/docs/client.rst index 481b7c3..75d5d91 100644 --- 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 d49a7a4..d9eec20 100644 --- 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 506c3f7..1782d3f 100644 --- 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 b1be0d1..fa5990c 100644 --- 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 d2d990d..4e56dfc 100644 --- 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 6fc86ac..19ba927 100644 --- 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) """