From 3bf2e65cd70ba9402d7e8172df18527c71bc4091 Mon Sep 17 00:00:00 2001
From: Mark Veidemanis <m@zm.is>
Date: Mon, 28 Feb 2022 20:18:42 +0000
Subject: [PATCH] Refactor initialisation and add docstrings to util module

---
 handler/app.py  | 19 ++++---------------
 handler/util.py | 40 ++++++++++++++++++++++++++++++++++++++++
 2 files changed, 44 insertions(+), 15 deletions(-)

diff --git a/handler/app.py b/handler/app.py
index 645f183..b1763c7 100755
--- a/handler/app.py
+++ b/handler/app.py
@@ -2,7 +2,6 @@
 # Twisted/Klein imports
 from twisted.logger import Logger
 from twisted.internet import reactor
-from twisted.internet.task import LoopingCall, deferLater
 from klein import Klein
 
 # Other library imports
@@ -76,18 +75,6 @@ class WebApp(object):
         return dumps(True)
 
 
-def setup_call_loops(token_setting, function_init, function_continuous, delay, function_post_start=None):
-    if token_setting == "1":
-        deferLater(reactor, 1, function_init)
-    else:
-        deferLater(reactor, 1, function_continuous, True)
-    if function_post_start:
-        deferLater(reactor, 4, function_post_start)
-
-    lc = LoopingCall(function_continuous)
-    lc.start(delay)
-
-
 if __name__ == "__main__":
     init_map = {
         "notify": Notify(),
@@ -103,16 +90,18 @@ if __name__ == "__main__":
         "webapp": WebApp(),
         "money": Money(),
     }
+    # Merge all classes into each other
     util.xmerge_attrs(init_map)
 
-    setup_call_loops(
+    # Setup the authcode -> refresh token and refresh_token -> auth_token stuff
+    util.setup_call_loops(
         token_setting=settings.Revolut.SetupToken,
         function_init=init_map["revolut"].setup_auth,
         function_continuous=init_map["revolut"].get_new_token,
         delay=int(settings.Revolut.RefreshSec),
         function_post_start=init_map["revolut"].setup_webhook,
     )
-    setup_call_loops(
+    util.setup_call_loops(
         token_setting=settings.TrueLayer.SetupToken,
         function_init=init_map["truelayer"].setup_auth,
         function_continuous=init_map["truelayer"].get_new_token,
diff --git a/handler/util.py b/handler/util.py
index f2a479b..56f132f 100644
--- a/handler/util.py
+++ b/handler/util.py
@@ -1,5 +1,7 @@
 # Twisted/Klein imports
 from twisted.logger import Logger
+from twisted.internet import reactor
+from twisted.internet.task import LoopingCall, deferLater
 
 # Other library imports
 from httpx import ReadTimeout, ReadError, RemoteProtocolError
@@ -9,6 +11,12 @@ log = Logger("util.global")
 
 
 def xmerge_attrs(init_map):
+    """
+    Given a dictionary of strings and classes, set all corresponding class.<string> attributes
+    on each class, to every other class.
+    "a": A(), "b": B() -> A.b = B_instance, B.a = A_instance
+    :param init_map: dict of class names to classes
+    """
     for classname, object_instance in init_map.items():
         # notify, Notify
         for classname_inside, object_instance_inside in init_map.items():
@@ -17,6 +25,26 @@ def xmerge_attrs(init_map):
                 setattr(object_instance, classname_inside, object_instance_inside)
 
 
+def setup_call_loops(token_setting, function_init, function_continuous, delay, function_post_start=None):
+    """
+    Setup the loops for dealing with access, refresh and auth tokens for various providers.
+    :param token_setting: the setting for whether to do the initial authentication
+    :param function_init: the initial authentication function
+    :param function_continuous: the ongoing authentication function (refresh_token -> access_token)
+    :param delay: time in seconds to wait between calls to function_continuous
+    :param function_post_start: an optional function to run after the access token is obtained
+    """
+    if token_setting == "1":
+        deferLater(reactor, 1, function_init)
+    else:
+        deferLater(reactor, 1, function_continuous, True)
+    if function_post_start:
+        deferLater(reactor, 4, function_post_start)
+
+    lc = LoopingCall(function_continuous)
+    lc.start(delay)
+
+
 def convert(data):
     """
     Recursively convert a dictionary.
@@ -48,7 +76,19 @@ def last_online_recent(date):
 
 
 def handle_exceptions(func):
+    """
+    Wrapper helper to handle Agora API errors.
+    :param func: function to wrap
+    :rtype: func
+    :return: the wrapped function
+    """
+
     def inner_function(*args, **kwargs):
+        """
+        Inner wrapper helper.
+        :rtype: any or bool
+        :return: False or the normal return
+        """
         try:
             rtrn = func(*args, **kwargs)
         except (ReadTimeout, ReadError, RemoteProtocolError):