Write docstrings for Agora and Transactions classes

handler/agora.py

@@ -18,6 +18,8 @@ from settings import settings
 
 log = Logger("agora.global")
 
+# TODO: move to utils
+
 
 def handle_exceptions(func):
     def inner_function(*args, **kwargs):
@@ -594,6 +596,7 @@ class Agora(object):
             ad = self.agora.ad_create(**form)
         return ad
 
+    # TODO: move to markets
     def create_distribution_list(self, filter_asset=None):
         """
         Create a list for distribution of ads.

handler/transactions.py

@@ -24,6 +24,7 @@ class Transactions(object):
         """
         self.log = Logger("transactions")
 
+    # TODO: write tests then refactor, this is terribly complicated!
     def transaction(self, data):
         """
         Store details of transaction and post notifications to IRC.
@@ -284,6 +285,7 @@ class Transactions(object):
         """
         refs = self.get_refs()
         matching_refs = []
+        # TODO: use get_ref_map in this function instead of calling get_ref multiple times
         for ref in refs:
             stored_trade = self.get_ref(ref)
             if stored_trade["currency"] == currency and float(stored_trade["amount"]) == float(amount):
@@ -320,9 +322,11 @@ class Transactions(object):
 
     def get_ref(self, reference):
         """
-        Get a reference ID for a single trade.
+        Get the trade information for a reference.
-        :return: trade ID
+        :param reference: trade reference
-        :rtype: string
+        :type reference: string
+        :return: dict of trade information
+        :rtype: dict
         """
         ref_data = r.hgetall(f"trade.{reference}")
         ref_data = convert(ref_data)
@@ -333,12 +337,20 @@ class Transactions(object):
     def del_ref(self, reference):
         """
         Delete a given reference from the Redis database.
+        :param reference: trade reference to delete
+        :type reference: string
         """
         tx = self.ref_to_tx(reference)
         r.delete(f"trade.{reference}")
         r.delete(f"trade.{tx}.reference")
 
     def cleanup(self, references):
+        """
+        Reconcile the internal reference database with a given list of references.
+        Delete all internal references not present in the list and clean up artifacts.
+        :param references: list of references to reconcile against
+        :type references: list
+        """
         for tx, reference in self.get_ref_map().items():
             if reference not in references:
                 self.log.info("Archiving trade reference: {reference} / TX: {tx}", reference=reference, tx=tx)
@@ -346,6 +358,13 @@ class Transactions(object):
                 r.rename(f"trade.{reference}", f"archive.trade.{reference}")
 
     def tx_to_ref(self, tx):
+        """
+        Convert a trade ID to a reference.
+        :param tx: trade ID
+        :type tx: string
+        :return: reference
+        :rtype: string
+        """
         refs = self.get_refs()
         for reference in refs:
             ref_data = convert(r.hgetall(f"trade.{reference}"))
@@ -355,12 +374,24 @@ class Transactions(object):
                 return reference
 
     def ref_to_tx(self, reference):
+        """
+        Convert a reference to a trade ID.
+        :param reference: trade reference
+        :type reference: string
+        :return: trade ID
+        :rtype: string
+        """
         ref_data = convert(r.hgetall(f"trade.{reference}"))
         if not ref_data:
             return False
         return ref_data["id"]
 
     def get_total_usd(self):
+        """
+        Get total USD in all our accounts, bank and trading.
+        :return: value in USD
+        :rtype float:
+        """
         total_usd_revolut = self.revolut.get_total_usd()
         if total_usd_revolut is False:
             return False
@@ -389,7 +420,14 @@ class Transactions(object):
         total_usd = total_usd_agora + total_usd_revolut
         return total_usd
 
+    # TODO: possibly refactor this into smaller functions which don't return as much stuff
+    # check if this is all really needed in the corresponding withdraw function
     def get_total(self):
+        """
+        Get all the values corresponding to the amount of money we hold.
+        :return: ((total SEK, total USD, total GBP), (total XMR USD, total BTC USD), (total XMR, total BTC))
+        :rtype: tuple(tuple(float, float, float), tuple(float, float), tuple(float, float))
+        """
         total_usd_revolut = self.revolut.get_total_usd()
         if total_usd_revolut is False:
             self.log.error("Could not get USD total.")
@@ -433,6 +471,11 @@ class Transactions(object):
         )  # Total XMR and BTC balance in Agora
 
     def get_remaining(self):
+        """
+        Check how much profit we need to make in order to withdraw.
+        :return: profit remaining in USD
+        :rtype: float
+        """
         total_usd = self.get_total_usd()
         if not total_usd:
             return False
@@ -443,6 +486,11 @@ class Transactions(object):
         return remaining
 
     def get_open_trades_usd(self):
+        """
+        Get total value of open trades in USD.
+        :return: total trade value
+        :rtype: float
+        """
         dash = self.agora.wrap_dashboard()
         if dash is False:
             return False
@@ -463,6 +511,11 @@ class Transactions(object):
         return cumul_usd
 
     def get_total_remaining(self):
+        """
+        Check how much profit we need to make in order to withdraw, taking into account open trade value.
+        :return: profit remaining in USD
+        :rtype: float
+        """
         total_usd = self.get_total_usd()
         total_trades_usd = self.get_open_trades_usd()
         if not total_usd: