da7e/amazing
1
0
Fork 0
mirror of https://github.com/maoakeEnterprise/amazing.git synced 2026-04-28 16:04:35 +02:00
Code Issues Packages Projects Releases Wiki Activity

Merge branch 'docstring'

Browse Source
This commit is contained in:
David GAILLETON
2026-04-01 17:42:48 +02:00
parent d2f38468a4 68c40be144
commit 3fe46026ec
8 changed files with 825 additions and 71 deletions
Download Patch File Download Diff File Expand all files Collapse all files
src/AMazeIng.py
+30
View File
@@ -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
+72
View File
@@ -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
+27
View File
@@ -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
+268 -46
View File
@@ -8,8 +8,18 @@ import random
class MazeGenerator(ABC):
def __init__(self, start: tuple[int, int], end: tuple[int, int],
perfect: bool) -> None:
"""Define the common interface and helpers for maze generators."""
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,
maze: NDArray[Any],
forty_two: set[tuple[int, int]] | None,
prob: float = 0.1
) -> Generator[NDArray[Any], None, NDArray[Any]]:
directions = {
"N": (0, -1),
"S": (0, 1),
"W": (-1, 0),
"E": (1, 0)
}
def unperfect_maze(
width: int,
height: int,
maze: NDArray[Any],
forty_two: set[tuple[int, int]] | None,
prob: float = 0.1,
) -> Generator[NDArray[Any], None, NDArray[Any]]:
"""Add extra openings to transform a perfect maze into an imperfect one.
reverse = {
"N": "S",
"S": "N",
"W": "E",
"E": "W"
}
Random walls are removed while optionally preserving the reserved
``forty_two`` area.
Args:
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 (
(y, x) in forty_two
or (ny, nx) in forty_two
):
if forty_two and ((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,
reverse[
direc])
cell_n = DepthFirstSearch.broken_wall(
cell_n,
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 (
a in sets.sets[i].cells or b in sets.sets[i].cells
):
elif base_set and (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,
cells_ft)
gen = Kruskal.unperfect_maze(width, height, maze, 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],
perfect: bool) -> None:
"""Generate a maze using a depth-first search backtracking algorithm."""
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,
self.forty_two)
gen = DepthFirstSearch.unperfect_maze(
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(
[[Cell(value=15) for _ in range(width)] for _ in range(height)]
)
"""Create a fully walled maze grid.
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]]
) -> list[tuple[int, int]]:
def add_cell_visited(
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],
w_h: tuple[int, int]) -> list[str]:
def random_cells(
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],
visited: NDArray[Any]) -> list[tuple[int, int]]:
def back_on_step(
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
+179 -7
View File
@@ -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],
maze: NDArray[Any], h_w: tuple[int, int]
) -> list[str]:
def random_path(
visited: NDArray[Any],
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
+100 -8
View File
@@ -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"],
res["PERFECT"])
DataMaze.get_solver_generator(
data,
res["ENTRY"],
res["EXIT"],
res["PERFECT"],
)
)
return res
@staticmethod
def get_solver_generator(data: dict[str, str], entry: tuple[int, int],
exit: tuple[int, int],
perfect: bool) -> dict[str, Any]:
def get_solver_generator(
data: dict[str, str],
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,
perfect)
res["GENERATOR"] = available_generator[data["GENERATOR"]](
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)