updated to isin and added comments

telegram_bot/api_handling/api_handler.py

@@ -12,9 +12,9 @@ __license__ = "None"
 import sys
 import os
 import requests as r
-from croniter import croniter
+from croniter import croniter # used for checking cron formatting
-
 
+# note: for more information about the api visit swagger documentation on https://gruppe1.testsites.info/api/docs#/
 
 class API_Handler:
     """class for interacting with the api webservice
@@ -50,17 +50,17 @@ class API_Handler:
         """
         self.db_adress = db_adress
 
-        payload = {'email': email, 'password': password}
+        payload = {'email': email, 'password': password} # credentials for admin account that has all permissions to get and set data (in this case bot account)
-        with r.Session() as s:
+        with r.Session() as s: # open session
-            p = s.post(self.db_adress + "/user/login", json=payload)
+            p = s.post(self.db_adress + "/user/login", json=payload) # login to webservice
             if p.status_code == 200:
-                self.token = p.json()["data"]['token']
+                self.token = p.json()["data"]['token'] # store token for further authentication of requests
             else:
                 print("Error: " + str(p.status_code) + " invalid credentials")
                 self.token = None
 
 
-    def reauthorize(self, email, password):
+    def reauthorize(self, email, password): # can be used if token expired
         """set new credentials
 
         Args:
@@ -78,7 +78,7 @@ class API_Handler:
                 return None
 
 
-    def get_user(self, user_id, max_retries=10):
+    def get_user(self, user_id, max_retries=10): # max retries are used recursively if the request fails
         """gets the shares of the user
 
         Args:
@@ -92,13 +92,13 @@ class API_Handler:
             return None
 
         with r.Session() as s:
-            headers = {'Authorization': 'Bearer ' + self.token + ":" + str(user_id)}
+            headers = {'Authorization': 'Bearer ' + self.token + ":" + str(user_id)} # authorization is bot_token:user_id (user_id is the id of the user you want to get data from)
             req = s.get(self.db_adress + "/user", headers=headers)
             if(req.status_code == 200):
                 return req.json()["data"]
             
             else:
-                return self.get_user(user_id, max_retries-1)
+                return self.get_user(user_id, max_retries-1) # if request fails try again recursively
 
     
     def get_all_users(self, max_retries=10):
@@ -142,10 +142,10 @@ class API_Handler:
             req = s.get(self.db_adress + "/keywords", headers=headers)
             if(req.status_code == 200):
                 keywords_json = req.json()["data"]
-                for keyword in keywords_json:
+                for keyword in keywords_json: # keywords_json is a list of dictionaries
                     keywords.append(keyword["keyword"])
 
-                return keywords
+                return keywords # will be empty if no keywords are set
 
             else:
                 return self.get_user_keywords(user_id, max_retries-1)
@@ -206,7 +206,7 @@ class API_Handler:
                 shares_json = req.json()["data"]
                 shares = []
                 for share in shares_json:
-                    shares.append(share["symbol"])
+                    shares.append(share["isin"]) # we only want the isin of the shares
 
                 return shares
             
@@ -214,23 +214,24 @@ class API_Handler:
                 return self.get_user_shares(user_id, max_retries-1)
 
 
-    def set_share(self, user_id, symbol):
+    def set_share(self, user_id, isin, comment):
         """sets the share of the user
 
         Args:
             user_id (int): id of the user
-            symbol (string): symbol of the share
+            isin (string): isin of the share
+            comment (string): comment of the share
         
         Returns:
             int: status code
         """
         with r.Session() as s:
             headers = {'Authorization': 'Bearer ' + self.token + ":" + str(user_id)}
-            req = s.post(self.db_adress + "/share", json={"symbol": symbol}, headers=headers)
+            req = s.post(self.db_adress + "/share", json={"comment": comment, "isin": isin}, headers=headers) # set share by setting comment and isin, comment can be the real name of the share e.g. "Apple Inc."
             return req.status_code
 
 
-    def delete_share(self, user_id, symbol):
+    def delete_share(self, user_id, isin):
         """deletes the share of the user
 
         Args:
@@ -242,7 +243,7 @@ class API_Handler:
         """
         with r.Session() as s:
             headers = {'Authorization': 'Bearer ' + self.token + ":" + str(user_id)}
-            req = s.delete(self.db_adress + "/share", json={"symbol": symbol}, headers=headers)
+            req = s.delete(self.db_adress + "/share", json={"isin": isin}, headers=headers) # to delete a share only the isin is needed because it is unique, shares are not transactions!
             return req.status_code
 
 
@@ -277,16 +278,16 @@ class API_Handler:
             user_id (int): id of the user
             comment (string): comment of the transaction
             isin (string): isin of the transaction
-            count (int): count of the transaction
+            count (float): count of the transaction
             price (float): price of the transaction
-            time (string): time of the transaction
+            time (string): time of the transaction formatted like e.g. "2011-10-05T14:48:00.000Z"
         
         Returns:
             int: status code
         """
         with r.Session() as s:
             headers = {'Authorization': 'Bearer ' + self.token + ":" + str(user_id)}
-            transaction = {"comment": comment, "count": count, "isin": isin, "price": price, "time": time}
+            transaction = {"comment": str(comment), "count": float(count), "isin": str(isin), "price": float(price), "time": str(time)} # set transaction as JSON with all the attributes needed according to Swagger docs
             req = s.post(self.db_adress + "/transaction", json=transaction, headers=headers)
             return req.status_code
 
@@ -306,9 +307,9 @@ class API_Handler:
 
         with r.Session() as s:
             headers = {'Authorization': 'Bearer ' + self.token + ":" + str(user_id)}
-            req = s.get(self.db_adress + "/portfolio", headers=headers)
+            req = s.get(self.db_adress + "/portfolio", headers=headers) # get portfolio as JSON
             if req.status_code == 200:
-                portfolio_dict = req.json()["data"]
+                portfolio_dict = req.json()["data"] # get the data of the JSON
                 return portfolio_dict
             else:
                 return self.get_user_portfolio(user_id, max_retries-1)
@@ -323,22 +324,22 @@ class API_Handler:
         Returns:
             int: status code
         """
-        if not croniter.is_valid(cron_interval):
+        if not croniter.is_valid(cron_interval): # check if cron_interval is in valid format
             print("Error: Invalid cron format")
-            return -1
+            return -1 # return error code -1 if invalid cron format
 
         with r.Session() as s:
             headers = {'Authorization': 'Bearer ' + self.token + ":" + str(user_id)}
-            req = s.put(self.db_adress + "/user/setCron", json={"cron": cron_interval}, headers=headers)
+            req = s.put(self.db_adress + "/user/setCron", json={"cron": str(cron_interval)}, headers=headers) # put not post (see swagger docs)
             return req.status_code
 
 
-if __name__ == "__main__":
+if __name__ == "__main__": # editable, just for basic on the go testing of new functions
 
     print("This is a module for the telegram bot. It is not intended to be run directly.")
     handler = API_Handler("https://gruppe1.testsites.info/api", "bot@example.com", "bot")
     print(handler.token)
-    keywords = handler.get_user_keywords(user_id = 1709356058) #user_id is currently mine (Linus)
+    keywords = handler.get_user_keywords(user_id = 1709356058) #user_id here is currently mine (Linus)
     print(keywords)
     shares = handler.get_user_portfolio(user_id = 1709356058)
     print("set cron with status: "+ str(handler.set_cron_interval(user_id = 1709356058, cron_interval = "0 0 * * *")))