From 4682e55ffc89c852965a5ff7421d189faeebefda Mon Sep 17 00:00:00 2001
From: kmille <github@androidloves.me>
Date: Thu, 28 Mar 2024 09:49:00 +0100
Subject: [PATCH] Add a full code example to the docs if a TAN is required
 (#124)

* Add a full code example to the docs if a TAN is required

* Improve some minor things
---
 docs/quickstart.rst |  2 +-
 docs/tans.rst       | 45 +++++++++++++++++++++++++++++++++++++++++++++
 2 files changed, 46 insertions(+), 1 deletion(-)

diff --git a/docs/quickstart.rst b/docs/quickstart.rst
index b54ab6e..2d37882 100644
--- a/docs/quickstart.rst
+++ b/docs/quickstart.rst
@@ -62,6 +62,6 @@ commands using the client instance:
         # Fetch accounts
         accounts = f.get_sepa_accounts()
 
-Go on to the next pages to find out what commands are supported!
+Go on to the next pages to find out what commands are supported! There is also a full example on how to get your bank transactions if a TAN is required (:ref:`tans-full-example`).
 
 .. _ZKA Website: https://www.hbci-zka.de/register/prod_register.htm
\ No newline at end of file
diff --git a/docs/tans.rst b/docs/tans.rst
index 9c3028a..288ceac 100644
--- a/docs/tans.rst
+++ b/docs/tans.rst
@@ -181,3 +181,48 @@ Reference
    :inherited-members:
    :member-order: bysource
    :exclude-members: is_unset, naive_parse, print_nested
+
+
+.. _tans-full-example:
+
+Full example
+------------
+
+A full example on how to get transactions if a TAN is required. If a TAN is required ``result`` will be an object of type ``NeedTANResponse``. Otherwise it will hold your transactions directly.
+
+.. code-block:: python
+
+    import datetime
+    from fints.utils import minimal_interactive_cli_bootstrap
+    from fints.client import FinTS3PinTanClient, NeedTANResponse
+    from fints.hhd.flicker import terminal_flicker_unix
+
+    from credentials import blz, username, password, hbci_backend
+
+    client = FinTS3PinTanClient(blz,
+                                username,
+                                password,
+                                hbci_backend)
+    minimal_interactive_cli_bootstrap(client)
+    with client:
+        accounts = client.get_sepa_accounts()
+        for account in accounts:
+            print(f"Doing {account.iban}")
+            result = client.get_transactions(account,
+                                             start_date=datetime.datetime.now() - datetime.timedelta(days=100),
+                                             end_date=datetime.datetime.now())
+            if isinstance(result, NeedTANResponse):
+                print("TAN is required")
+                if getattr(result, 'challenge_hhduc', None):
+                    # Smart-TAN with flicker
+                    try:
+                        terminal_flicker_unix(result.challenge_hhduc)
+                    except KeyboardInterrupt:
+                        pass
+                # else: mobile TAN/manual Smart-TAN/... is used
+                print(result.challenge)
+                tan = input('Please enter TAN:')
+                result = client.send_tan(result, tan)
+            else:
+                print("No TAN is required")
+            print(f"Got {len(result)} transactions for {account.iban}")