Complete commenting for database methods

Change-Id: I4b7827c60ff7515440ebae421ecebf45054613aa

1 files changed, 88 insertions, 10 deletions

diff --git a/db/db.py b/db/db.py
index 2303a06..7c9fc75 100644
--- a/db/db.py
+++ b/db/db.py
@@ -106,7 +106,7 @@ class VlanDB:
     # Constraints:
     # Names and tags must be unique
     # Tags must be in the range 1-4095 (802.1q spec)
-    #
+    # Names can be any free-form text
     def create_vlan(self, name, tag, is_base_vlan):
 
         if int(tag) < 1 or int(tag) > 4095:
@@ -133,6 +133,7 @@ class VlanDB:
 
         return vlan_id
 
+    # Internal helper function
     def _delete_row(self, table, field, value):
         try:
             sql = "DELETE FROM %s WHERE %s = %s" % (table, field, '%s')
@@ -194,7 +195,8 @@ class VlanDB:
         self._delete_row("vlan", "vlan_id", vlan_id)
         return vlan_id
 
-    # Grab one column from one row of a query on one column; useful as a quick wrapper
+    # Grab one column from one row of a query on one column; useful as
+    # a quick wrapper
     def _get_element(self, select_field, table, compare_field, value):
 
         # We really want to use psycopg's type handling deal with the
@@ -218,7 +220,8 @@ class VlanDB:
         else:
             return None
 
-    # Grab one column from one row of a query on 2 columns; useful as a quick wrapper
+    # Grab one column from one row of a query on 2 columns; useful as
+    # a quick wrapper
     def _get_element2(self, select_field, table, compare_field1, value1, compare_field2, value2):
 
         # We really want to use psycopg's type handling deal with the
@@ -230,10 +233,6 @@ class VlanDB:
         # keep it after python's own string substitution.
         sql = "SELECT %s FROM %s WHERE %s = %s AND %s = %s" % (select_field, table, compare_field1, "%s", compare_field2, "%s")
 
-        # Now, the next icky thing: we need to make sure that we're
-        # passing a dict so that psycopg2 can pick it apart properly
-        # for its own substitution code. We force this with the
-        # trailing comma here
         data = (value1, value2)
         self.cursor.execute(sql, data)
 
@@ -242,7 +241,8 @@ class VlanDB:
         else:
             return None
 
-    # Grab one column from multiple rows of a query; useful as a quick wrapper
+    # Grab one column from multiple rows of a query; useful as a quick
+    # wrapper
     def _get_multi_elements(self, select_field, table, compare_field, value):
 
         # We really want to use psycopg's type handling deal with the
@@ -269,50 +269,105 @@ class VlanDB:
         else:
             return None
 
+    # Simple lookup: look up a switch by ID, and return all the
+    # details of that switch.
+    #
+    # Returns None on failure.
     def get_switch_by_id(self, switch_id):
         return self._get_row("switch", "switch_id", switch_id)
 
+    # Simple lookup: look up a switch by name, and return the ID of
+    # that switch.
+    #
+    # Returns None on failure.
     def get_switch_id_by_name(self, name):
         return self._get_element("switch_id", "switch", "name", name)
 
+    # Simple lookup: look up a switch by ID, and return the name of
+    # that switch.
+    #
+    # Returns None on failure.
     def get_switch_name_by_id(self, switch_id):
         return self._get_element("name", "switch", "switch_id", switch_id)
 
+    # Simple lookup: look up a port by ID, and return all the details
+    # of that port.
+    #
+    # Returns None on failure.
     def get_port_by_id(self, port_id):
         return self._get_row("port", "port_id", port_id)
 
-
-
+    # Simple lookup: look up a switch by ID, and return the IDs of all
+    # the ports on that switch.
+    #
+    # Returns None on failure.
     def get_ports_by_switch(self, switch_id):
         return self._get_multi_elements("port_id", "port", "switch_id", switch_id)
 
+    # Simple lookup: look up a port by its name and its parent switch
+    # by ID, and return the ID of the port.
+    #
+    # Returns None on failure.
     def get_port_by_switch_and_name(self, switch_id, name):
         return self._get_element2("port_id", "port", "switch_id", switch_id, "name", name)
 
+    # Simple lookup: look up a port by ID, and return the current VLAN
+    # id of that port.
+    #
+    # Returns None on failure.
     def get_current_vlan_id_by_port(self, port_id):
         return self._get_element("current_vlan_id", "port", "port_id", port_id)
 
+    # Simple lookup: look up a port by ID, and return the base VLAN
+    # id of that port.
+    #
+    # Returns None on failure.
     def get_base_vlan_id_by_port(self, port_id):
         return self._get_element("base_vlan_id", "port", "port_id", port_id)
 
+    # Simple lookup: look up a current VLAN by ID, and return the IDs
+    # of all the ports on that VLAN.
+    #
+    # Returns None on failure.
     def get_ports_by_current_vlan(self, vlan_id):
         return self._get_multi_elements("port_id", "port", "current_vlan_id", vlan_id)
 
+    # Simple lookup: look up a base VLAN by ID, and return the IDs
+    # of all the ports on that VLAN.
+    #
+    # Returns None on failure.
     def get_ports_by_base_vlan(self, vlan_id):
         return self._get_multi_elements("port_id", "port", "base_vlan_id", vlan_id)
 
+    # Simple lookup: look up a VLAN by ID, and return all the details
+    # of that VLAN.
+    #
+    # Returns None on failure.
     def get_vlan_by_id(self, vlan_id):
         return self._get_row("vlan", "vlan_id", vlan_id)
 
+    # Simple lookup: look up a VLAN by name, and return the ID of that
+    # VLAN.
+    #
+    # Returns None on failure.
     def get_vlan_id_by_name(self, name):
         return self._get_element("vlan_id", "vlan", "name", name)
 
+    # Simple lookup: look up a VLAN by tag, and return the ID of that
+    # VLAN.
+    #
+    # Returns None on failure.
     def get_vlan_id_by_tag(self, tag):
         return self._get_element("vlan_id", "vlan", "tag", tag)
 
+    # Simple lookup: look up a VLAN by ID, and return the name of that
+    # VLAN.
+    #
+    # Returns None on failure.
     def get_vlan_name_by_id(self, vlan_id):
         return self._get_element("vlan_name", "vlan", "vlan_id", vlan_id)
 
+    # Grab one row of a query on one column; useful as a quick wrapper
     def _get_row(self, table, field, value):
 
         # We really want to use psycopg's type handling deal with the
@@ -374,6 +429,14 @@ class VlanDB:
             raise
         return port_id
 
+    # Set the current vlan of a port in the database. The VLAN is
+    # passed by ID.
+    #
+    # Constraints:
+    # 1. The port must already exist
+    # 2. The port must not be a trunk port
+    # 3. The port must not be locked
+    # 1. The VLAN must already exist in the database
     def set_current_vlan(self, port_id, vlan_id):
         port = self.get_port_by_id(port_id)
         if port is None:
@@ -397,6 +460,14 @@ class VlanDB:
             raise
         return port_id
 
+    # Set the base vlan of a port in the database. The VLAN is
+    # passed by ID.
+    #
+    # Constraints:
+    # 1. The port must already exist
+    # 2. The port must not be a trunk port
+    # 3. The port must not be locked
+    # 1. The VLAN must already exist in the database
     def set_base_vlan(self, port_id, vlan_id):
         port = self.get_port_by_id(port_id)
         if port is None:
@@ -422,6 +493,12 @@ class VlanDB:
             raise
         return port_id
 
+    # Return a port back to its base VLAN
+    #
+    # Constraints:
+    # 1. The port must already exist
+    # 2. The port must not be a trunk port
+    # 3. The port must not be locked
     def restore_base_vlan(self, port_id):
         port = self.get_port_by_id(port_id)
         if port is None:
@@ -441,6 +518,7 @@ class VlanDB:
             raise
         return port_id
 
+    # Trivial helper function to return all the rows in a given table
     def _dump_table(self, table):
         result = []
         self.cursor.execute("SELECT * FROM %s" % table)