Document and comment api.py

Author: avivace

api.py

@@ -1,4 +1,6 @@
 """
+API methods implementation
+This file contains every method called by the API defined in v2.yml
 """
 
 from flask import jsonify
@@ -22,7 +24,9 @@
 )
 
 def get_serial():
-  # Extract serial from cpuinfo file
+  """
+  Extract serial from cpuinfo file
+  """
   cpuserial = "0000000000000000"
   try:
     f = open('/proc/cpuinfo','r')
@@ -37,6 +41,11 @@ def get_serial():
 
 @cached(cache=TTLCache(maxsize=1, ttl=10))
 def get_status():
+    """
+    Expose CoderBot status:
+    temperature, uptime, and internet connectivity status.
+    (Cached method)
+    """
     try:
         temp = os.popen("vcgencmd measure_temp").readline().replace("temp=","")
     except:
@@ -50,8 +59,12 @@ def get_status():
 
 @cached(cache=TTLCache(maxsize=1, ttl=60))
 def get_info():
-    # [:-2] strips out '\n' (cat)
+    """
+    Expose informations about the CoderBot system.
+    (Cached method)
+    """
     try:
+        # manifest.json is generated while building/copying the backend
         with open('manifest.json', 'r') as f:
             metadata = json.load(f)
         backend_commit = metadata["backendCommit"][0:7]
@@ -81,27 +94,34 @@ def get_info():
 prog = None
 prog_engine = ProgramEngine.get_instance()
 
+# Programs and Activities databases
 programs = TinyDB("data/programs.json")
 activities = TinyDB("data/activities.json")
 
 query = Query()
 
+## Robot control 
+
 def stop():
     bot.stop()
     return 200
 
-
 def move(data):
     print(data)
     bot.move(speed=data["speed"], elapse=data["elapse"])
     return 200
 
-
 def turn(data):
     print(data)
     bot.turn(speed=data["speed"], elapse=data["elapse"])
     return 200
 
+def exec(data):
+    prog = prog_engine.create(data["name"], data["code"])
+    return json.dumps(prog.execute())
+
+## System
+
 def status():
     status = get_status()
 
@@ -123,21 +143,22 @@ def info():
         "serial": info["serial"]
     }
 
-
-def exec(data):
-    prog = prog_engine.create(data["name"], data["code"])
-    return json.dumps(prog.execute())
-
-
 def restoreSettings():
     with open("data/defaults/config.json") as f:
         Config.write(json.loads(f.read()))
     bot_config = Config.get()
     return "ok"
 
+def updateFromPackage():
+    os.system('sudo bash /home/pi/clean-update.sh')
+    file_to_upload = connexion.request.files['file_to_upload']
+    file_to_upload.save(os.path.join('/home/pi/', 'update.tar'))
+    os.system('sudo coderbot_update /home/pi/update.tar && sudo reboot')
+    return 200
+
 
-## Programs
 
+## Programs
 
 def saveProgram(data, overwrite):
     print(overwrite)
@@ -156,11 +177,9 @@ def saveProgram(data, overwrite):
             else:
                 return "askOverwrite"
 
-
 def loadProgram(name):
     return programs.search(query.name == name)[0], 200
 
-
 def deleteProgram(data):
     programs.remove(query.name == data["name"])
 
@@ -180,30 +199,23 @@ def saveActivity(data):
         activities.update(data, query.name == data["name"])
         return 200
 
-
 def loadActivity(name):
     return activities.search(query.name == name)[0], 200
 
-
 def deleteActivity(data):
     activities.remove(query.name == data["name"])
 
 
 def listActivities():
     return activities.all()
 
-# Delete everything but the defaults programs
 def resetDefaultPrograms():
+    """
+    Delete everything but the default programs
+    """
     programs.purge()
     for filename in os.listdir("data/defaults/programs/"):
         if filename.endswith(".json"):
             with open("data/defaults/programs/" + filename) as p:
                 q = p.read()
-                programs.insert(json.loads(q))
-
-def updateFromPackage():
-    os.system('sudo bash /home/pi/clean-update.sh')
-    file_to_upload = connexion.request.files['file_to_upload']
-    file_to_upload.save(os.path.join('/home/pi/', 'update.tar'))
-    os.system('sudo coderbot_update /home/pi/update.tar && sudo reboot')
-    return 200
+                programs.insert(json.loads(q))