From 987e8545f5eca4ad2bfc24878c5ea5bc408a4a0a Mon Sep 17 00:00:00 2001
From: Mark Veidemanis <m@zm.is>
Date: Mon, 27 Dec 2021 21:33:49 +0000
Subject: [PATCH] Add more docstrings to Agora code

---
 handler/agora.py | 53 ++++++++++++++++++++++++++++++++++++++++++++++++
 1 file changed, 53 insertions(+)

diff --git a/handler/agora.py b/handler/agora.py
index dd3e588..24be265 100644
--- a/handler/agora.py
+++ b/handler/agora.py
@@ -17,6 +17,10 @@ class Agora(object):
     """
 
     def __init__(self):
+        """
+        Initialise the AgoraDesk and CurrencyRates APIs.
+        Initialise the last_dash storage for detecting new trades.
+        """
         self.log = Logger("agora")
         self.agora = AgoraDesk(settings.Agora.Token)
         self.cr = CurrencyRates()
@@ -26,10 +30,18 @@ class Agora(object):
         self.irc = irc
 
     def setup_loop(self):
+        """
+        Set up the LoopingCall to get all active trades.
+        """
         self.lc = LoopingCall(self.dashboard)
         self.lc.start(int(settings.Agora.RefreshSec))
 
     def dashboard_id_only(self):
+        """
+        Returns a list of the IDs of open trades.
+        :return: list of open trade IDs
+        :rtype: list
+        """
         dash = self.agora.dashboard_seller()
         dash_tmp = []
         if dash["response"]["data"]["contact_count"] > 0:
@@ -39,6 +51,11 @@ class Agora(object):
         return dash_tmp
 
     def dashboard(self):
+        """
+        Get information about our open trades.
+        :return: human readable list of strings about our trades
+        :rtype: list
+        """
         dash = self.agora.dashboard_seller()
         dash_tmp = []
         if dash["response"]["data"]["contact_count"] > 0:
@@ -58,6 +75,12 @@ class Agora(object):
         return dash_tmp
 
     def get_messages(self, contact_id):
+        """
+        Get messages for a certain trade ID.
+        :param contact_id: trade/contact ID
+        :return: list of messages
+        :rtype: list
+        """
         messages = self.agora.contact_messages(contact_id)
         messages_tmp = []
         for message in messages["response"]["data"]["message_list"]:
@@ -65,6 +88,11 @@ class Agora(object):
         return messages_tmp
 
     def get_all_messages(self):
+        """
+        Get all messages for all open trades.
+        :return: dict of lists keyed by trade/contact ID
+        :rtype: dict with lists
+        """
         dash = self.dashboard_id_only()
         messages_tmp = {}
         for contact_id in dash:
@@ -74,14 +102,34 @@ class Agora(object):
         return messages_tmp
 
     def get_ads(self):
+        """
+        Get information about our ads.
+        :return: data about our open ads
+        :rtype: dict
+        """
         ads = self.agora.ads()
         return ads
 
     def get_rates_all(self):
+        """
+        Get all rates that pair with USD.
+        :return: dictionary of USD/XXX rates
+        :rtype: dict
+        """
         rates = self.cr.get_rates("USD")
         return rates
 
     def create_ad(self, countrycode, currency):
+        """
+        Post an ad in a country with a given currency.
+        Convert the min and max amounts from settings to the given currency with CurrencyRates.
+        :param countrycode: country code
+        :param currency: currency code
+        :type countrycode: string
+        :type currency: string
+        :return: data about created object or error
+        :rtype: dict
+        """
         rates = self.get_rates_all()
         if currency == "USD":
             min_amount = float(settings.Agora.MinUSD)
@@ -113,6 +161,11 @@ class Agora(object):
         return ad
 
     def dist_countries(self):
+        """
+        Distribute our advert into all countries listed in the config.
+        :return: True or False
+        :rtype: bool
+        """
         for currency, countrycode in loads(settings.Agora.DistList):
             rtrn = self.create_ad(countrycode, currency)
             if not rtrn: