docstrings

frontier.py

@@ -7,20 +7,32 @@ def __init__(self):
         self._frontier = self._createFrontier()
 
     def _createFrontier(self):
-            frontier = SortedKeyList(key=treeNode.getF)
-            return frontier
+        """
+        :return: frontier data structure
+        """
+        frontier = SortedKeyList(key=treeNode.getF)
+        return frontier
 
     def insert(self, node):
+        """
+        inserts node into the frontier
+        :param node: node id string to insert
+        """
         if isinstance(node, treeNode):
             self._frontier.add(node)
         else:
             print("error. it is not a node")
 
     def remove(self):
+        """
+        removes node from the frontier
+        :return: node id string removed
+        """
         return self._frontier.pop(0)
 
     def isEmpty(self):
-        if bool(self._frontier): #true if has items, false otherwise
-            return False
-        else:
-            return True
+        """
+        :return: true/false if elements in the frontier
+        """
+        if bool(self._frontier): return False
+        else: return True

main.py

@@ -26,6 +26,10 @@ def main():
     call(['solu/gpx2svg', '-i', 'solu/out.gpx', '-o', 'solu/out.svg'])
 
 def askInfo():
+    """
+    :return: all user inputs needed to run the program
+    :raises ValueError: not entering a valid input
+    """
     try:
         filename = input('json file: ')
         if filename.isdigit():
@@ -55,6 +59,14 @@ def askInfo():
         sys.exit(1)
 
 def limSearch(problem, strategy, depthl, pruning, heu):
+    """
+    :param problem: problem class object
+    :param strategy: strategy int
+    :param depthl: depth limit int
+    :param pruning: pruning option boolean
+    :param heu: heuristic string
+    :return: goal node and number of elements in the frontier
+    """
     f = frontier(); problem._visitedList = {}
     num_f = 0
     initial = treeNode(problem._init_state, strategy)
@@ -81,6 +93,15 @@ def limSearch(problem, strategy, depthl, pruning, heu):
     else: return None
 
 def search(problem, strategy, depthl, depthi, pruning, heu):
+    """
+    :param problem: problem class object
+    :param strategy: strategy int
+    :param depthl: depth limit int
+    :param depthi: depth limit increment
+    :param pruning: pruning option boolean
+    :param heu: heuristic string
+    :return: path to the problem's solution
+    """
     depthact = depthi
     sol = None
     while(not sol and depthact <= depthl+1):
@@ -89,6 +110,13 @@ def search(problem, strategy, depthl, depthi, pruning, heu):
     return sol
 
 def createSolution(sol, itime, etime, num_f):
+    """
+    creates txt file with the solution + statistics
+    :param sol: problem solution
+    :param itime: initial time
+    :param etime: end time
+    :param num_f: number of elements in the frontier
+    """
     txt = open('solu/out.txt','w')
     if(sol is not None):
         list = []
@@ -110,6 +138,15 @@ def createSolution(sol, itime, etime, num_f):
     txt.close()
 
 def createGpx(problem, sol, itime, etime, num_f, stat):
+    """
+    creates gpx(xml) file representing the solution
+    :param problem: problem class object
+    :param sol: problem solution
+    :param itime: initial time
+    :param etime: end time
+    :param num_f: number of elements in the frontier
+    :param stat: strategy string
+    """
     if(sol is not None):
         list, points = [], []
         act = sol

problem.py

@@ -16,17 +16,26 @@ def __init__(self, json):
         self._visitedList = {}
 
     def _readJson(self):
+        """
+        :return: json data from file
+        """
         with open('json/' + self._json) as json_data:
             return json.load(json_data)
 
     def isGoal(self, state):
-        #input: state, output: true/false if list of nodes is empty
-        if bool(state._nodes): #true if has items, false otherwise
-            return False
-        else:
-            return True
+        """
+        :param state: state class object
+        :return: true/false if its list of nodes is empty
+        """
+        if bool(state._nodes): return False
+        else: return True
 
     def distance(self, node1, node2):
+        """
+        :param node1: osm node id string
+        :param node2: osm node id string
+        :return: distance (meters) between node1 and node2
+        """
         (lng1, lat1) = self._state_space.positionNode(node1)
         (lng2, lat2) = self._state_space.positionNode(node2)
         earth_radius = 6371009
@@ -43,6 +52,14 @@ def distance(self, node1, node2):
         return dist
 
     def createTreeNodes(self, ls, node, depthl, strategy, heu):
+        """
+        :param ls: list successors for a given state
+        :param node: actual node string
+        :param depthl: depth limit int
+        :param strategy: strategy int
+        :param heu: heuristic string
+        :return: list of all problem's nodes
+        """
         nodes = []; h = 0
         if(depthl >= node._d):
             for (action, result, cost) in ls:

state.py

@@ -8,12 +8,21 @@ def __init__(self, current, nodes, md5=None):
         else: self._md5 = md5
 
     def createCode(self, node, list):
-        #_current + _nodes to string
-        data = node + ''.join(str(i) for i in list)
+        """
+        :param node: current node id string
+        :param list: nodes' list to be visited
+        :return: md5 representation of a state
+        """
+        data = node + ''.join(str(i) for i in list) #_current + _nodes to string
         md5 = hashlib.new("md5", data.encode('utf-8')) #encode string
         return md5.hexdigest() #return hexadecimal string value
 
     def visited(self, id, old_list):
+        """
+        :param id: node id string
+        :param old_list: old nodes' list to be visited
+        :return: new list removing current or just the old one
+        """
         if id in old_list:
             new_list = old_list[:]
             new_list.remove(id)
@@ -22,7 +31,14 @@ def visited(self, id, old_list):
             return old_list
 
     def updateCode(self, aux):
+        """
+        updates md5 representation of a state
+        :param aux: state class auxiliar object
+        """
         self._md5 = self.createCode(aux._current, aux._nodes)
 
     def __str__(self):
+        """
+        :return: state to string
+        """
         return f'({self._current}, {self._nodes})'

stateSpace.py

@@ -8,6 +8,9 @@ def __init__(self, path):
         self._keys, self._nodes, self._edges = self._readFile()
 
     def _readFile(self):
+        """
+        :return: data from xml loaded into data structures
+        """
         data = etree.parse(self._path)
         root = data.getroot()
         ns = {'n': 'http://graphml.graphdrawing.org/xmlns'}
@@ -32,12 +35,19 @@ def _readFile(self):
         return keys, nodes, edges
 
     def belongNode(self, id):
-        #input: osm node, output: true/false if in nodes
+        """
+        :param id: osm node id string
+        :return: true/false if in nodes
+        """
         if id in self._nodes: return True
         else: return False
 
     def positionNode(self, id):
-        #input: osm node, output: latitude&longitude(y,x) of current node
+        """
+        :param id: osm node id string
+        :return: latitude&longitude(y,x) of the node
+        :raises ValueError: not entering a valid node id
+        """
         try:
             if self.belongNode(id):
                 return self._nodes[id]
@@ -47,7 +57,11 @@ def positionNode(self, id):
             print("error. the node does not exist"); sys.exit(1)
 
     def successors(self, id):
-        #input: problem state, output: list of adjacent nodes + extra info
+        """
+        :param id: state class object
+        :return: list of successors for given state + info(acc,aux,cost)
+        :raises ValueError: not entering a valid state for given json
+        """
         try:
             successors = []
             if self.belongNode(id._current):
@@ -61,4 +75,4 @@ def successors(self, id):
             else:
                 raise ValueError
         except ValueError:
-            print("error. the node does not belong to given json"); sys.exit(1)
+            print("error. the state does not belong to given json"); sys.exit(1)

treeNode.py

@@ -13,4 +13,7 @@ def __init__(self, state, strategy, parent=None, cost=0, action=None, h=0, d=1):
 		self._f = switch[strategy] #factory pattern
 
 	def getF(self):
+		"""
+		return: node's f value
+		"""
 		return self._f