minor changes for better documentation and to automatically generate documentation using diaggen

Author: brean

pathfinding/core/node.py

@@ -1,8 +1,18 @@
+from __future__ import annotations
 import dataclasses
 
 
 @dataclasses.dataclass
 class Node:
+    h: float = 0.0
+    g: float = 0.0
+    f: float = 0.0
+    opened: int = 0
+    closed: bool = False
+    parent: Node = None
+    retain_count: int = 0
+    tested: bool = False
+
     def __post_init__(self):
         # values used in the finder
         self.cleanup()
@@ -94,10 +104,13 @@ def __iter__(self):
             yield self.grid_id
 
     def connect(self, other_node):
+        """
+        Connect two nodes with each other.
+        """
         if not self.connections:
             self.connections = [other_node]
         else:
             self.connections.append(other_node)
 
     def __repr__(self):
-        return f'<GridNode({self.x}:{self.y} {hex(id(self))})>'
+        return f'<GridNode({self.x}:{self.y} {hex(id(self))})>'

pathfinding/finder/a_star.py

@@ -5,12 +5,16 @@
 
 
 class AStarFinder(Finder):
+    """
+    Find shortest path using A* algorithm
+    """
+
     def __init__(self, heuristic=None, weight=1,
                  diagonal_movement=DiagonalMovement.never,
                  time_limit=TIME_LIMIT,
                  max_runs=MAX_RUNS):
         """
-        find shortest path using A* algorithm
+        Find shortest path using A* algorithm
         :param heuristic: heuristic used to calculate distance of 2 points
             (defaults to manhattan)
         :param weight: weight for the edges
@@ -40,7 +44,7 @@ def __init__(self, heuristic=None, weight=1,
     def check_neighbors(self, start, end, graph, open_list,
                         open_value=True, backtrace_by=None):
         """
-        find next path segment based on given node
+        Find next path segment based on given node
         (or return path if we found the end)
 
         :param start: start node

pathfinding/finder/bi_a_star.py

@@ -7,8 +7,9 @@
 
 class BiAStarFinder(AStarFinder):
     """
-    Similar to the default A* algorithm from a_star.
+    Run A* from start to end and end to start during path finding loop.
     """
+
     def __init__(self, heuristic=None, weight=1,
                  diagonal_movement=DiagonalMovement.never,
                  time_limit=TIME_LIMIT,

pathfinding/finder/breadth_first.py

@@ -4,6 +4,9 @@
 
 
 class BreadthFirstFinder(Finder):
+    """
+    Breadth-first algorithm, similar to Dijkstra or A* but without cost.
+    """
     def __init__(self, heuristic=None, weight=1,
                  diagonal_movement=DiagonalMovement.never,
                  time_limit=TIME_LIMIT,
@@ -15,8 +18,6 @@ def __init__(self, heuristic=None, weight=1,
             diagonal_movement=diagonal_movement,
             time_limit=time_limit,
             max_runs=max_runs)
-        if not diagonal_movement:
-            self.diagonalMovement = DiagonalMovement.never
 
     def check_neighbors(self, start, end, grid, open_list):
         node = open_list.pop_node()

pathfinding/finder/dijkstra.py

@@ -4,6 +4,10 @@
 
 
 class DijkstraFinder(AStarFinder):
+    """
+    Find shortest path using the best-first Dijkstra path finding algorithm.
+    """
+
     def __init__(self, weight=1,
                  diagonal_movement=DiagonalMovement.never,
                  time_limit=TIME_LIMIT,
@@ -17,6 +21,8 @@ def __init__(self, weight=1,
 
     def apply_heuristic(self, node_a, node_b, heuristic=None, graph=None):
         """
-        helper function to apply heuristic
+        Helper function to apply heuristic
+        
+        returns 0 as Dijkstra is not using any heuristic (but A* is).
         """
         return 0

pathfinding/finder/finder.py

@@ -15,11 +15,17 @@
 
 
 class ExecutionTimeException(Exception):
+    """
+    Exception that gets thrown when a certain time has been exceeded.
+    """
     def __init__(self, message):
         super(ExecutionTimeException, self).__init__(message)
 
 
 class ExecutionRunsException(Exception):
+    """
+    Exception that gets thrown when the number of max. runs has been reached.
+    """
     def __init__(self, message):
         super(ExecutionRunsException, self).__init__(message)
 
@@ -31,7 +37,7 @@ def __init__(self, heuristic=None, weight=1,
                  time_limit=TIME_LIMIT,
                  max_runs=MAX_RUNS):
         """
-        find shortest path
+        Find shortest path
         :param heuristic: heuristic used to calculate distance of 2 points
             (defaults to manhattan)
         :param weight: weight for the edges
@@ -58,7 +64,7 @@ def __init__(self, heuristic=None, weight=1,
 
     def apply_heuristic(self, node_a, node_b, heuristic=None, graph=None):
         """
-        helper function to apply heuristic
+        Helper function to apply heuristic
         """
         if not heuristic:
             heuristic = self.heuristic
@@ -84,15 +90,16 @@ def apply_heuristic(self, node_a, node_b, heuristic=None, graph=None):
 
     def find_neighbors(self, grid, node, diagonal_movement=None):
         '''
-        find neighbor, same for Djikstra, A*, Bi-A*, IDA*
+        Find neighbor, same for Djikstra, A*, Bi-A*, IDA*
         '''
         if not diagonal_movement:
             diagonal_movement = self.diagonal_movement
         return grid.neighbors(node, diagonal_movement=diagonal_movement)
 
     def keep_running(self):
         """
-        check, if we run into time or iteration constrains.
+        Check, if we run into time or iteration constrains.
+
         :returns: True if we keep running and False if we run into a constraint
         """
         if self.runs >= self.max_runs:
@@ -109,7 +116,7 @@ def keep_running(self):
     def process_node(
             self, graph, node, parent, end, open_list, open_value=True):
         '''
-        we check if the given node is part of the path by calculating its
+        We check if the given node is part of the path by calculating its
         cost and add or remove it from our path
         :param node: the node we like to test
             (the neighbor in A* or jump-node in JumpPointSearch)
@@ -143,7 +150,7 @@ def process_node(
     def check_neighbors(self, start, end, graph, open_list,
                         open_value=True, backtrace_by=None):
         """
-        find next path segment based on given node
+        Find next path segment based on given node
         (or return path if we found the end)
 
         :param start: start node
@@ -155,14 +162,14 @@ def check_neighbors(self, start, end, graph, open_list,
             'Please implement check_neighbors in your finder')
 
     def clean_grid(self, grid):
-        """clean the map if needed."""
+        """Clean the map if needed."""
         if grid.dirty:
             grid.cleanup()
         grid.dirty = True
 
     def find_path(self, start, end, grid):
         """
-        find a path from start to end node on grid by iterating over
+        Find a path from start to end node on grid by iterating over
         all neighbors of a node (see check_neighbors)
         :param start: start node
         :param end: end node
@@ -191,7 +198,7 @@ def find_path(self, start, end, grid):
 
     def __repr__(self):
         """
-        return a human readable representation
+        Return a human readable representation
         """
         return f"<{self.__class__.__name__}" \
             f"diagonal_movement={self.diagonal_movement} >"