need to be merge

add clean and fclean method to Makefile

.gitignore

@@ -214,4 +214,6 @@ __marimo__/
 
 # Streamlit
 .streamlit/secrets.toml
+test.txt
 
+mazegen-1.0.0-py3-none-any.whl

Makefile

@@ -1,22 +1,41 @@
+build:
+	uv build --clear --wheel
+	cp dist/*.whl mazegen-1.0.0-py3-none-any.whl
+
 install:
 	uv sync
+	uv pip install mlx-2.2-py3-none-any.whl
 
 run: install
 	uv run python3 a_maze_ing.py config.txt
 
+run_windows:
+	.venv\Scripts\python -m a_maze_ing config.txt
+
 debug:
 	uv pdb python3 a_maze_ing.py config.txt
 
 clean:
-	rm -rf __pycache__ .mypy_cache .venv
+	rm -rf */**/__pycache__ */__pycache__ __pycache__ .mypy_cache .venv dist build */**/*.egg-info */*.egg-info *.egg-info test.txt
+
+fclean: clean
+	rm mazegen-1.0.0-py3-none-any.whl 
 
 lint:
 	uv run flake8 . --exclude=.venv
-	uv run mypy . --warn-return-any --warn-unused-ignores --ignore-missing-imports --disallow-untyped-defs --check-untyped-defs
+	uv run env PYTHONPATH=src python3 -m mypy --warn-return-any --warn-unused-ignores --ignore-missing-imports --disallow-untyped-defs --check-untyped-defs -p mazegen
+	uv run env PYTHONPATH=src python3 -m mypy --warn-return-any --warn-unused-ignores --ignore-missing-imports --disallow-untyped-defs --check-untyped-defs -p parsing
+	uv run env PYTHONPATH=src python3 -m mypy --warn-return-any --warn-unused-ignores --ignore-missing-imports --disallow-untyped-defs --check-untyped-defs src/AMazeIng.py
+	uv run env PYTHONPATH=src python3 -m mypy --warn-return-any --warn-unused-ignores --ignore-missing-imports --disallow-untyped-defs --check-untyped-defs tests
+	uv run env PYTHONPATH=src python3 -m mypy --warn-return-any --warn-unused-ignores --ignore-missing-imports --disallow-untyped-defs --check-untyped-defs a_maze_ing.py
 
 lint-strict:
-	uv run flake8 .
-	uv run mypy . --strict
+	uv run flake8 . --exclude=.venv
+	uv run env PYTHONPATH=src python3 -m mypy --strict -p mazegen
+	uv run env PYTHONPATH=src python3 -m mypy --strict src/AMazeIng.py
+	uv run env PYTHONPATH=src python3 -m mypy --strict -p parsing
+	uv run env PYTHONPATH=src python3 -m mypy --strict tests
+	uv run env PYTHONPATH=src python3 -m mypy --strict a_maze_ing.py
 
 run_test_parsing:
 	PYTHONPATH=src uv run pytest tests/test_parsing.py
@@ -28,3 +47,7 @@ run_test_maze_gen:
 	PYTHONPATH=src uv run pytest tests/test_MazeGenerator.py
 run_test:
 	uv run pytest
+mlx:
+	uv run python3 test.py
+
+.PHONY: build install run debug clean fclean lint lint-strict run_test

README.md

@@ -1,3 +1 @@
-The Randomized Kruskal's Algorithm
-
-The Randomized Prim's Algorithm
+SITULITUPU

a_maze_ing.py

@@ -1,23 +1,500 @@
-import os
-from src.amaz_lib import Maze
-from src.amaz_lib import MazeGenerator
-import src.amaz_lib as g
+from typing import Any
+from numpy.typing import NDArray
+from AMazeIng import AMazeIng
+from parsing.Parsing import DataMaze as Parsing
+from mlx import Mlx
+import time
 
 
-def main(maze_gen: MazeGenerator) -> None:
-    # try:
-    maze = Maze(maze=None)
-    for alg in maze_gen.generator(10, 10):
-        maze.set_maze(alg)
-        os.system("clear")
-    maze.ascii_print()
-    # solver = AStar((1, 1), (14, 18))
-    # print(solver.solve(maze))
+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
+        self.print_path = False
+        self.color = [0x00, 0x00, 0xFF, 0xFF]
+        self.mlx_ptr = self.mlx.mlx_init()
+        self.win_ptr = self.mlx.mlx_new_window(
+            self.mlx_ptr, width, height + 200, "A-Maze-Ing"
+        )
+        self.img_ptr = self.mlx.mlx_new_image(self.mlx_ptr, width, height)
+        self.buf, self.bpp, self.size_line, self.format = (
+            self.mlx.mlx_get_data_addr(self.img_ptr)
+        )
+
+    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
+        )
+        self.mlx.mlx_string_put(
+            self.mlx_ptr,
+            self.win_ptr,
+            self.width // 3,
+            self.height + 100,
+            0xFFFFFF,
+            "1: regen; 2: path; 3: color; 4: quit;",
+        )
+
+    def put_pixel(
+        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)
+
+        if color:
+            self.buf[offset + 0] = color[0]
+            self.buf[offset + 1] = color[1]
+            self.buf[offset + 2] = color[2]
+            if self.bpp >= 32:
+                self.buf[offset + 3] = color[3]
+        else:
+            self.buf[offset + 0] = self.color[0]
+            self.buf[offset + 1] = self.color[1]
+            self.buf[offset + 2] = self.color[2]
+            if self.bpp >= 32:
+                self.buf[offset + 3] = self.color[3]
+
+    def put_line(
+        self,
+        start: tuple[int, int],
+        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:
+            for x in range(min(sx, ex), max(sx, ex) + 1):
+                self.put_pixel(x, sy, color)
+        if sx == ex:
+            for y in range(min(sy, ey), max(sy, ey) + 1):
+                self.put_pixel(sx, y, color)
+
+    def put_block(
+        self,
+        ul: tuple[int, int],
+        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
+            )
+
+    @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
+            [0xFF, 0x00, 0xFF, 0xFF],  # pink
+            [0x00, 0xFF, 0xFF, 0xFF],  # yellow
+        ]
+        while True:
+            for color in colors:
+                yield color
+
+    @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
+            [0x00, 0xFF, 0x40, 0xFF],  # green
+            [0xFF, 0xBF, 0x00, 0xFF],  # blue
+            [0xFF, 0x00, 0x80, 0xFF],  # purple
+            [0x00, 0x00, 0xFF, 0xFF],  # red
+        ]
+        while True:
+            for color in colors:
+                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])
+
+        line_len = min(self.width // cols, self.height // rows) - 1
+
+        maze_width = cols * line_len
+        maze_height = rows * line_len
+
+        margin_x = ((self.width - maze_width) // 2) + 1
+        margin_y = ((self.height - maze_height) // 2) + 1
+
+        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)
+        for y in range(len(maze)):
+            for x in range(len(maze[0])):
+                x0 = x * line_len + margin_x
+                y0 = y * line_len + margin_y
+                x1 = x * line_len + line_len + margin_x
+                y1 = y * line_len + line_len + margin_y
+
+                if maze[y][x].get_north():
+                    self.put_line((x0, y0), (x1, y0))
+                if maze[y][x].get_est():
+                    self.put_line((x1, y0), (x1, y1))
+                if maze[y][x].get_south():
+                    self.put_line((x0, y1), (x1, y1))
+                if maze[y][x].get_west():
+                    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
+        actual = (actual[0] - 1, actual[1] - 1)
+        maze = amazing.maze.get_maze()
+        if maze is None:
+            return
+
+        line_len, margin_x, margin_y = self.get_margin_line_len(maze)
+
+        for i in range(len(path)):
+            ul = (
+                (actual[0]) * line_len + margin_x + 12,
+                (actual[1]) * line_len + 12 + margin_y,
+            )
+            dr = (
+                (actual[0]) * line_len + line_len + margin_x - 12,
+                (actual[1]) * line_len + line_len - 12 + margin_y,
+            )
+            self.put_block(ul, dr)
+            x0 = actual[0] * line_len + margin_x + 12
+            y0 = actual[1] * line_len + margin_y + 12
+            x1 = actual[0] * line_len + line_len + margin_x - 12
+            y1 = actual[1] * line_len + line_len + margin_y - 12
+            yield
+            match path[i]:
+                case "N":
+                    self.put_block((x0, y0), (x1, y0 - 24))
+                    actual = (actual[0], actual[1] - 1)
+                case "E":
+                    self.put_block((x1, y0), (x1 + 24, y1))
+                    actual = (actual[0] + 1, actual[1])
+                case "S":
+                    self.put_block((x0, y1), (x1, y1 + 24))
+                    actual = (actual[0], actual[1] + 1)
+                case "W":
+                    self.put_block((x0, y0), (x0 - 24, y1))
+                    actual = (actual[0] - 1, actual[1])
+        ul = (
+            (actual[0]) * line_len + margin_x + 12,
+            (actual[1]) * line_len + 12 + margin_y,
+        )
+        dr = (
+            (actual[0]) * line_len + line_len + margin_x - 12,
+            (actual[1]) * line_len + line_len - 12 + margin_y,
+        )
+        self.put_block(ul, dr)
+        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()
+        if maze is None:
+            return
+
+        line_len, margin_x, margin_y = self.get_margin_line_len(maze)
+
+        ul = (
+            (entry[0] - 1) * line_len + margin_x + 3,
+            (entry[1] - 1) * line_len + 3 + margin_y,
+        )
+        dr = (
+            (entry[0] - 1) * line_len + line_len + margin_x - 3,
+            (entry[1] - 1) * line_len + line_len - 3 + margin_y,
+        )
+        self.put_block(ul, dr, [0xFF, 0xBF, 0x00, 0x9F])
+
+        ul = (
+            (exit[0] - 1) * line_len + margin_x + 3,
+            (exit[1] - 1) * line_len + 3 + margin_y,
+        )
+        dr = (
+            (exit[0] - 1) * line_len + line_len + margin_x - 3,
+            (exit[1] - 1) * line_len + line_len - 3 + margin_y,
+        )
+        self.put_block(ul, dr, [0x00, 0xFF, 0x40, 0x9F])
+
+    def draw_ft(
+        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)):
+            for x in range(len(maze[0])):
+                if maze[y][x].value == 15:
+                    x0 = x * line_len + margin_x
+                    y0 = y * line_len + margin_y
+                    x1 = x * line_len + line_len + margin_x
+                    y1 = y * line_len + line_len + margin_y
+                    self.put_block((x0, y0), (x1, y1), color)
+
+    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():
+                    color = next(self.color_gen_ft)
+                    if maze is not None:
+                        self.draw_ft(maze, color)
+                    next(self.timer_gen)
+            else:
+                self.time_gen()
+                if maze is not None:
+                    self.update_maze(maze)
+                    self.draw_ft(maze)
+            self.put_start_end(amazing)
+        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)
+            return False
+        except StopIteration:
+            pass
+        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)
+            if maze is not None:
+                self.update_maze(maze)
+            return False
+        except StopIteration:
+            pass
+        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
+        if keycode == 50:
+            self.restart_path(amazing)
+            self.print_path = True if self.print_path is False else False
+        if keycode == 51:
+            self.print_path = False
+            self.color = next(self.color_gen)
+        if keycode == 52:
+            self.close_loop(None)
+
+    def handle_key_press_mteriier(
+        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
+        if keycode == 233:
+            self.restart_path(amazing)
+            self.print_path = True if self.print_path is False else False
+        if keycode == 34:
+            self.print_path = False
+            self.color = next(self.color_gen)
+        if keycode == 39:
+            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()
+        self.time_gen()
+        self.mlx.mlx_loop_hook(self.mlx_ptr, self.draw_image, amazing)
+        self.mlx.mlx_hook(self.win_ptr, 33, 0, self.close_loop, None)
+        self.mlx.mlx_hook(
+            self.win_ptr, 2, 1 << 0, self.handle_key_press_mteriier, amazing
+        )
+        self.mlx.mlx_loop(self.mlx_ptr)
 
 
-# except Exception as err:
-# print(err)
+def main() -> None:
+    """Run the maze application."""
+    mlx = None
+    try:
+        mlx = MazeMLX(1000, 1000)
+        config = Parsing.get_data_maze("config.txt")
+        amazing = AMazeIng(**config)
+        mlx.start(amazing)
+        with open("test.txt", "w") as output:
+            output.write(amazing.__str__())
+    except Exception as err:
+        print(err)
+    finally:
+        if mlx is not None:
+            mlx.close()
 
 
 if __name__ == "__main__":
-    main(g.DepthFirstSearch())
+    main()

config.txt

@@ -1,6 +1,8 @@
-WIDTH=200
-HEIGHT=100
-ENTRY=0,0
-EXIT=19,14
+WIDTH=10
+HEIGHT=10
+ENTRY=1,1
+EXIT=10,10
 OUTPUT_FILE=maze.txt
-PERFECT=True
+PERFECT=True
+GENERATOR=Kruskal
+SOLVER=AStar

output_validator.py

@@ -1,25 +0,0 @@
-# This script does not check for errors or malformed files.
-# It only validates that neighbooring cells sharing a wall have
-#  both the correct encoding.
-# Usage: python3 output_validator.py output_maze.txt
-
-import sys
-
-if len(sys.argv) != 2:
-    print(f"Usage: python3 {sys.argv[0]} <output_file>")
-    sys.exit(1)
-
-g = []
-for line in open(sys.argv[1]):
-    if line.strip() == '':
-        break
-    g.append([int(c, 16) for c in line.strip(' \t\n\r')])
-
-for r in range(len(g)):
-    for c in range(len(g[0])):
-        v = g[r][c]
-        if not all([(r < 1 or v & 1 == (g[r-1][c] >> 2) & 1),
-                    (c >= len(g[0])-1 or (v >> 1) & 1 == (g[r][c+1] >> 3) & 1),
-                    (r >= len(g)-1 or (v >> 2) & 1 == g[r+1][c] & 1),
-                    (c < 1 or (v >> 3) & 1 == (g[r][c-1] >> 1) & 1)]):
-            print(f'Wrong encoding for ({c},{r})')

pyproject.toml

@@ -1,5 +1,5 @@
 [project]
-name = "A-Maze-ing"
+name = "mazegen"
 version = "0.1.0"
 description = "This is the way"
 readme = "README.md"
@@ -20,6 +20,18 @@ dev = [
 
 [tool.mypy]
 python_version = "3.10"
+explicit_package_bases = true
 
 [tool.pytest.ini_options]
 pythonpath = ["src"]
+
+[build-system]
+requires = ["setuptools>=78.1.0", "wheel>=0.45.1"]
+build-backend = "setuptools.build_meta"
+
+[tool.setuptools]
+package-dir = {"" = "src"}
+
+[tool.setuptools.packages.find]
+where = ["src"]
+

src/AMazeIng.py

@@ -1,42 +1,73 @@
-from dataclasses import field
-from os import eventfd_read
 from typing import Generator
-import numpy
 from typing_extensions import Self
-from pydantic import AfterValidator, BaseModel, Field, model_validator
+from pydantic import BaseModel, Field, model_validator, ConfigDict
 
-from amaz_lib import Maze, MazeGenerator, MazeSolver
-from amaz_lib.Cell import Cell
+from mazegen import Maze, MazeGenerator, MazeSolver
 
 
 class AMazeIng(BaseModel):
-    width: int = Field(ge=3)
-    height: int = Field(ge=3)
+    """Represent a complete maze configuration, generation,
+    and solving setup.
+    """
+
+    model_config = ConfigDict(arbitrary_types_allowed=True)
+
+    width: int = Field(ge=4)
+    height: int = Field(ge=4)
     entry: tuple[int, int]
     exit: tuple[int, int]
     output_file: str = Field(min_length=3)
     perfect: bool = Field(default=True)
-    maze: Maze = Field(default=Maze(maze=numpy.array([])))
+    maze: Maze = Field(default=Maze(None))
     generator: MazeGenerator
     solver: MazeSolver
 
     @model_validator(mode="after")
     def check_entry_exit(self) -> Self:
-        if self.entry[0] >= self.width or self.entry[1] >= self.height:
+        """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:
+        if self.exit[0] > self.width or self.exit[1] > self.height:
             raise ValueError("Exit coordinates exceed the maze size")
         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:
-        return self.solver.solve(self.maze)
+        """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

@@ -1,52 +0,0 @@
-from dataclasses import dataclass
-
-
-@dataclass
-class Cell:
-    def __init__(self, value: int) -> None:
-        self.value = value
-
-    def __str__(self) -> str:
-        return hex(self.value).removeprefix("0x").upper()
-
-    def set_value(self, value: int) -> None:
-        self.value = value
-
-    def get_value(self) -> int:
-        return self.value
-
-    def set_north(self, is_wall: bool) -> None:
-        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 self.value & 1 == 1
-
-    def set_est(self, is_wall: bool) -> None:
-        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 self.value & 2 == 2
-
-    def set_south(self, is_wall: bool) -> None:
-        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 self.value & 4 == 4
-
-    def set_west(self, is_wall: bool) -> None:
-        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 self.value & 8 == 8

src/amaz_lib/Maze.py

@@ -1,48 +0,0 @@
-from dataclasses import dataclass
-
-import numpy
-from .Cell import Cell
-from .MazeGenerator import MazeGenerator
-
-
-@dataclass
-class Maze:
-    maze: numpy.ndarray
-
-    def get_maze(self) -> numpy.ndarray | None:
-        return self.maze
-
-    def set_maze(self, new_maze: numpy.ndarray) -> None:
-        self.maze = new_maze
-
-    def __str__(self) -> str:
-        if self.maze is None:
-            return "None"
-        res = ""
-        for line in self.maze:
-            for cell in line:
-                res += cell.__str__()
-            res += "\n"
-        return res
-
-    def ascii_print(self) -> None:
-        for cell in self.maze[0]:
-            print("_", end="")
-            if cell.get_north():
-                print("__", end="")
-            else:
-                print("  ", end="")
-        print("_")
-        for line in self.maze:
-            for cell in line:
-                if cell is line[0] and cell.get_west():
-                    print("|", end="")
-                if cell.get_south() is True:
-                    print("__", end="")
-                else:
-                    print("  ", end="")
-                if cell.get_est() is True:
-                    print("|", end="")
-                else:
-                    print("_", end="")
-            print()

src/amaz_lib/MazeGenerator.py

@@ -1,247 +0,0 @@
-from abc import ABC, abstractmethod
-from typing import Generator, Set
-import numpy as np
-from .Cell import Cell
-import math
-
-
-class MazeGenerator(ABC):
-    @abstractmethod
-    def generator(
-        self, height: int, width: int, seed: int = None
-    ) -> Generator[np.ndarray, None, np.ndarray]: ...
-
-    @staticmethod
-    def get_cell_ft(width: int, height: int) -> set:
-        forty_two = set()
-        y, x = (int(height / 2), int(width / 2))
-        forty_two.add((y, x - 1))
-        forty_two.add((y, x - 2))
-        forty_two.add((y, x - 3))
-        forty_two.add((y - 1, x - 3))
-        forty_two.add((y - 2, x - 3))
-        forty_two.add((y + 1, x - 1))
-        forty_two.add((y + 2, x - 1))
-        forty_two.add((y, x + 1))
-        forty_two.add((y, x + 2))
-        forty_two.add((y, x + 3))
-        forty_two.add((y - 1, x + 3))
-        forty_two.add((y - 2, x + 3))
-        forty_two.add((y - 2, x + 2))
-        forty_two.add((y - 2, x + 1))
-        forty_two.add((y + 1, x + 1))
-        forty_two.add((y + 2, x + 1))
-        forty_two.add((y + 2, x + 2))
-        forty_two.add((y + 2, x + 3))
-        return forty_two
-
-
-class Kruskal(MazeGenerator):
-    class Set:
-        def __init__(self, cells: list[int]) -> None:
-            self.cells: list[int] = cells
-
-    class Sets:
-        def __init__(self, sets: list[Set]) -> None:
-            self.sets = sets
-
-    @staticmethod
-    def walls_to_maze(
-        walls: np.ndarray, height: int, width: int
-    ) -> np.ndarray:
-        maze: np.ndarray = np.array(
-            [[Cell(value=0) for _ in range(width)] for _ in range(height)]
-        )
-        for wall in walls:
-            x, y = wall
-            match y - x:
-                case 1:
-                    maze[math.trunc((x / width))][x % width].set_est(True)
-                    maze[math.trunc((y / width))][y % width].set_west(True)
-                case width:
-                    maze[math.trunc((x / width))][x % width].set_south(True)
-                    maze[math.trunc((y / width))][y % width].set_north(True)
-        for x in range(height):
-            for y in range(width):
-                if x == 0:
-                    maze[x][y].set_north(True)
-                if x == height - 1:
-                    maze[x][y].set_south(True)
-                if y == 0:
-                    maze[x][y].set_west(True)
-                if y == width - 1:
-                    maze[x][y].set_est(True)
-        return maze
-
-    @staticmethod
-    def is_in_same_set(sets: Sets, wall: tuple[int, int]) -> bool:
-        a, b = wall
-        for set in sets.sets:
-            if a in set.cells and b in set.cells:
-                return True
-            elif a in set.cells or b in set.cells:
-                return False
-        return False
-
-    @staticmethod
-    def merge_sets(sets: Sets, wall: tuple[int, int]) -> None:
-        a, b = wall
-        base_set = None
-        for i in range(len(sets.sets)):
-            if base_set is None and (
-                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
-            ):
-                base_set.cells += sets.sets[i].cells
-                sets.sets.pop(i)
-                return
-        raise Exception("two sets not found")
-
-    def generator(
-        self, height: int, width: int, seed: int = None
-    ) -> Generator[np.ndarray, None, np.ndarray]:
-        if seed is not None:
-            np.random.seed(seed)
-        sets = self.Sets([self.Set([i]) for i in range(height * width)])
-        walls = []
-        for h in range(height):
-            for w in range(width - 1):
-                walls += [(w + (width * h), w + (width * h) + 1)]
-        for h in range(height - 1):
-            for w in range(width):
-                walls += [(w + (width * h), w + (width * (h + 1)))]
-        print(walls)
-        np.random.shuffle(walls)
-
-        yield self.walls_to_maze(walls, height, width)
-        while len(sets.sets) > 1:
-            for wall in walls:
-                if not self.is_in_same_set(sets, wall):
-                    self.merge_sets(sets, wall)
-                    walls.remove(wall)
-                    yield self.walls_to_maze(walls, height, width)
-                if len(sets.sets) == 1:
-                    break
-        print(f"nb sets: {len(sets.sets)}")
-        return self.walls_to_maze(walls, height, width)
-
-
-class DepthFirstSearch(MazeGenerator):
-
-    def generator(
-        self, height: int, width: int, seed: int = None
-    ) -> Generator[np.ndarray, None, np.ndarray]:
-        if seed is not None:
-            np.random.seed(seed)
-        maze = self.init_maze(width, height)
-        forty_two = self.get_cell_ft(width, height)
-        visited = np.zeros((height, width), dtype=bool)
-        visited = self.lock_cell_ft(visited, forty_two)
-        path = list()
-        w_h = (width, height)
-        coord = (0, 0)
-        x, y = coord
-        first_iteration = True
-
-        while path or first_iteration:
-            first_iteration = False
-
-            visited[y, x] = True
-            path = self.add_cell_visited(coord, path)
-
-            random_c = self.random_cells(visited, coord, w_h)
-
-            if not random_c:
-                path = self.back_on_step(path, w_h, visited)
-                if not path:
-                    break
-                coord = path[-1]
-                random_c = self.random_cells(visited, coord, w_h)
-                x, y = coord
-
-            wall = self.next_step(random_c)
-            maze[y][x] = self.broken_wall(maze[y][x], wall)
-
-            coord = self.next_cell(x, y, wall)
-            wall_r = self.reverse_path(wall)
-            x, y = coord
-            maze[y][x] = self.broken_wall(maze[y][x], wall_r)
-            yield maze
-        return maze
-
-    @staticmethod
-    def init_maze(width: int, height: int) -> np.ndarray:
-        maze = np.array(
-            [[Cell(value=15) for _ in range(width)] for _ in range(height)]
-        )
-        return maze
-
-    @staticmethod
-    def add_cell_visited(coord: tuple, path: set) -> list:
-        path.append(coord)
-        return path
-
-    @staticmethod
-    def random_cells(visited: np.array, coord: tuple, w_h: tuple) -> list:
-        rand_cell = []
-        x, y = coord
-        width, height = w_h
-
-        if y - 1 >= 0 and not visited[y - 1][x]:
-            rand_cell.append("N")
-
-        if y + 1 < height and not visited[y + 1][x]:
-            rand_cell.append("S")
-
-        if x - 1 >= 0 and not visited[y][x - 1]:
-            rand_cell.append("W")
-
-        if x + 1 < width and not visited[y][x + 1]:
-            rand_cell.append("E")
-        return rand_cell
-
-    @staticmethod
-    def next_step(rand_cell: list) -> str:
-        return np.random.choice(rand_cell)
-
-    @staticmethod
-    def broken_wall(cell: Cell, wall: str) -> Cell:
-        if wall == "N":
-            cell.set_north(False)
-        elif wall == "S":
-            cell.set_south(False)
-        elif wall == "W":
-            cell.set_west(False)
-        elif wall == "E":
-            cell.set_est(False)
-        return cell
-
-    @staticmethod
-    def next_cell(x: int, y: int, next: str) -> tuple:
-        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 {"N": "S", "S": "N", "W": "E", "E": "W"}[direction]
-
-    @staticmethod
-    def back_on_step(path: list, w_h: tuple, visited: np.array) -> list:
-        while path:
-            last = path[-1]
-            if DepthFirstSearch.random_cells(visited, last, w_h):
-                break
-            path.pop()
-        return path
-
-    @staticmethod
-    def lock_cell_ft(visited: np.ndarray, forty_two: set[tuple[int]]
-                     ) -> np.ndarray:
-        tab = [cell for cell in forty_two]
-        for cell in tab:
-            visited[cell] = True
-        return visited

src/amaz_lib/MazeSolver.py

@@ -1,121 +0,0 @@
-from abc import ABC, abstractmethod
-from .Maze import Maze
-import numpy as np
-
-
-class MazeSolver(ABC):
-    def __init__(self, start: tuple[int, int], end: tuple[int, int]) -> None:
-        self.start = (start[0] - 1, start[1] - 1)
-        self.end = (end[0] - 1, end[1] - 1)
-
-    @abstractmethod
-    def solve(self, maze: Maze) -> str: ...
-
-
-class AStar(MazeSolver):
-
-    def __init__(self, start: tuple[int, int], end: tuple[int, int]) -> None:
-        super().__init__(start, end)
-
-    def f(self, n):
-        def g(n: tuple[int, int]) -> int:
-            res = 0
-            if n[0] < self.start[0]:
-                res += self.start[0] - n[0]
-            else:
-                res += n[0] - self.start[0]
-            if n[1] < self.start[1]:
-                res += self.start[1] - n[1]
-            else:
-                res += n[1] - self.start[1]
-            return res
-
-        def h(n: tuple[int, int]) -> int:
-            res = 0
-            if n[0] < self.end[0]:
-                res += self.end[0] - n[0]
-            else:
-                res += n[0] - self.end[0]
-            if n[1] < self.end[1]:
-                res += self.end[1] - n[1]
-            else:
-                res += n[1] - self.end[1]
-            return res
-
-        try:
-            return g(n) + h(n)
-        except Exception:
-            return 1000
-
-    def best_path(
-        self, maze: np.ndarray, actual: tuple[int, int]
-    ) -> dict[str, int | None]:
-        print(actual)
-        path = {
-            "N": (
-                self.f((actual[1] - 1, actual[0]))
-                if not maze[actual[1]][actual[0]].get_north() and actual[0] > 0
-                else None
-            ),
-            "E": (
-                self.f((actual[1], actual[0] + 1))
-                if not maze[actual[1]][actual[0]].get_est()
-                and actual[1] < len(maze) - 1
-                else None
-            ),
-            "S": (
-                self.f((actual[1] + 1, actual[0]))
-                if not maze[actual[1]][actual[0]].get_south()
-                and actual[0] < len(maze) - 1
-                else None
-            ),
-            "W": (
-                self.f((actual[1], actual[0] - 1))
-                if not maze[actual[1]][actual[0]].get_west() and actual[1] > 0
-                else None
-            ),
-        }
-        return {
-            k: v for k, v in sorted(path.items(), key=lambda item: item[0])
-        }
-
-    def get_opposit(self, dir: str) -> str:
-        match dir:
-            case "N":
-                return "S"
-            case "E":
-                return "W"
-            case "S":
-                return "N"
-            case "W":
-                return "E"
-            case _:
-                return ""
-
-    def get_next_pos(
-        self, dir: str, actual: tuple[int, int]
-    ) -> tuple[int, int]:
-        match dir:
-            case "N":
-                return (actual[0], actual[1] - 1)
-            case "E":
-                return (actual[0] + 1, actual[1])
-            case "S":
-                return (actual[0], actual[1] + 1)
-            case "W":
-                return (actual[0] - 1, actual[1])
-            case _:
-                return actual
-
-    def get_path(self, maze: np.ndarray) -> str | None:
-        actual = self.start
-        path = ""
-
-        return None
-
-    def solve(self, maze: Maze) -> str:
-        print(maze)
-        res = self.get_path(self.start, maze.get_maze(), None)
-        if res is None:
-            raise Exception("Path not found")
-        return res

src/amaz_lib/__init__.py

@@ -1,10 +0,0 @@
-from .Cell import Cell
-from .Maze import Maze
-from .MazeGenerator import MazeGenerator, DepthFirstSearch
-from .MazeGenerator import Kruskal
-from .MazeSolver import MazeSolver, AStar
-
-__version__ = "1.0.0"
-__author__ = "us"
-__all__ = ["Cell", "Maze", "MazeGenerator",
-           "MazeSolver", "AStar", "Kruskal", "DepthFirstSearch"]

src/mazegen/Cell.py

@@ -0,0 +1,124 @@
+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/mazegen/Maze.py

@@ -0,0 +1,76 @@
+from dataclasses import dataclass
+from numpy.typing import NDArray
+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 = ""
+        for line in self.maze:
+            for cell in line:
+                res += cell.__str__()
+            res += "\n"
+        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
+        for cell in self.maze[0]:
+            print("_", end="")
+            if cell.get_north():
+                print("__", end="")
+            else:
+                print("  ", end="")
+        print("_")
+        for line in self.maze:
+            for cell in line:
+                if cell is line[0] and cell.get_west():
+                    print("|", end="")
+                if cell.get_south() is True:
+                    print("__", end="")
+                else:
+                    print("  ", end="")
+                if cell.get_est() is True:
+                    print("|", end="")
+                else:
+                    print("_", end="")
+            print()

src/mazegen/MazeGenerator.py

@@ -0,0 +1,591 @@
+from abc import ABC, abstractmethod
+from typing import Generator, Any
+import numpy as np
+from numpy.typing import NDArray
+from mazegen.Cell import Cell
+import math
+import random
+
+
+class MazeGenerator(ABC):
+    """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
+
+    @abstractmethod
+    def generator(
+        self, height: int, width: int, seed: int | None = None
+    ) -> 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))
+        forty_two.add((y, x - 2))
+        forty_two.add((y, x - 3))
+        forty_two.add((y - 1, x - 3))
+        forty_two.add((y - 2, x - 3))
+        forty_two.add((y + 1, x - 1))
+        forty_two.add((y + 2, x - 1))
+        forty_two.add((y, x + 1))
+        forty_two.add((y, x + 2))
+        forty_two.add((y, x + 3))
+        forty_two.add((y - 1, x + 3))
+        forty_two.add((y - 2, x + 3))
+        forty_two.add((y - 2, x + 2))
+        forty_two.add((y - 2, x + 1))
+        forty_two.add((y + 1, x + 1))
+        forty_two.add((y + 2, x + 1))
+        forty_two.add((y + 2, x + 2))
+        forty_two.add((y + 2, x + 3))
+        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]]:
+        """Add extra openings to transform a perfect maze into an imperfect
+        one.
+
+        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
+            for y in range(height):
+                for x in range(width):
+                    if forty_two and (x, y) in forty_two:
+                        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
+                        ):
+                            continue
+                        if not (0 <= nx < width and 0 < ny < height):
+                            continue
+                        if direc in ["S", "E"]:
+                            continue
+                        if np.random.random() < prob:
+                            count += 1
+                            cell = maze[y][x]
+                            cell_n = maze[ny][nx]
+                            cell = DepthFirstSearch.broken_wall(cell, direc)
+                            cell_n = DepthFirstSearch.broken_wall(
+                                cell_n,
+                                reverse[direc],
+                            )
+                            maze[y][x] = cell
+                            maze[ny][nx] = cell_n
+                            yield maze
+            if count > min_break:
+                break
+        return maze
+
+
+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:
+        """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)]
+        )
+        for wall in walls:
+            x, y = wall
+            match y - x:
+                case 1:
+                    maze[math.trunc((x / width))][x % width].set_est(True)
+                    maze[math.trunc((y / width))][y % width].set_west(True)
+                case width:
+                    maze[math.trunc((x / width))][x % width].set_south(True)
+                    maze[math.trunc((y / width))][y % width].set_north(True)
+        for x in range(height):
+            for y in range(width):
+                if x == 0:
+                    maze[x][y].set_north(True)
+                if x == height - 1:
+                    maze[x][y].set_south(True)
+                if y == 0:
+                    maze[x][y].set_west(True)
+                if y == width - 1:
+                    maze[x][y].set_est(True)
+        return maze
+
+    @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:
+                return True
+            elif a in set.cells or b in set.cells:
+                return False
+        return False
+
+    @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)):
+            if base_set is None and (
+                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
+            ):
+                base_set.cells += sets.sets[i].cells
+                sets.sets.pop(i)
+                return
+        raise Exception("two sets not found")
+
+    @staticmethod
+    def touch_ft(
+        width: int,
+        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)
+        s2 = (math.trunc(wall[1] / width), wall[1] % width)
+        return s1 in cells_ft or s2 in cells_ft
+
+    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)
+        if cells_ft and (self.start in cells_ft or self.end in cells_ft):
+            cells_ft = None
+
+        if seed is not None:
+            np.random.seed(seed)
+        sets = self.Sets([self.KruskalSet([i]) for i in range(height * width)])
+        walls = []
+        for h in range(height):
+            for w in range(width - 1):
+                walls += [(w + (width * h), w + (width * h) + 1)]
+        for h in range(height - 1):
+            for w in range(width):
+                walls += [(w + (width * h), w + (width * (h + 1)))]
+        np.random.shuffle(walls)
+
+        yield self.walls_to_maze(walls, height, width)
+        while (len(sets.sets) != 1 and cells_ft is None) or (
+            len(sets.sets) != 19 and cells_ft is not None
+        ):
+            for wall in walls:
+                if not self.is_in_same_set(sets, wall) and not self.touch_ft(
+                    width, wall, cells_ft
+                ):
+                    self.merge_sets(sets, wall)
+                    walls.remove(wall)
+                    yield self.walls_to_maze(walls, height, width)
+                if (len(sets.sets) == 1 and cells_ft is None) or (
+                    len(sets.sets) == 19 and cells_ft is not None
+                ):
+                    break
+        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)
+            for res in gen:
+                maze = res
+                yield maze
+        return maze
+
+
+class DepthFirstSearch(MazeGenerator):
+    """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
+        self.forty_two: set[tuple[int, int]] | None = None
+
+    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)
+        if width > 9 and height > 9:
+            self.forty_two = self.get_cell_ft(width, height)
+        visited: NDArray[np.object_] = np.zeros((height, width), dtype=bool)
+        if (
+            self.forty_two
+            and self.start not in self.forty_two
+            and self.end not in self.forty_two
+        ):
+            visited = self.lock_cell_ft(visited, self.forty_two)
+        path: list[tuple[int, int]] = list()
+        w_h = (width, height)
+        coord = (0, 0)
+        x, y = coord
+        first_iteration = True
+
+        while path or first_iteration:
+            first_iteration = False
+
+            visited[y, x] = True
+            path = self.add_cell_visited(coord, path)
+
+            random_c = self.random_cells(visited, coord, w_h)
+
+            if not random_c:
+                path = self.back_on_step(path, w_h, visited)
+                if not path:
+                    break
+                coord = path[-1]
+                random_c = self.random_cells(visited, coord, w_h)
+                x, y = coord
+
+            wall = self.next_step(random_c)
+            maze[y][x] = self.broken_wall(maze[y][x], wall)
+
+            coord = self.next_cell(x, y, wall)
+            wall_r = self.reverse_path(wall)
+            x, y = coord
+            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,
+            )
+            for res in gen:
+                maze = res
+                yield maze
+        return maze
+
+    @staticmethod
+    def init_maze(width: int, height: int) -> NDArray[Any]:
+        """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]]:
+        """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]:
+        """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
+
+        if y - 1 >= 0 and not visited[y - 1][x]:
+            rand_cell.append("N")
+
+        if y + 1 < height and not visited[y + 1][x]:
+            rand_cell.append("S")
+
+        if x - 1 >= 0 and not visited[y][x - 1]:
+            rand_cell.append("W")
+
+        if x + 1 < width and not visited[y][x + 1]:
+            rand_cell.append("E")
+        return rand_cell
+
+    @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":
+            cell.set_south(False)
+        elif wall == "W":
+            cell.set_west(False)
+        elif wall == "E":
+            cell.set_est(False)
+        return cell
+
+    @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]]:
+        """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):
+                break
+            path.pop()
+        return path
+
+    @staticmethod
+    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
+        return visited

src/mazegen/MazeSolver.py

@@ -0,0 +1,427 @@
+from abc import ABC, abstractmethod
+from .Maze import Maze
+from typing import Any
+import numpy as np
+from numpy.typing import NDArray
+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:
+        """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],
+            g: int,
+            h: int,
+            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
+            self.f = f
+            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])
+            + max(n[1], self.end[1])
+            - min(n[1], self.end[1])
+        )
+
+    def get_paths(
+        self,
+        maze: NDArray[Any],
+        actual: tuple[int, int],
+        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)
+                if not maze[actual[1]][actual[0]].get_north()
+                and actual[1] > 0
+                and (actual[0], actual[1] - 1)
+                not in [n.coordinate for n in close]
+                else None
+            ),
+            (
+                (actual[0] + 1, actual[1])
+                if not maze[actual[1]][actual[0]].get_est()
+                and actual[0] < len(maze[0]) - 1
+                and (actual[0] + 1, actual[1])
+                not in [n.coordinate for n in close]
+                else None
+            ),
+            (
+                (actual[0], actual[1] + 1)
+                if not maze[actual[1]][actual[0]].get_south()
+                and actual[1] < len(maze) - 1
+                and (actual[0], actual[1] + 1)
+                not in [n.coordinate for n in close]
+                else None
+            ),
+            (
+                (actual[0] - 1, actual[1])
+                if not maze[actual[1]][actual[0]].get_west()
+                and actual[0] > 0
+                and (actual[0] - 1, actual[1])
+                not in [n.coordinate for n in close]
+                else None
+            ),
+        ]
+        return [p for p in path if p is not None]
+
+    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] = []
+
+        open.append(
+            AStar.Node(
+                self.start,
+                0,
+                self.h(self.start),
+                self.h(self.start),
+                None,
+            )
+        )
+
+        while len(open) > 0:
+            to_check = sorted(open, key=lambda x: x.f)[0]
+            open.remove(to_check)
+            close.append(to_check)
+            if to_check.coordinate == self.end:
+                return close
+            paths = self.get_paths(maze, to_check.coordinate, close)
+            for path in paths:
+                open.append(
+                    self.Node(
+                        path,
+                        to_check.g + 1,
+                        self.h(path),
+                        self.h(path) + to_check.g + 1,
+                        to_check,
+                    )
+                )
+        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,
+        ):
+            return "S"
+        elif current.parent.coordinate == (
+            current.coordinate[0] + 1,
+            current.coordinate[1],
+        ):
+            return "W"
+        elif current.parent.coordinate == (
+            current.coordinate[0],
+            current.coordinate[1] + 1,
+        ):
+            return "N"
+        elif current.parent.coordinate == (
+            current.coordinate[0] - 1,
+            current.coordinate[1],
+        ):
+            return "E"
+        else:
+            raise Exception("Translate error: AStar path not found")
+
+    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:
+            res = self.get_rev_dir(current) + res
+            current = current.parent
+            if current.coordinate == self.start:
+                break
+        return res
+
+    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")
+        path: list[AStar.Node] = self.get_path(maze_arr)
+        return self.translate(path)
+
+
+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")
+        visited: NDArray[Any] = np.zeros((height, width), dtype=bool)
+        path: list[tuple[int, int]] = list()
+        move: list[str] = list()
+        maze_s = maze.get_maze()
+        if maze_s is None:
+            raise Exception("Maze is not initializef")
+        coord = self.start
+        h_w: tuple[int, int] = (height, width)
+        while coord != self.end:
+            visited[coord] = True
+            path.append(coord)
+            rand_p: list[str] = self.random_path(visited, coord, maze_s, h_w)
+
+            if not rand_p:
+                path, move = self.back_on_step(
+                    path, visited, maze_s, h_w, move
+                )
+                if not path:
+                    break
+                coord = path[-1]
+                rand_p = self.random_path(visited, coord, maze_s, h_w)
+            next = self.next_path(rand_p)
+            move.append(next)
+            coord = self.next_cell(coord, next)
+        for m in move:
+            path_str += m
+        if not path:
+            raise Exception("Path not found")
+        return path_str
+
+    @staticmethod
+    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
+
+        if y - 1 >= 0 and not maze[y][x].get_north() and not visited[y - 1][x]:
+            random_p.append("N")
+
+        if y + 1 < h and not maze[y][x].get_south() and not visited[y + 1][x]:
+            random_p.append("S")
+
+        if x - 1 >= 0 and not maze[y][x].get_west() and not visited[y][x - 1]:
+            random_p.append("W")
+
+        if x + 1 < w and not maze[y][x].get_est() and not visited[y][x + 1]:
+            random_p.append("E")
+        return random_p
+
+    @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
+    def back_on_step(
+        path: list[tuple[int, int]],
+        visited: NDArray[Any],
+        maze: NDArray[Any],
+        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):
+                break
+            path.pop()
+            move.pop()
+        return path, move
+
+    @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]
+        return (y + add_y, x + add_x)

src/mazegen/__init__.py

@@ -0,0 +1,18 @@
+from mazegen.Cell import Cell
+from mazegen.Maze import Maze
+from mazegen.MazeGenerator import MazeGenerator, DepthFirstSearch
+from mazegen.MazeGenerator import Kruskal
+from mazegen.MazeSolver import MazeSolver, AStar, DepthFirstSearchSolver
+
+__version__ = "1.0.0"
+__author__ = "us"
+__all__ = [
+    "Cell",
+    "Maze",
+    "MazeGenerator",
+    "DepthFirstSearchSolver",
+    "MazeSolver",
+    "AStar",
+    "Kruskal",
+    "DepthFirstSearch",
+]

src/parsing/Parsing.py

@@ -1,7 +1,24 @@
+from mazegen import DepthFirstSearch, Kruskal
+from mazegen import AStar, DepthFirstSearchSolver
+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 == "":
@@ -9,37 +26,66 @@ class DataMaze:
         return data
 
     @staticmethod
-    def transform_data(data: str) -> dict:
+    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
-        ]
-        data_t = {
-            value[0]: value[1] for value in tmp2
-        }
+        tmp2 = [value.split("=", 1) for value in tmp if "=" in value]
+        data_t = {value[0]: value[1] for value in tmp2}
         return data_t
 
     @staticmethod
-    def verif_key_data(data: dict) -> None:
+    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", "ENTRY", "EXIT", "OUTPUT_FILE", "PERFECT"
-        }
-        set_key = {
-            key for key in data.keys()
+            "WIDTH",
+            "HEIGHT",
+            "ENTRY",
+            "EXIT",
+            "OUTPUT_FILE",
+            "PERFECT",
+            "GENERATOR",
+            "SOLVER",
         }
+        set_key = {key for key in data.keys()}
         if len(set_key) != len(key_test):
             raise KeyError("Missing some data the len do not correspond")
         res_key = {key for key in set_key if key not in key_test}
         if len(res_key) != 0:
-            raise KeyError("Some Key "
-                           f"do not correspond the keys: {res_key}")
+            raise KeyError(
+                "Some Key " f"do not correspond the keys: {res_key}"
+            )
 
     @staticmethod
-    def convert_values(data: dict):
+    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"}
-        res: dict = {}
+        res: dict[str, Any] = {}
         for key in key_int:
             res.update({key: int(data[key])})
         for key in key_tuple:
@@ -47,16 +93,110 @@ class DataMaze:
         for key in key_bool:
             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"],
+            )
+        )
         return res
 
     @staticmethod
-    def get_data_maze(name_file: str) -> dict:
+    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,
+        }
+        res = {}
+        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(
+                "There is too much " "argument in the coordinate given"
+            )
+        x, y = data_t
+        tup = (int(x), int(y))
+        return tup
+
+    @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":
+            return True
+        return False
+
+    @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)
             DataMaze.verif_key_data(data_dict)
             data_maze = DataMaze.convert_values(data_dict)
-            return data_maze
+            return {k.lower(): v for k, v in data_maze.items()}
         except FileNotFoundError:
             print("The file do not exist")
             exit()
@@ -70,28 +210,11 @@ class DataMaze:
             print(f"Error on the key in the file: {e}")
             exit()
         except IndexError as e:
-            print("In the function transform Data some data cannot "
-                  f"be splited by '=' because '=' was not present: {e}")
+            print(
+                "In the function transform Data some data cannot "
+                f"be splited by '=' because '=' was not present: {e}"
+            )
             exit()
         except AttributeError as e:
-            print("Error on the "
-                  f"funciton get_data_maze : {e}")
+            print("Error on the " f"funciton get_data_maze : {e}")
             exit()
-
-    @staticmethod
-    def convert_tuple(data: str) -> tuple:
-        data_t = data.split(",")
-        if len(data_t) != 2:
-            raise ValueError("There is too much "
-                             "argument in the coordinate given")
-        x, y = data_t
-        tup = (int(x), int(y))
-        return tup
-
-    @staticmethod
-    def convert_bool(data: str) -> bool:
-        if data != "True" and data != "False":
-            raise ValueError("This is not True or False")
-        if data == "True":
-            return True
-        return False

src/parsing/__init__.py

@@ -1,6 +0,0 @@
-__version__ = "1.0.0"
-__author__ = "mteriier, dgaillet"
-
-from .Parsing import DataMaze
-
-__all__ = ["DataMaze"]

test.txt

@@ -1,23 +0,0 @@
-7D53BFD3D57951517D1D
-3D12C3903BD03AD4178D
-2BAEBEEEAA92EED547C9
-2287ED17AAAC5393FFF0
-6C6951292A87D2AEBD30
-37D43E8686E93AABAB8C
-21516D2D47FEE8284049
-6C7857C3FB9116C696D8
-751453D6D2AAC57BE970
-3BA952D17EA83BD05470
-22AAD2907BAE86967B74
-2AA83C2EFC69696FBC35
-686EE96FD7D4783FAD21
-7ED17ED3D57D3EC52FA0
-7B943D16FB7BABD3AFC8
-7407C5297EB82EB84174
-392D53C6912EE9447E9D
-62A952BBAAC13EFD7B89
-3AAC3EC6EABAAD557824
-66C7C7D7D6C6C7D556CD
-
-1,1
-16,15

tests/test_Cell.py

@@ -1,5 +1,4 @@
-import pytest
-from amaz_lib.Cell import Cell
+from mazegen import Cell
 
 
 def test_cell_setter_getter() -> None:

tests/test_Depth.py

@@ -1,5 +1,5 @@
-from amaz_lib.MazeGenerator import DepthFirstSearch
-from amaz_lib.Cell import Cell
+from mazegen import DepthFirstSearch
+from mazegen import Cell
 import numpy as np
 
 

tests/test_Maze.py

@@ -1,6 +1,6 @@
 import numpy
-from amaz_lib.Cell import Cell
-from amaz_lib.Maze import Maze
+from mazegen import Cell
+from mazegen import Maze
 
 
 def test_maze_setter_getter() -> None:
@@ -15,7 +15,9 @@ def test_maze_setter_getter() -> None:
     )
 
     maze.set_maze(test)
-    assert numpy.array_equal(maze.get_maze(), test) is True
+    m = maze.get_maze()
+    assert m is not None
+    assert numpy.array_equal(m, test) is True
 
 
 def test_maze_str() -> None:

tests/test_MazeGenerator.py

@@ -1,13 +1,13 @@
 import numpy
-from amaz_lib.MazeGenerator import DepthFirstSearch
+from mazegen import DepthFirstSearch
 
 
 class TestMazeGenerator:
 
     def test_generator(self) -> None:
-        w_h = (300, 300)
+        w_h = (10, 10)
         maze = numpy.array([])
-        generator = DepthFirstSearch().generator(*w_h)
+        generator = DepthFirstSearch((1, 1), (2, 2), True).generator(*w_h)
         for output in generator:
             maze = output
 

tests/test_MazeSolver.py

@@ -1,6 +1,6 @@
-from amaz_lib.Cell import Cell
+from mazegen import Cell
 import numpy as np
-from amaz_lib import AStar, Maze, MazeSolver
+from mazegen import AStar, Maze
 
 
 def test_solver() -> None:

tests/test_parsing.py

@@ -4,71 +4,71 @@ import pytest
 
 class TestParsing:
 
-    def test_get_data_valid(self):
+    def test_get_data_valid(self) -> None:
         data = DataMaze.get_file_data("tests/test_txt/config_1.txt")
         assert isinstance(data, str) is True
 
-    def test_file_error(self):
+    def test_file_error(self) -> None:
         with pytest.raises(FileNotFoundError):
             DataMaze.get_file_data("tete")
 
-    # def test_permission_error(self):
+    # def test_permission_error(self) -> None:
     #     with pytest.raises(PermissionError):
     #         DataMaze.get_file_data("tests/test_txt/error_1.txt")
 
-    def test_empty_file_error(self):
+    def test_empty_file_error(self) -> None:
         with pytest.raises(ValueError):
             DataMaze.get_file_data("tests/test_txt/error_6.txt")
 
-    def test_transform_data_valid(self):
+    def test_transform_data_valid(self) -> None:
         data = DataMaze.get_file_data("tests/test_txt/config_1.txt")
         data_2 = DataMaze.transform_data(data)
         assert isinstance(data_2, dict)
 
-    def test_transform__index_error(self):
+    def test_transform__index_error(self) -> None:
         with pytest.raises(IndexError):
             DataMaze.transform_data("asdasdasdasdasdasda\nasdasdas=asdasd")
 
-    def test_key_data_error(self):
+    def test_key_data_error(self) -> None:
         with pytest.raises(KeyError):
             data = DataMaze.get_file_data("tests/test_txt/error_8.txt")
             data2 = DataMaze.transform_data(data)
             DataMaze.verif_key_data(data2)
 
-    def test_key_data_error_2(self):
+    def test_key_data_error_2(self) -> None:
         with pytest.raises(KeyError):
             data = DataMaze.get_file_data("tests/test_txt/error_9.txt")
             data2 = DataMaze.transform_data(data)
             DataMaze.verif_key_data(data2)
 
-    def test_convert_int(self):
+    def test_convert_int(self) -> None:
         with pytest.raises(ValueError):
             data = DataMaze.get_file_data("tests/test_txt/error_2.txt")
             data2 = DataMaze.transform_data(data)
             DataMaze.convert_values(data2)
 
-    def test_tuple_error(self):
+    def test_tuple_error(self) -> None:
         with pytest.raises(ValueError):
             DataMaze.convert_tuple("0,3,5,5")
 
-    def test_tuple_error1(self):
+    def test_tuple_error1(self) -> None:
         with pytest.raises(AttributeError):
-            DataMaze.convert_tuple(None)
+            DataMaze.convert_tuple("None")
 
-    def test_bool_error(self):
+    def test_bool_error(self) -> None:
         with pytest.raises(ValueError):
             DataMaze.convert_bool("Trueeee")
 
-    def test_valid_tuple(self):
+    def test_valid_tuple(self) -> None:
         assert DataMaze.convert_tuple("7534564654, 78") == (7534564654, 78)
 
-    def test_valid_bool(self):
+    def test_valid_bool(self) -> None:
         assert DataMaze.convert_bool("False") is False
 
-    def test_valid_bool1(self):
+    def test_valid_bool1(self) -> None:
         assert DataMaze.convert_bool("True") is True
 
-    def test_data_maze(self):
+    def test_data_maze(self) -> None:
         data = DataMaze.get_data_maze("tests/test_txt/config_1.txt")
         assert data["WIDTH"] == 200
         assert data["HEIGHT"] == 100

uv.lock

@@ -6,36 +6,6 @@ resolution-markers = [
     "python_full_version < '3.11'",
 ]
 
-[[package]]
-name = "a-maze-ing"
-version = "0.1.0"
-source = { virtual = "." }
-dependencies = [
-    { name = "numpy", version = "2.2.6", source = { registry = "https://pypi.org/simple" }, marker = "python_full_version < '3.11'" },
-    { name = "numpy", version = "2.4.3", source = { registry = "https://pypi.org/simple" }, marker = "python_full_version >= '3.11'" },
-    { name = "pydantic" },
-]
-
-[package.dev-dependencies]
-dev = [
-    { name = "flake8" },
-    { name = "mypy" },
-    { name = "pytest" },
-]
-
-[package.metadata]
-requires-dist = [
-    { name = "numpy", specifier = ">=2.2.6" },
-    { name = "pydantic", specifier = ">=2.12.5" },
-]
-
-[package.metadata.requires-dev]
-dev = [
-    { name = "flake8", specifier = ">=7.3.0" },
-    { name = "mypy", specifier = ">=1.19.1" },
-    { name = "pytest", specifier = ">=9.0.2" },
-]
-
 [[package]]
 name = "annotated-types"
 version = "0.7.0"
@@ -174,6 +144,36 @@ wheels = [
     { url = "https://files.pythonhosted.org/packages/b2/c8/d148e041732d631fc76036f8b30fae4e77b027a1e95b7a84bb522481a940/librt-0.8.1-cp314-cp314t-win_arm64.whl", hash = "sha256:bf512a71a23504ed08103a13c941f763db13fb11177beb3d9244c98c29fb4a61", size = 48755, upload-time = "2026-02-17T16:12:47.943Z" },
 ]
 
+[[package]]
+name = "mazegen"
+version = "0.1.0"
+source = { editable = "." }
+dependencies = [
+    { name = "numpy", version = "2.2.6", source = { registry = "https://pypi.org/simple" }, marker = "python_full_version < '3.11'" },
+    { name = "numpy", version = "2.4.3", source = { registry = "https://pypi.org/simple" }, marker = "python_full_version >= '3.11'" },
+    { name = "pydantic" },
+]
+
+[package.dev-dependencies]
+dev = [
+    { name = "flake8" },
+    { name = "mypy" },
+    { name = "pytest" },
+]
+
+[package.metadata]
+requires-dist = [
+    { name = "numpy", specifier = ">=2.2.6" },
+    { name = "pydantic", specifier = ">=2.12.5" },
+]
+
+[package.metadata.requires-dev]
+dev = [
+    { name = "flake8", specifier = ">=7.3.0" },
+    { name = "mypy", specifier = ">=1.19.1" },
+    { name = "pytest", specifier = ">=9.0.2" },
+]
+
 [[package]]
 name = "mccabe"
 version = "0.7.0"