Merge branch 'docstring'

a_maze_ing.py

@@ -7,7 +7,15 @@ import time
 
 
 class MazeMLX:
+    """Render, animate, and interact with a maze using an MLX window."""
+
     def __init__(self, height: int, width: int) -> None:
+        """Initialize the MLX renderer and create the window and image buffer.
+
+        Args:
+            height: Height of the rendering area in pixels.
+            width: Width of the rendering area in pixels.
+        """
         self.mlx = Mlx()
         self.height = height
         self.width = width
@@ -23,15 +31,23 @@ class MazeMLX:
         )
 
     def close(self) -> None:
+        """Destroy the image used by the renderer."""
         self.mlx.mlx_destroy_image(self.mlx_ptr, self.img_ptr)
 
     def close_loop(self, _: Any) -> None:
+        """Stop the MLX event loop.
+
+        Args:
+            _: Unused callback argument.
+        """
         self.mlx.mlx_loop_exit(self.mlx_ptr)
 
     def clear_image(self) -> None:
+        """Clear the image buffer."""
         self.buf[:] = b"\x00" * len(self.buf)
 
     def redraw_image(self) -> None:
+        """Redraw the window contents and display the control help text."""
         self.mlx.mlx_clear_window(self.mlx_ptr, self.win_ptr)
         self.mlx.mlx_put_image_to_window(
             self.mlx_ptr, self.win_ptr, self.img_ptr, 0, 0
@@ -45,8 +61,17 @@ class MazeMLX:
             "1: regen; 2: path; 3: color; 4: quit;",
         )
 
-    def put_pixel(self, x: int, y: int, color: list[Any] | None = None
+    def put_pixel(
-                  ) -> None:
+        self, x: int, y: int, color: list[Any] | None = None
+    ) -> None:
+        """Draw a single pixel into the image buffer.
+
+        Args:
+            x: Horizontal pixel position.
+            y: Vertical pixel position.
+            color: Optional RGBA color list. If omitted, the current renderer
+                color is used.
+        """
         if x < 0 or y < 0 or x >= self.width or y >= self.height:
             return
         offset = y * self.size_line + x * (self.bpp // 8)
@@ -70,6 +95,13 @@ class MazeMLX:
         end: tuple[int, int],
         color: list[Any] | None = None,
     ) -> None:
+        """Draw a horizontal or vertical line.
+
+        Args:
+            start: Starting pixel coordinates.
+            end: Ending pixel coordinates.
+            color: Optional RGBA color list.
+        """
         sx, sy = start
         ex, ey = end
         if sy == ey:
@@ -85,6 +117,13 @@ class MazeMLX:
         dr: tuple[int, int],
         color: list[Any] | None = None,
     ) -> None:
+        """Draw a filled rectangular block.
+
+        Args:
+            ul: Upper-left corner coordinates.
+            dr: Lower-right corner coordinates.
+            color: Optional RGBA color list.
+        """
         for y in range(min(ul[1], dr[1]), max(dr[1], ul[1])):
             self.put_line(
                 (min(ul[0], dr[0]), y), (max(ul[0], dr[0]), y), color
@@ -92,6 +131,11 @@ class MazeMLX:
 
     @staticmethod
     def random_color_ft() -> Any:
+        """Yield colors in a repeating sequence for the reserved pattern.
+
+        Yields:
+            RGBA color lists.
+        """
         colors = [
             [0xFF, 0xBF, 0x00, 0xFF],  # blue
             [0x00, 0xFF, 0x40, 0xFF],  # green
@@ -104,6 +148,11 @@ class MazeMLX:
 
     @staticmethod
     def random_color() -> Any:
+        """Yield colors in a repeating sequence for maze rendering.
+
+        Yields:
+            RGBA color lists.
+        """
         colors = [
             [0xFF, 0x00, 0xFF, 0xFF],  # pink
             [0x00, 0xFF, 0xFF, 0xFF],  # yellow
@@ -117,6 +166,15 @@ class MazeMLX:
                 yield color
 
     def get_margin_line_len(self, maze: NDArray[Any]) -> tuple[int, int, int]:
+        """Compute the cell size and margins for centering the maze.
+
+        Args:
+            maze: Maze grid to render.
+
+        Returns:
+            A tuple containing the cell side length, horizontal margin, and
+            vertical margin.
+        """
         rows = len(maze)
         cols = len(maze[0])
 
@@ -131,6 +189,11 @@ class MazeMLX:
         return (line_len, margin_x, margin_y)
 
     def update_maze(self, maze: NDArray[Any]) -> None:
+        """Render the maze walls into the image buffer.
+
+        Args:
+            maze: Maze grid to render.
+        """
         self.clear_image()
 
         line_len, margin_x, margin_y = self.get_margin_line_len(maze)
@@ -151,6 +214,15 @@ class MazeMLX:
                     self.put_line((x0, y0), (x0, y1))
 
     def put_path(self, amazing: AMazeIng) -> Any:
+        """Animate the solution path inside the maze.
+
+        Args:
+            amazing: Maze container with generation and solving logic.
+
+        Yields:
+            Control after each path segment so the animation can be rendered
+            progressively.
+        """
         path = amazing.solve_path()
         print(path)
         actual = amazing.entry
@@ -201,6 +273,11 @@ class MazeMLX:
         return
 
     def put_start_end(self, amazing: AMazeIng) -> None:
+        """Draw highlighted blocks for the maze entry and exit.
+
+        Args:
+            amazing: Maze container with current maze data.
+        """
         entry = amazing.entry
         exit = amazing.exit
         maze = amazing.maze.get_maze()
@@ -229,8 +306,15 @@ class MazeMLX:
         )
         self.put_block(ul, dr, [0x00, 0xFF, 0x40, 0x9F])
 
-    def draw_ft(self, maze: NDArray[Any], color: list[Any] | None = None
+    def draw_ft(
-                ) -> None:
+        self, maze: NDArray[Any], color: list[Any] | None = None
+    ) -> None:
+        """Draw filled cells corresponding to the reserved fully walled pattern.
+
+        Args:
+            maze: Maze grid to inspect.
+            color: Optional RGBA color list.
+        """
         line_len, margin_x, margin_y = self.get_margin_line_len(maze)
 
         for y in range(len(maze)):
@@ -244,6 +328,11 @@ class MazeMLX:
 
     def draw_image(self, amazing: AMazeIng) -> None:
         maze = amazing.maze.get_maze()
+        """Main rendering callback used by the MLX loop.
+
+        Args:
+            amazing: Maze container to render.
+        """
         if self.render_maze(amazing):
             if self.print_path:
                 if self.render_path():
@@ -260,27 +349,50 @@ class MazeMLX:
         self.redraw_image()
 
     def shift_color(self) -> None:
+        """Reset the maze color generator."""
         self.color_gen = self.random_color()
 
     def shift_color_ft(self) -> None:
+        """Reset the reserved-pattern color generator."""
         self.color_gen_ft = self.random_color_ft()
 
     def time_gen(self) -> None:
+        """Reset the timing generator used for animation pacing."""
         self.timer_gen = self.time_generator()
 
     def restart_maze(self, amazing: AMazeIng) -> None:
+        """Restart maze generation.
+
+        Args:
+            amazing: Maze container providing the generation generator.
+        """
         self.generator = amazing.generate()
 
     def time_generator(self) -> Any:
+        """Yield regularly with a fixed delay for animation timing.
+
+        Yields:
+            ``None`` at each step after sleeping.
+        """
         yield
         while True:
             time.sleep(0.3)
             yield
 
     def restart_path(self, amazing: AMazeIng) -> None:
+        """Restart solution path animation.
+
+        Args:
+            amazing: Maze container providing the solution path.
+        """
         self.path_printer = self.put_path(amazing)
 
     def render_path(self) -> bool:
+        """Advance the path animation by one step.
+
+        Returns:
+            ``True`` if the path animation is complete, otherwise ``False``.
+        """
         try:
             next(self.path_printer)
             time.sleep(0.03)
@@ -290,6 +402,14 @@ class MazeMLX:
         return True
 
     def render_maze(self, amazing: AMazeIng) -> bool:
+        """Advance maze generation by one step and redraw it.
+
+        Args:
+            amazing: Maze container being generated.
+
+        Returns:
+            ``True`` if maze generation is complete, otherwise ``False``.
+        """
         try:
             maze = amazing.maze.get_maze()
             next(self.generator)
@@ -301,6 +421,12 @@ class MazeMLX:
         return True
 
     def handle_key_press(self, keycode: int, amazing: AMazeIng) -> None:
+        """Handle keyboard input for one keycode mapping.
+
+        Args:
+            keycode: Key code received from MLX.
+            amazing: Maze container to update or render.
+        """
         if keycode == 49:
             self.restart_maze(amazing)
             self.print_path = False
@@ -313,8 +439,15 @@ class MazeMLX:
         if keycode == 52:
             self.close_loop(None)
 
-    def handle_key_press_mteriier(self, keycode: int,
+    def handle_key_press_mteriier(
-                                  amazing: AMazeIng) -> None:
+        self, keycode: int, amazing: AMazeIng
+    ) -> None:
+        """Handle keyboard input for an alternative keycode mapping.
+
+        Args:
+            keycode: Key code received from MLX.
+            amazing: Maze container to update or render.
+        """
         if keycode == 38:
             self.restart_maze(amazing)
             self.print_path = False
@@ -328,6 +461,11 @@ class MazeMLX:
             self.close_loop(None)
 
     def start(self, amazing: AMazeIng) -> None:
+        """Start the MLX rendering loop.
+
+        Args:
+            amazing: Maze container to generate, solve, and display.
+        """
         self.restart_maze(amazing)
         self.shift_color()
         self.shift_color_ft()
@@ -341,6 +479,7 @@ class MazeMLX:
 
 
 def main() -> None:
+    """Run the maze application."""
     mlx = None
     try:
         mlx = MazeMLX(1000, 1000)

config.txt

@@ -1,8 +1,8 @@
 WIDTH=10
 HEIGHT=10
 ENTRY=1,1
-EXIT=5,5
+EXIT=10,10
 OUTPUT_FILE=maze.txt
-PERFECT=False
+PERFECT=True
-GENERATOR=DFS
+GENERATOR=Kruskal
-SOLVER=DFS
+SOLVER=AStar

src/AMazeIng.py

@@ -6,6 +6,8 @@ from .amaz_lib import Maze, MazeGenerator, MazeSolver
 
 
 class AMazeIng(BaseModel):
+    """Represent a complete maze configuration, generation, and solving setup."""
+
     model_config = ConfigDict(arbitrary_types_allowed=True)
 
     width: int = Field(ge=4)
@@ -20,6 +22,14 @@ class AMazeIng(BaseModel):
 
     @model_validator(mode="after")
     def check_entry_exit(self) -> Self:
+        """Validate that entry and exit coordinates fit within maze bounds.
+
+        Returns:
+            The validated model instance.
+
+        Raises:
+            ValueError: If entry or exit coordinates exceed maze dimensions.
+        """
         if self.entry[0] > self.width or self.entry[1] > self.height:
             raise ValueError("Entry coordinates exceed the maze size")
         if self.exit[0] > self.width or self.exit[1] > self.height:
@@ -27,15 +37,35 @@ class AMazeIng(BaseModel):
         return self
 
     def generate(self) -> Generator[Maze, None, None]:
+        """Generate the maze step by step.
+
+        The internal maze state is updated at each generation step.
+
+        Yields:
+            The current maze state after each generation step.
+        """
         for array in self.generator.generator(self.height, self.width):
             self.maze.set_maze(array)
             yield self.maze
         return
 
     def solve_path(self) -> str:
+        """Solve the current maze and return the path string.
+
+        Returns:
+            A string of direction letters representing the solution path.
+        """
         return self.solver.solve(self.maze, self.height, self.width)
 
     def __str__(self) -> str:
+        """Return a string representation of the maze and its solution.
+
+        The output includes the maze, entry coordinates, exit coordinates, and
+        the computed solution path.
+
+        Returns:
+            A formatted string representation of the maze data.
+        """
         res = self.maze.__str__()
         res += "\n"
         res += f"{self.entry[0]},{self.entry[1]}\n"

src/amaz_lib/Cell.py

@@ -3,50 +3,122 @@ from dataclasses import dataclass
 
 @dataclass
 class Cell:
+    """Represent a maze cell encoded as a bitmask of surrounding walls.
+
+    The cell value is stored as an integer where each bit represents the
+    presence of a wall in one cardinal direction:
+
+    - bit 0 (1): north wall
+    - bit 1 (2): east wall
+    - bit 2 (4): south wall
+    - bit 3 (8): west wall
+    """
+
     def __init__(self, value: int) -> None:
+        """Initialize a cell with its encoded wall value.
+
+        Args:
+            value: Integer bitmask representing the cell walls.
+        """
         self.value = value
 
     def __str__(self) -> str:
+        """Return the hexadecimal representation of the cell value.
+
+        Returns:
+            The uppercase hexadecimal form of the cell value without the
+            ``0x`` prefix.
+        """
         return hex(self.value).removeprefix("0x").upper()
 
     def set_value(self, value: int) -> None:
+        """Set the encoded value of the cell.
+
+        Args:
+            value: Integer bitmask representing the cell walls.
+        """
         self.value = value
 
     def get_value(self) -> int:
+        """Return the encoded value of the cell.
+
+        Returns:
+            The integer bitmask representing the cell walls.
+        """
         return self.value
 
     def set_north(self, is_wall: bool) -> None:
+        """Set or clear the north wall.
+
+        Args:
+            is_wall: ``True`` to add the north wall, ``False`` to remove it.
+        """
         if (not is_wall and self.value | 14 == 15) or (
             is_wall and self.value | 14 != 15
         ):
             self.value = self.value ^ (1)
 
     def get_north(self) -> bool:
+        """Return whether the north wall is present.
+
+        Returns:
+            ``True`` if the north wall is set, otherwise ``False``.
+        """
         return self.value & 1 == 1
 
     def set_est(self, is_wall: bool) -> None:
+        """Set or clear the east wall.
+
+        Args:
+            is_wall: ``True`` to add the east wall, ``False`` to remove it.
+        """
         if (not is_wall and self.value | 13 == 15) or (
             is_wall and self.value | 13 != 15
         ):
             self.value = self.value ^ (2)
 
     def get_est(self) -> bool:
+        """Return whether the east wall is present.
+
+        Returns:
+            ``True`` if the east wall is set, otherwise ``False``.
+        """
         return self.value & 2 == 2
 
     def set_south(self, is_wall: bool) -> None:
+        """Set or clear the south wall.
+
+        Args:
+            is_wall: ``True`` to add the south wall, ``False`` to remove it.
+        """
         if (not is_wall and self.value | 11 == 15) or (
             is_wall and self.value | 11 != 15
         ):
             self.value = self.value ^ (4)
 
     def get_south(self) -> bool:
+        """Return whether the south wall is present.
+
+        Returns:
+            ``True`` if the south wall is set, otherwise ``False``.
+        """
         return self.value & 4 == 4
 
     def set_west(self, is_wall: bool) -> None:
+        """Set or clear the west wall.
+
+        Args:
+            is_wall: ``True`` to add the west wall, ``False`` to remove it.
+        """
         if (not is_wall and self.value | 7 == 15) or (
             is_wall and self.value | 7 != 15
         ):
             self.value = self.value ^ (8)
 
     def get_west(self) -> bool:
+        """Return whether the west wall is present.
+
+        Returns:
+            ``True`` if the west wall is set, otherwise ``False``.
+        """
         return self.value & 8 == 8

src/amaz_lib/Maze.py

@@ -5,15 +5,37 @@ from typing import Optional, Any
 
 @dataclass
 class Maze:
+    """Represent a maze as a two-dimensional array of cells."""
+
     maze: Optional[NDArray[Any]] = None
 
     def get_maze(self) -> Optional[NDArray[Any]]:
+        """Return the underlying maze array.
+
+        Returns:
+            The two-dimensional array representing the maze, or ``None`` if no
+            maze has been set.
+        """
         return self.maze
 
     def set_maze(self, new_maze: NDArray[Any]) -> None:
+        """Set the maze array.
+
+        Args:
+            new_maze: A two-dimensional array containing the maze cells.
+        """
         self.maze = new_maze
 
     def __str__(self) -> str:
+        """Return a string representation of the maze.
+
+        Each cell is converted to its string representation and concatenated
+        line by line.
+
+        Returns:
+            A multiline string representation of the maze, or ``"None"`` if the
+            maze is not set.
+        """
         if self.maze is None:
             return "None"
         res = ""
@@ -24,6 +46,11 @@ class Maze:
         return res
 
     def ascii_print(self) -> None:
+        """Print an ASCII representation of the maze.
+
+        The maze is rendered using underscores and vertical bars to show the
+        walls of each cell. If no maze is set, ``"None"`` is printed.
+        """
         if self.maze is None:
             print("None")
             return

src/amaz_lib/MazeGenerator.py

@@ -8,8 +8,18 @@ import random
 
 
 class MazeGenerator(ABC):
-    def __init__(self, start: tuple[int, int], end: tuple[int, int],
+    """Define the common interface and helpers for maze generators."""
-                 perfect: bool) -> None:
+
+    def __init__(
+        self, start: tuple[int, int], end: tuple[int, int], perfect: bool
+    ) -> None:
+        """Initialize the maze generator.
+
+        Args:
+            start: Starting cell coordinates, using 1-based indexing.
+            end: Ending cell coordinates, using 1-based indexing.
+            perfect: Whether to generate a perfect maze with no loops.
+        """
         self.start = (start[0] - 1, start[1] - 1)
         self.end = (end[0] - 1, end[1] - 1)
         self.perfect = perfect
@@ -17,10 +27,33 @@ class MazeGenerator(ABC):
     @abstractmethod
     def generator(
         self, height: int, width: int, seed: int | None = None
-    ) -> Generator[NDArray[Any], None, NDArray[Any]]: ...
+    ) -> Generator[NDArray[Any], None, NDArray[Any]]:
+        """Generate a maze step by step.
+
+        Args:
+            height: Number of rows in the maze.
+            width: Number of columns in the maze.
+            seed: Optional random seed for reproducibility.
+
+        Yields:
+            Intermediate maze states during generation.
+
+        Returns:
+            The final generated maze.
+        """
+        ...
 
     @staticmethod
     def get_cell_ft(width: int, height: int) -> set[tuple[int, int]]:
+        """Return the coordinates used to reserve the '42' pattern.
+
+        Args:
+            width: Number of columns in the maze.
+            height: Number of rows in the maze.
+
+        Returns:
+            A set of cell coordinates belonging to the reserved pattern.
+        """
         forty_two = set()
         y, x = (int(height / 2), int(width / 2))
         forty_two.add((y, x - 1))
@@ -44,24 +77,36 @@ class MazeGenerator(ABC):
         return forty_two
 
     @staticmethod
-    def unperfect_maze(width: int, height: int,
+    def unperfect_maze(
-                       maze: NDArray[Any],
+        width: int,
-                       forty_two: set[tuple[int, int]] | None,
+        height: int,
-                       prob: float = 0.1
+        maze: NDArray[Any],
-                       ) -> Generator[NDArray[Any], None, NDArray[Any]]:
+        forty_two: set[tuple[int, int]] | None,
-        directions = {
+        prob: float = 0.1,
-            "N": (0, -1),
+    ) -> Generator[NDArray[Any], None, NDArray[Any]]:
-            "S": (0, 1),
+        """Add extra openings to transform a perfect maze into an imperfect one.
-            "W": (-1, 0),
-            "E": (1, 0)
-        }
 
-        reverse = {
+        Random walls are removed while optionally preserving the reserved
-            "N": "S",
+            ``forty_two`` area.
-            "S": "N",
+
-            "W": "E",
+        Args:
-            "E": "W"
+            width: Number of columns in the maze.
-        }
+            height: Number of rows in the maze.
+            maze: The maze to modify.
+            forty_two: Optional set of reserved coordinates that must not be
+                altered.
+            prob: Probability of breaking an eligible wall.
+
+        Yields:
+            Intermediate maze states after each wall removal.
+
+        Returns:
+            The modified maze.
+        """
+
+        directions = {"N": (0, -1), "S": (0, 1), "W": (-1, 0), "E": (1, 0)}
+
+        reverse = {"N": "S", "S": "N", "W": "E", "E": "W"}
         min_break = 2
         while True:
             count = 0
@@ -71,10 +116,7 @@ class MazeGenerator(ABC):
                         continue
                     for direc, (dx, dy) in directions.items():
                         nx, ny = x + dx, y + dy
-                        if forty_two and (
+                        if forty_two and ((y, x) in forty_two or (ny, nx) in forty_two):
-                            (y, x) in forty_two
-                            or (ny, nx) in forty_two
-                        ):
                             continue
                         if not (0 <= nx < width and 0 < ny < height):
                             continue
@@ -85,9 +127,10 @@ class MazeGenerator(ABC):
                             cell = maze[y][x]
                             cell_n = maze[ny][nx]
                             cell = DepthFirstSearch.broken_wall(cell, direc)
-                            cell_n = DepthFirstSearch.broken_wall(cell_n,
+                            cell_n = DepthFirstSearch.broken_wall(
-                                                                  reverse[
+                                cell_n,
-                                                                    direc])
+                                reverse[direc],
+                            )
                             maze[y][x] = cell
                             maze[ny][nx] = cell_n
                             yield maze
@@ -97,19 +140,46 @@ class MazeGenerator(ABC):
 
 
 class Kruskal(MazeGenerator):
+    """Generate a maze using a Kruskal-based algorithm."""
 
     class KruskalSet:
+        """Represent a connected component of maze cells."""
+
         def __init__(self, cells: list[int]) -> None:
+            """Initialize a set of connected cells.
+
+            Args:
+                cells: List of cell indices belonging to the set.
+            """
             self.cells: list[int] = cells
 
     class Sets:
-        def __init__(self, sets: list['Kruskal.KruskalSet']) -> None:
+        """Store all connected components used during generation."""
+
+        def __init__(self, sets: list["Kruskal.KruskalSet"]) -> None:
+            """Initialize the collection of connected components.
+
+            Args:
+                sets: List of disjoint cell sets.
+            """
             self.sets = sets
 
     @staticmethod
     def walls_to_maze(
         walls: list[tuple[int, int]], height: int, width: int
     ) -> NDArray[Any]:
+        """Convert a list of remaining walls into a maze grid.
+
+        Args:
+            walls: Collection of wall pairs between adjacent cells.
+            height: Number of rows in the maze.
+            width: Number of columns in the maze.
+
+        Returns:
+            A two-dimensional array of :class:`Cell` instances representing the
+            maze.
+        """
+
         maze: NDArray[Any] = np.array(
             [[Cell(value=0) for _ in range(width)] for _ in range(height)]
         )
@@ -136,6 +206,15 @@ class Kruskal(MazeGenerator):
 
     @staticmethod
     def is_in_same_set(sets: Sets, wall: tuple[int, int]) -> bool:
+        """Check whether both cells connected by a wall are in the same set.
+
+        Args:
+            sets: Current collection of connected components.
+            wall: Pair of adjacent cell indices.
+
+        Returns:
+            ``True`` if both cells belong to the same set, otherwise ``False``.
+        """
         a, b = wall
         for set in sets.sets:
             if a in set.cells and b in set.cells:
@@ -146,6 +225,15 @@ class Kruskal(MazeGenerator):
 
     @staticmethod
     def merge_sets(sets: Sets, wall: tuple[int, int]) -> None:
+        """Merge the two sets connected by the given wall.
+
+        Args:
+            sets: Current collection of connected components.
+            wall: Pair of adjacent cell indices.
+
+        Raises:
+            Exception: If the two corresponding sets cannot be found.
+        """
         a, b = wall
         base_set = None
         for i in range(len(sets.sets)):
@@ -153,9 +241,7 @@ class Kruskal(MazeGenerator):
                 a in sets.sets[i].cells or b in sets.sets[i].cells
             ):
                 base_set = sets.sets[i]
-            elif base_set and (
+            elif base_set and (a in sets.sets[i].cells or b in sets.sets[i].cells):
-                a in sets.sets[i].cells or b in sets.sets[i].cells
-            ):
                 base_set.cells += sets.sets[i].cells
                 sets.sets.pop(i)
                 return
@@ -167,6 +253,17 @@ class Kruskal(MazeGenerator):
         wall: tuple[int, int],
         cells_ft: None | set[tuple[int, int]],
     ) -> bool:
+        """Check whether a wall touches the reserved '42' pattern.
+
+        Args:
+            width: Number of columns in the maze.
+            wall: Pair of adjacent cell indices.
+            cells_ft: Reserved coordinates, or ``None``.
+
+        Returns:
+            ``True`` if either endpoint of the wall belongs to the reserved
+            pattern, otherwise ``False``.
+        """
         if cells_ft is None:
             return False
         s1 = (math.trunc(wall[0] / width), wall[0] % width)
@@ -176,6 +273,19 @@ class Kruskal(MazeGenerator):
     def generator(
         self, height: int, width: int, seed: int | None = None
     ) -> Generator[NDArray[Any], None, NDArray[Any]]:
+        """Generate a maze using a Kruskal-based approach.
+
+        Args:
+            height: Number of rows in the maze.
+            width: Number of columns in the maze.
+            seed: Optional random seed for reproducibility.
+
+        Yields:
+            Intermediate maze states during generation.
+
+        Returns:
+            The final generated maze.
+        """
         cells_ft = None
         if height > 10 and width > 10:
             cells_ft = self.get_cell_ft(width, height)
@@ -212,8 +322,7 @@ class Kruskal(MazeGenerator):
         print(f"nb sets: {len(sets.sets)}")
         maze = self.walls_to_maze(walls, height, width)
         if self.perfect is False:
-            gen = Kruskal.unperfect_maze(width, height, maze,
+            gen = Kruskal.unperfect_maze(width, height, maze, cells_ft)
-                                         cells_ft)
             for res in gen:
                 maze = res
                 yield maze
@@ -221,8 +330,18 @@ class Kruskal(MazeGenerator):
 
 
 class DepthFirstSearch(MazeGenerator):
-    def __init__(self, start: tuple[int, int], end: tuple[int, int],
+    """Generate a maze using a depth-first search backtracking algorithm."""
-                 perfect: bool) -> None:
+
+    def __init__(
+        self, start: tuple[int, int], end: tuple[int, int], perfect: bool
+    ) -> None:
+        """Initialize the depth-first search generator.
+
+        Args:
+            start: Starting cell coordinates, using 1-based indexing.
+            end: Ending cell coordinates, using 1-based indexing.
+            perfect: Whether to generate a perfect maze with no loops.
+        """
         self.start = (start[0] - 1, start[1] - 1)
         self.end = (end[0] - 1, end[1] - 1)
         self.perfect = perfect
@@ -231,6 +350,19 @@ class DepthFirstSearch(MazeGenerator):
     def generator(
         self, height: int, width: int, seed: int | None = None
     ) -> Generator[NDArray[Any], None, NDArray[Any]]:
+        """Generate a maze using depth-first search.
+
+        Args:
+            height: Number of rows in the maze.
+            width: Number of columns in the maze.
+            seed: Optional random seed for reproducibility.
+
+        Yields:
+            Intermediate maze states during generation.
+
+        Returns:
+            The final generated maze.
+        """
         if seed is not None:
             np.random.seed(seed)
         maze = self.init_maze(width, height)
@@ -274,8 +406,12 @@ class DepthFirstSearch(MazeGenerator):
             maze[y][x] = self.broken_wall(maze[y][x], wall_r)
             yield maze
         if self.perfect is False:
-            gen = DepthFirstSearch.unperfect_maze(width, height, maze,
+            gen = DepthFirstSearch.unperfect_maze(
-                                                  self.forty_two)
+                width,
+                height,
+                maze,
+                self.forty_two,
+            )
             for res in gen:
                 maze = res
                 yield maze
@@ -283,20 +419,49 @@ class DepthFirstSearch(MazeGenerator):
 
     @staticmethod
     def init_maze(width: int, height: int) -> NDArray[Any]:
-        maze = np.array(
+        """Create a fully walled maze grid.
-            [[Cell(value=15) for _ in range(width)] for _ in range(height)]
+
-        )
+        Args:
+            width: Number of columns in the maze.
+            height: Number of rows in the maze.
+
+        Returns:
+            A two-dimensional array of cells initialized with all walls present.
+        """
+        maze = np.array([[Cell(value=15) for _ in range(width)] for _ in range(height)])
         return maze
 
     @staticmethod
-    def add_cell_visited(coord: tuple[int, int], path: list[tuple[int, int]]
+    def add_cell_visited(
-                         ) -> list[tuple[int, int]]:
+        coord: tuple[int, int], path: list[tuple[int, int]]
+    ) -> list[tuple[int, int]]:
+        """Append a visited coordinate to the current traversal path.
+
+        Args:
+            coord: Coordinate of the visited cell.
+            path: Current traversal path.
+
+        Returns:
+            The updated path.
+        """
         path.append(coord)
         return path
 
     @staticmethod
-    def random_cells(visited: NDArray[Any], coord: tuple[int, int],
+    def random_cells(
-                     w_h: tuple[int, int]) -> list[str]:
+        visited: NDArray[Any], coord: tuple[int, int], w_h: tuple[int, int]
+    ) -> list[str]:
+        """Return the list of unvisited neighboring directions.
+
+        Args:
+            visited: Boolean array marking visited cells.
+            coord: Current cell coordinate.
+            w_h: Tuple containing maze width and height.
+
+        Returns:
+            A list of direction strings among ``"N"``, ``"S"``, ``"W"``, and
+            ``"E"``.
+        """
         rand_cell: list[str] = []
         x, y = coord
         width, height = w_h
@@ -316,10 +481,27 @@ class DepthFirstSearch(MazeGenerator):
 
     @staticmethod
     def next_step(rand_cell: list[str]) -> str:
+        """Select the next direction at random.
+
+        Args:
+            rand_cell: List of candidate directions.
+
+        Returns:
+            A randomly selected direction.
+        """
         return random.choice(rand_cell)
 
     @staticmethod
     def broken_wall(cell: Cell, wall: str) -> Cell:
+        """Remove the specified wall from a cell.
+
+        Args:
+            cell: The cell to modify.
+            wall: Direction of the wall to remove.
+
+        Returns:
+            The modified cell.
+        """
         if wall == "N":
             cell.set_north(False)
         elif wall == "S":
@@ -332,17 +514,48 @@ class DepthFirstSearch(MazeGenerator):
 
     @staticmethod
     def next_cell(x: int, y: int, next: str) -> tuple[int, int]:
+        """Return the coordinates of the adjacent cell in the given direction.
+
+        Args:
+            x: Current column index.
+            y: Current row index.
+            next: Direction to move.
+
+        Returns:
+            The coordinates of the next cell.
+        """
         next_step = {"N": (0, -1), "S": (0, 1), "W": (-1, 0), "E": (1, 0)}
         add_x, add_y = next_step[next]
         return (x + add_x, y + add_y)
 
     @staticmethod
     def reverse_path(direction: str) -> str:
+        """Return the opposite cardinal direction.
+
+        Args:
+            direction: Input direction.
+
+        Returns:
+            The opposite direction.
+        """
         return {"N": "S", "S": "N", "W": "E", "E": "W"}[direction]
 
     @staticmethod
-    def back_on_step(path: list[tuple[int, int]], w_h: tuple[int, int],
+    def back_on_step(
-                     visited: NDArray[Any]) -> list[tuple[int, int]]:
+        path: list[tuple[int, int]],
+        w_h: tuple[int, int],
+        visited: NDArray[Any],
+    ) -> list[tuple[int, int]]:
+        """Backtrack through the path until a cell with unvisited neighbors is found.
+
+        Args:
+            path: Current traversal path.
+            w_h: Tuple containing maze width and height.
+            visited: Boolean array marking visited cells.
+
+        Returns:
+            The truncated path after backtracking.
+        """
         while path:
             last = path[-1]
             if DepthFirstSearch.random_cells(visited, last, w_h):
@@ -354,6 +567,15 @@ class DepthFirstSearch(MazeGenerator):
     def lock_cell_ft(
         visited: NDArray[Any], forty_two: set[tuple[int, int]]
     ) -> NDArray[Any]:
+        """Mark the reserved '42' pattern cells as already visited.
+
+        Args:
+            visited: Boolean array marking visited cells.
+            forty_two: Set of reserved cell coordinates.
+
+        Returns:
+            The updated visited array.
+        """
         tab = [cell for cell in forty_two]
         for cell in tab:
             visited[cell] = True

src/amaz_lib/MazeSolver.py

@@ -7,18 +7,41 @@ import random
 
 
 class MazeSolver(ABC):
+    """Define the common interface for maze-solving algorithms."""
+
     def __init__(self, start: tuple[int, int], end: tuple[int, int]) -> None:
+        """Initialize the maze solver.
+
+        Args:
+            start: Start coordinates using 1-based indexing.
+            end: End coordinates using 1-based indexing.
+        """
         self.start = (start[1] - 1, start[0] - 1)
         self.end = (end[1] - 1, end[0] - 1)
 
     @abstractmethod
     def solve(
         self, maze: Maze, height: int | None = None, width: int | None = None
-    ) -> str: ...
+    ) -> str:
+        """Solve the maze and return the path as direction letters.
+
+        Args:
+            maze: The maze to solve.
+            height: Optional maze height.
+            width: Optional maze width.
+
+        Returns:
+            A string representing the path using cardinal directions.
+        """
+        ...
 
 
 class AStar(MazeSolver):
+    """Solve a maze using the A* pathfinding algorithm."""
+
     class Node:
+        """Represent a node used during A* exploration."""
+
         def __init__(
             self,
             coordinate: tuple[int, int],
@@ -27,6 +50,15 @@ class AStar(MazeSolver):
             f: int,
             parent: Any,
         ) -> None:
+            """Initialize a search node.
+
+            Args:
+                coordinate: Coordinates of the node.
+                g: Cost from the start node.
+                h: Heuristic cost to the goal.
+                f: Total estimated cost.
+                parent: Parent node in the reconstructed path.
+            """
             self.coordinate = coordinate
             self.g = g
             self.h = h
@@ -34,12 +66,35 @@ class AStar(MazeSolver):
             self.parent = parent
 
         def __eq__(self, value: object, /) -> bool:
+            """Compare a node to a coordinate.
+
+            Args:
+                value: Object to compare with.
+
+            Returns:
+                ``True`` if the value equals the node coordinate, otherwise
+                ``False``.
+            """
             return value == self.coordinate
 
     def __init__(self, start: tuple[int, int], end: tuple[int, int]) -> None:
+        """Initialize the A* solver.
+
+        Args:
+            start: Start coordinates using 1-based indexing.
+            end: End coordinates using 1-based indexing.
+        """
         super().__init__(start, end)
 
     def h(self, n: tuple[int, int]) -> int:
+        """Compute the Manhattan distance heuristic to the goal.
+
+        Args:
+            n: Coordinates of the current node.
+
+        Returns:
+            The heuristic distance to the end coordinate.
+        """
         return (
             max(n[0], self.end[0])
             - min(n[0], self.end[0])
@@ -51,8 +106,18 @@ class AStar(MazeSolver):
         self,
         maze: NDArray[Any],
         actual: tuple[int, int],
-        close: list['Node'],
+        close: list["Node"],
     ) -> list[tuple[int, int]]:
+        """Return all reachable neighboring coordinates.
+
+        Args:
+            maze: Maze grid to inspect.
+            actual: Current coordinate.
+            close: List of already explored nodes.
+
+        Returns:
+            A list of reachable adjacent coordinates not yet closed.
+        """
         path = [
             (
                 (actual[0], actual[1] - 1)
@@ -89,7 +154,18 @@ class AStar(MazeSolver):
         ]
         return [p for p in path if p is not None]
 
-    def get_path(self, maze: NDArray[Any]) -> list['Node']:
+    def get_path(self, maze: NDArray[Any]) -> list["Node"]:
+        """Perform A* exploration until the destination is reached.
+
+        Args:
+            maze: Maze grid to solve.
+
+        Returns:
+            The closed list ending with the goal node.
+
+        Raises:
+            Exception: If no path can be found.
+        """
         open: list[AStar.Node] = []
         close: list[AStar.Node] = []
 
@@ -123,6 +199,17 @@ class AStar(MazeSolver):
         raise Exception("Path not found")
 
     def get_rev_dir(self, current: Node) -> str:
+        """Determine the direction taken from the parent to the current node.
+
+        Args:
+            current: Current node in the reconstructed path.
+
+        Returns:
+            A cardinal direction letter.
+
+        Raises:
+            Exception: If the parent-child relationship cannot be translated.
+        """
         if current.parent.coordinate == (
             current.coordinate[0],
             current.coordinate[1] - 1,
@@ -146,7 +233,15 @@ class AStar(MazeSolver):
         else:
             raise Exception("Translate error: AStar path not found")
 
-    def translate(self, close: list['Node']) -> str:
+    def translate(self, close: list["Node"]) -> str:
+        """Translate a node chain into a path string.
+
+        Args:
+            close: Closed list ending with the goal node.
+
+        Returns:
+            A string of direction letters from start to end.
+        """
         current = close[-1]
         res = ""
         while True:
@@ -159,6 +254,17 @@ class AStar(MazeSolver):
     def solve(
         self, maze: Maze, height: int | None = None, width: int | None = None
     ) -> str:
+        """Solve the maze using A*.
+
+        Args:
+            maze: The maze to solve.
+            height: Unused optional maze height.
+            width: Unused optional maze width.
+
+        Returns:
+            A string representing the path using cardinal directions.
+        """
+
         maze_arr = maze.get_maze()
         if maze_arr is None:
             raise Exception("Maze is not initialized")
@@ -167,12 +273,33 @@ class AStar(MazeSolver):
 
 
 class DepthFirstSearchSolver(MazeSolver):
+    """Solve a maze using depth-first search with backtracking."""
+
     def __init__(self, start: tuple[int, int], end: tuple[int, int]):
+        """Initialize the depth-first search solver.
+
+        Args:
+            start: Start coordinates using 1-based indexing.
+            end: End coordinates using 1-based indexing.
+        """
         super().__init__(start, end)
 
     def solve(
         self, maze: Maze, height: int | None = None, width: int | None = None
     ) -> str:
+        """Solve the maze using depth-first search.
+
+        Args:
+            maze: The maze to solve.
+            height: Maze height.
+            width: Maze width.
+
+        Returns:
+            A string representing the path using cardinal directions.
+
+        Raises:
+            Exception: If no path can be found.
+        """
         path_str = ""
         if height is None or width is None:
             raise Exception("We need Height and Width in the arg")
@@ -207,9 +334,23 @@ class DepthFirstSearchSolver(MazeSolver):
         return path_str
 
     @staticmethod
-    def random_path(visited: NDArray[Any], coord: tuple[int, int],
+    def random_path(
-                    maze: NDArray[Any], h_w: tuple[int, int]
+        visited: NDArray[Any],
-                    ) -> list[str]:
+        coord: tuple[int, int],
+        maze: NDArray[Any],
+        h_w: tuple[int, int],
+    ) -> list[str]:
+        """Return all valid unvisited directions from the current cell.
+
+        Args:
+            visited: Boolean array marking visited cells.
+            coord: Current coordinate.
+            maze: Maze grid to inspect.
+            h_w: Tuple containing maze height and width.
+
+        Returns:
+            A list of valid direction letters.
+        """
         random_p = []
         h, w = h_w
         y, x = coord
@@ -229,6 +370,15 @@ class DepthFirstSearchSolver(MazeSolver):
 
     @staticmethod
     def next_path(rand_path: list[str]) -> str:
+        """Select the next move at random.
+
+        Args:
+            rand_path: List of available directions.
+
+        Returns:
+            A randomly selected direction.
+        """
+
         return random.choice(rand_path)
 
     @staticmethod
@@ -239,6 +389,19 @@ class DepthFirstSearchSolver(MazeSolver):
         h_w: tuple[int, int],
         move: list[str],
     ) -> tuple[list[Any], list[Any]]:
+        """Backtrack until a cell with an unexplored path is found.
+
+        Args:
+            path: Current path of visited coordinates.
+            visited: Boolean array marking visited cells.
+            maze: Maze grid to inspect.
+            h_w: Tuple containing maze height and width.
+            move: List of moves made so far.
+
+        Returns:
+            A tuple containing the updated path and move list.
+        """
+
         while path:
             last = path[-1]
             if DepthFirstSearchSolver.random_path(visited, last, maze, h_w):
@@ -249,6 +412,15 @@ class DepthFirstSearchSolver(MazeSolver):
 
     @staticmethod
     def next_cell(coord: tuple[int, int], next: str) -> tuple[int, int]:
+        """Return the coordinates of the next cell in the given direction.
+
+        Args:
+            coord: Current coordinate.
+            next: Direction to move.
+
+        Returns:
+            The coordinates of the next cell.
+        """
         y, x = coord
         next_step = {"N": (-1, 0), "S": (1, 0), "W": (0, -1), "E": (0, 1)}
         add_y, add_x = next_step[next]

src/parsing/Parsing.py

@@ -4,9 +4,21 @@ from typing import Any
 
 
 class DataMaze:
+    """Provide helper methods to load and validate maze configuration data."""
 
     @staticmethod
     def get_file_data(name_file: str) -> str:
+        """Read and return the contents of a configuration file.
+
+        Args:
+            name_file: Path to the configuration file.
+
+        Returns:
+            The file contents as a string.
+
+        Raises:
+            ValueError: If the file is empty.
+        """
         with open(name_file, "r") as file:
             data = file.read()
         if data == "":
@@ -15,6 +27,16 @@ class DataMaze:
 
     @staticmethod
     def transform_data(data: str) -> dict[str, str]:
+        """Transform raw configuration text into a dictionary.
+
+        Each non-empty line containing ``=`` is split into a key-value pair.
+
+        Args:
+            data: Raw configuration text.
+
+        Returns:
+            A dictionary mapping configuration keys to their string values.
+        """
         tmp = data.split("\n")
         tmp2 = [value.split("=", 1) for value in tmp if "=" in value]
         data_t = {value[0]: value[1] for value in tmp2}
@@ -22,6 +44,14 @@ class DataMaze:
 
     @staticmethod
     def verif_key_data(data: dict[str, str]) -> None:
+        """Validate that the configuration contains the expected keys.
+
+        Args:
+            data: Configuration dictionary to validate.
+
+        Raises:
+            KeyError: If keys are missing or unexpected keys are present.
+        """
         key_test = {
             "WIDTH",
             "HEIGHT",
@@ -43,6 +73,15 @@ class DataMaze:
 
     @staticmethod
     def convert_values(data: dict[str, str]) -> dict[str, Any]:
+        """Convert configuration values to their appropriate Python types.
+
+        Args:
+            data: Raw configuration dictionary with string values.
+
+        Returns:
+            A dictionary containing converted values and instantiated solver and
+            generator objects.
+        """
         key_int = {"WIDTH", "HEIGHT"}
         key_tuple = {"ENTRY", "EXIT"}
         key_bool = {"PERFECT"}
@@ -55,31 +94,65 @@ class DataMaze:
             res.update({key: DataMaze.convert_bool(data[key])})
         res.update({"OUTPUT_FILE": data["OUTPUT_FILE"]})
         res.update(
-            DataMaze.get_solver_generator(data, res["ENTRY"], res["EXIT"],
+            DataMaze.get_solver_generator(
-                                          res["PERFECT"])
+                data,
+                res["ENTRY"],
+                res["EXIT"],
+                res["PERFECT"],
+            )
         )
         return res
 
     @staticmethod
-    def get_solver_generator(data: dict[str, str], entry: tuple[int, int],
+    def get_solver_generator(
-                             exit: tuple[int, int],
+        data: dict[str, str],
-                             perfect: bool) -> dict[str, Any]:
+        entry: tuple[int, int],
+        exit: tuple[int, int],
+        perfect: bool,
+    ) -> dict[str, Any]:
+        """Instantiate the configured maze generator and solver.
+
+        Args:
+            data: Raw configuration dictionary.
+            entry: Entry coordinates.
+            exit: Exit coordinates.
+            perfect: Whether the maze must be perfect.
+
+        Returns:
+            A dictionary containing initialized ``GENERATOR`` and ``SOLVER``
+            objects.
+        """
         available_generator: dict[str, Any] = {
             "Kruskal": Kruskal,
             "DFS": DepthFirstSearch,
         }
         available_solver: dict[str, Any] = {
             "AStar": AStar,
-            "DFS": DepthFirstSearchSolver
+            "DFS": DepthFirstSearchSolver,
         }
         res = {}
-        res["GENERATOR"] = available_generator[data["GENERATOR"]](entry, exit,
+        res["GENERATOR"] = available_generator[data["GENERATOR"]](
-                                                                  perfect)
+            entry,
+            exit,
+            perfect,
+        )
         res["SOLVER"] = available_solver[data["SOLVER"]](entry, exit)
         return res
 
     @staticmethod
     def convert_tuple(data: str) -> tuple[int, int]:
+        """Convert a comma-separated coordinate string into a tuple.
+
+        Args:
+            data: Coordinate string in the form ``"x,y"``.
+
+        Returns:
+            A tuple of two integers.
+
+        Raises:
+            ValueError: If the coordinate string does not contain exactly two
+                values.
+        """
         data_t = data.split(",")
         if len(data_t) != 2:
             raise ValueError(
@@ -91,6 +164,17 @@ class DataMaze:
 
     @staticmethod
     def convert_bool(data: str) -> bool:
+        """Convert a string to a boolean value.
+
+        Args:
+            data: String representation of a boolean.
+
+        Returns:
+            ``True`` if the string is ``"True"``, otherwise ``False``.
+
+        Raises:
+            ValueError: If the string is neither ``"True"`` nor ``"False"``.
+        """
         if data != "True" and data != "False":
             raise ValueError("This is not True or False")
         if data == "True":
@@ -99,6 +183,14 @@ class DataMaze:
 
     @staticmethod
     def get_data_maze(name_file: str) -> dict[str, Any]:
+        """Load, validate, and convert maze configuration data from a file.
+
+        Args:
+            name_file: Path to the configuration file.
+
+        Returns:
+            A dictionary of validated configuration values with lowercase keys.
+        """
         try:
             data_str = DataMaze.get_file_data(name_file)
             data_dict = DataMaze.transform_data(data_str)