README

Makefile

@@ -16,20 +16,24 @@ debug:
 	uv pdb python3 a_maze_ing.py config.txt
 
 clean:
-	rm -rf */**/__pycache__ __pycache__ .mypy_cache .venv dist build */**/*.egg-info *.egg-info test.txt
+	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 env PYTHONPATH=src python3 -m mypy --warn-return-any --warn-unused-ignores --ignore-missing-imports --disallow-untyped-defs --check-untyped-defs src
+	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 . --exclude=.venv
-	uv run env PYTHONPATH=src python3 -m mypy --strict src
+	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
 

README.md

@@ -1,3 +1,615 @@
-The Randomized Kruskal's Algorithm
+This project has been created as part of the 42 curriculum by *mteriier*, *dgaillet*
 
-The Randomized Prim's Algorithm
+# A-Maze-ing
+
+## Description
+
+A-Maze-ing is a Python project that generates, solves, exports, and displays mazes.
+
+The program:
+
+- reads a configuration file,
+- generates a maze according to the requested parameters,
+- optionally enforces a **perfect maze** property,
+- solves the maze from entry to exit,
+- writes the maze to an output file using the required hexadecimal wall encoding,
+- and displays the maze visually through an **MLX graphical window**.
+
+This project was designed with **code reusability** in mind.  
+The maze generation and solving logic is exposed through a reusable Python package named **`mazegen`**, which can be built and installed independently for use in future projects.
+
+---
+
+## Features
+
+- Maze generation from a config file
+- Multiple generation algorithms:
+  - `DFS` (depth-first search / recursive backtracking style)
+  - `Kruskal`
+- Multiple solving algorithms:
+  - `AStar`
+  - `DFS`
+- Perfect and imperfect maze support
+- Maze export using hexadecimal wall encoding
+- Graphical rendering with MLX
+- Animated generation
+- Animated solution path display
+- Wall color switching
+- Reserved visual **“42” pattern** using fully closed cells when the maze is large enough
+- Reusable `mazegen` package
+
+---
+
+## Project Structure
+
+```text
+.
+├── a_maze_ing.py          # Main executable script and MLX display
+├── config.txt             # Default configuration file
+├── Makefile
+├── README.md
+├── src/
+│   ├── AMazeIng.py
+│   ├── mazegen/
+│   │   ├── __init__.py
+│   │   ├── Cell.py
+│   │   ├── Maze.py
+│   │   ├── MazeGenerator.py
+│   │   └── MazeSolver.py
+│   └── parsing/
+│       └── Parsing.py
+└── tests/
+```
+
+---
+
+## Instructions
+
+### Requirements
+
+- Python **3.10+**
+- `uv`, `pip`
+- MLX Python binding used by the project
+
+### Installation
+
+Using the provided `Makefile`:
+
+```bash
+make install
+```
+
+This installs project dependencies and the MLX wheel used by the graphical display.
+
+---
+
+## Run
+
+```bash
+make run
+```
+
+---
+
+## Debug
+
+```bash
+make debug
+```
+
+---
+
+## Lint
+
+Mandatory lint target:
+
+```bash
+make lint
+```
+
+Strict lint target:
+
+```bash
+make lint-strict
+```
+
+---
+
+## Clean
+
+```bash
+make clean
+```
+
+Full cleanup:
+
+```bash
+make fclean
+```
+
+---
+
+## Configuration File Format
+
+The configuration file contains one `KEY=VALUE` pair per line.
+
+### Mandatory keys
+
+| Key | Description | Example |
+|---|---|---|
+| `WIDTH` | Maze width in cells | `WIDTH=20` |
+| `HEIGHT` | Maze height in cells | `HEIGHT=15` |
+| `ENTRY` | Entry coordinates `(x,y)` | `ENTRY=1,1` |
+| `EXIT` | Exit coordinates `(x,y)` | `EXIT=20,15` |
+| `OUTPUT_FILE` | Output filename | `OUTPUT_FILE=maze.txt` |
+| `PERFECT` | Perfect maze or not | `PERFECT=True` |
+| `GENERATOR` | Generation algorithm | `GENERATOR=DFS` |
+| `SOLVER` | Solving algorithm | `SOLVER=AStar` |
+
+### Supported values
+
+#### GENERATOR
+
+- `DFS`
+- `Kruskal`
+
+#### SOLVER
+
+- `AStar`
+- `DFS`
+
+#### PERFECT
+
+- `True`
+- `False`
+
+### Example config
+
+```ini
+WIDTH=20
+HEIGHT=15
+ENTRY=1,1
+EXIT=20,15
+OUTPUT_FILE=maze.txt
+PERFECT=True
+GENERATOR=DFS
+SOLVER=AStar
+SEED=31766516
+```
+
+### Notes
+
+- Coordinates are handled as tuples in the form `x,y`.
+- In the current implementation, coordinates are expected to be **inside maze bounds**.
+- Entry and exit must be valid cells.
+- The parser validates required keys and converts values to the correct Python types.
+- You can add a `SEED` value
+
+---
+
+## Output File Format
+
+The generated maze is written row by row using **one hexadecimal digit per cell**.
+
+Each cell stores wall information using this bitmask:
+
+| Bit | Direction |
+|---|---|
+| `1` | North |
+| `2` | East |
+| `4` | South |
+| `8` | West |
+
+A bit set to `1` means the wall is **closed**.
+
+### Example
+
+- `3` = `0011` → north and east closed
+- `A` = `1010` → east and west closed
+
+### Output layout
+
+```text
+<maze row 1>
+<maze row 2>
+...
+<maze row n>
+
+<entry coordinates>
+<exit coordinates>
+<solution path>
+```
+
+Example:
+
+```text
+FFFF
+9A63
+8C47
+FFFF
+
+1,1
+4,4
+EESSEN
+```
+
+---
+
+## Visual Representation
+
+This project provides a graphical rendering through **MLX**.
+
+The display shows:
+
+- maze walls,
+- entry cell,
+- exit cell,
+- optional shortest path,
+- reserved “42” pattern when present.
+
+### Controls
+
+In the MLX window:
+
+- `1` / mapped equivalent: regenerate maze
+- `2` / mapped equivalent: show/hide path
+- `3` / mapped equivalent: change wall color
+- `4` / mapped equivalent: quit
+
+The code includes two key mappings to handle platform/layout differences.
+
+### Visual Features
+
+- animated generation,
+- animated path display,
+- color cycling for walls,
+- separate color cycling for the “42” cells.
+
+---
+
+## Maze Generation Algorithm
+
+This project supports two generation algorithms.
+
+### 1. Depth-First Search (DFS)
+
+This algorithm starts from a cell and repeatedly visits an unvisited neighbour, removing walls as it advances. When it reaches a dead end, it backtracks until it finds a cell with an unvisited neighbour.
+
+#### Why this algorithm was chosen
+
+- simple to implement,
+- naturally produces connected mazes,
+- works well for animation,
+- produces visually interesting long corridors,
+- easy to adapt for perfect mazes.
+
+### 2. Kruskal
+
+This algorithm treats each cell as its own set and removes walls between cells only when it connects two different sets. This avoids cycles and guarantees connectivity.
+
+#### Why this algorithm was included
+
+- classic maze generation algorithm,
+- good complement to DFS,
+- demonstrates modularity and algorithm interchangeability,
+- naturally fits the reusable package requirement.
+
+---
+
+## Why These Algorithms Were Chosen
+
+We chose DFS and Kruskal because together they provide:
+
+- two well-known and complementary approaches,
+- good pedagogical value,
+- simple integration into a reusable class-based architecture,
+- deterministic structure when used with a seed,
+- compatibility with perfect maze generation.
+
+DFS is particularly suitable for progressive visual rendering.  
+Kruskal is useful to show a different construction logic based on set merging.
+
+---
+
+## Perfect and Imperfect Mazes
+
+When `PERFECT=True`:
+
+- the maze is generated as a **perfect maze**,
+- there is exactly one path between any two reachable cells,
+- in particular, entry and exit have a unique valid path.
+
+When `PERFECT=False`:
+
+- additional walls may be removed after initial generation,
+- loops can appear,
+- the maze remains connected,
+- the solver still computes a valid path.
+
+---
+
+## The “42” Pattern
+
+For sufficiently large mazes, the generator reserves a group of fully closed cells to draw a visible **“42”** pattern in the visual rendering.
+
+### Behaviour
+
+- the pattern is added only if the maze is large enough,
+- if the maze is too small, the pattern may be omitted,
+- this should be reported to the user with a console message.
+
+### Current implementation note
+
+The current code includes support for reserving and rendering the “42” pattern using cells with value `15` (all walls closed).  
+The pattern is drawn in the central area when dimensions are large enough.
+
+---
+
+## Error Handling
+
+The project is designed to fail gracefully and provide clear messages for common problems such as:
+
+- missing configuration file,
+- empty file,
+- missing or invalid keys,
+- invalid boolean values,
+- invalid coordinates,
+- invalid maze dimensions,
+- solving an uninitialized maze.
+
+The parser catches several common exceptions and prints user-friendly messages before exiting.
+
+---
+
+## Reusable Code
+
+The reusable part of the project is the **`mazegen`** package.
+
+It contains:
+
+- `Cell`: wall bitmask representation,
+- `Maze`: maze container and textual/ascii rendering,
+- `MazeGenerator`: abstract generator interface,
+- `DepthFirstSearch`: DFS-based maze generator,
+- `Kruskal`: Kruskal-based maze generator,
+- `MazeSolver`: abstract solver interface,
+- `AStar`: shortest-path solver,
+- `DepthFirstSearchSolver`: DFS-based path solver.
+
+This package can be built as a wheel and reused independently of the MLX application.
+
+---
+
+## How to Use the Reusable Module
+
+### Basic example
+
+```python
+from mazegen import Maze
+from mazegen import DepthFirstSearch, AStar
+
+generator = DepthFirstSearch(start=(1, 1), end=(10, 10), perfect=True)
+solver = AStar(start=(1, 1), end=(10, 10))
+
+maze = Maze()
+
+for grid in generator.generator(height=10, width=10, seed=42):
+    maze.set_maze(grid)
+
+path = solver.solve(maze, height=10, width=10)
+
+print(maze)
+print(path)
+```
+
+### With Kruskal
+
+```python
+from mazegen import Maze, Kruskal, AStar
+
+generator = Kruskal(start=(1, 1), end=(20, 15), perfect=True)
+solver = AStar(start=(1, 1), end=(20, 15))
+
+maze = Maze()
+
+for grid in generator.generator(height=15, width=20, seed=123):
+    maze.set_maze(grid)
+
+print(solver.solve(maze, height=15, width=20))
+```
+
+### Accessing the generated structure
+
+```python
+maze_array = maze.get_maze()
+```
+
+Each element of `maze_array` is a `Cell` object exposing:
+
+- `get_north()`
+- `get_est()`
+- `get_south()`
+- `get_west()`
+- `get_value()`
+
+### Accessing a solution
+
+```python
+solution = solver.solve(maze, height=15, width=20)
+print(solution)  # Example: "EESSWN..."
+```
+
+---
+
+## Packaging
+
+The reusable package is distributed as **`mazegen-*`**.
+
+Example expected artifact:
+
+```text
+mazegen-1.0.0-py3-none-any.whl
+```
+
+Build with:
+
+```bash
+make build
+```
+
+This produces a wheel suitable for later installation with `pip`/`uv`.
+
+---
+
+## Tests
+
+Unit tests are recommended and partially integrated through `pytest` targets in the Makefile.
+
+Start test with:
+
+```bash
+make run_test
+```
+
+These tests are useful to validate:
+
+- parsing,
+- generation,
+- solver behavior,
+- edge cases.
+
+---
+
+## Technical Choices
+
+### Language
+
+- Python 3.10+
+
+### Libraries
+
+- `numpy` for grid storage
+- `pydantic` for model validation
+- `mlx` for graphical rendering
+- `pytest` for tests
+- `mypy` for static typing
+- `flake8` for style checking
+
+### Architecture
+
+The project is separated into three main parts:
+
+1. **Main application**
+   - parsing,
+   - orchestration,
+   - MLX rendering,
+   - user interaction.
+
+2. **Domain model**
+   - `AMazeIng`,
+   - maze configuration and lifecycle.
+
+3. **Reusable package**
+   - generation,
+   - solving,
+   - maze structure.
+
+This separation makes the generation logic portable to other projects.
+
+---
+
+## Team and Project Management
+
+### Team roles
+
+- **mteriier**
+  - Parsing
+  - DFS generator / solver
+  - Makefile
+  - some pytest
+  - Fix of mazegen package generation
+  - MLX
+- **dgaillet**
+  - AMazeIng config class
+  - AStar solver
+  - Kruskal generator
+  - some pytest
+  - mazegen package generation
+  - MLX
+  - Cell / Maze class
+
+### Initial planning
+
+Our initial plan was:
+
+1. define the maze data model,
+2. implement one working generation algorithm,
+3. export the maze to the required format,
+4. implement solving,
+5. add graphical rendering,
+6. package reusable code,
+7. write tests and documentation.
+
+### How planning evolved
+
+In practice:
+
+- the reusable package structure had to be stabilized earlier than expected,
+- coordinate handling between parser, generator, solver, and renderer required extra work,
+- rendering and animation took longer than planned,
+- algorithm modularity made later integration easier.
+
+### What worked well
+
+- clean separation between generation and display,
+- abstract base classes for generator and solver,
+- Makefile automation,
+- packaging the reusable module.
+
+### What could be improved
+
+- stricter normalization of coordinate conventions,
+- seed support should be exposed directly from configuration,
+- more tests for edge cases and invalid inputs,
+
+### Tools used
+
+- Git
+- `uv`
+- `flake8`
+- `mypy`
+- `pytest`
+- MLX
+- optionally AI assistance for docstrings, README
+
+---
+
+## Resources
+
+### Documentation and references
+
+- [NumPy Documentation](https://numpy.org/doc/)
+- [Pydantic Documentation](https://docs.pydantic.dev/)
+- [A* Pathfinding explanation](https://matteo-tosato7.medium.com/exploring-the-depths-solving-mazes-with-a-search-algorithm-c15253104899)
+- [Kruskal generation](https://medium.com/@anushidesilva28/understanding-kruskals-algorithm-44886bf8ba8b)
+
+### How AI was used
+
+AI was used as an assistant for:
+
+- improving docstrings,
+- helping structure the README,
+
+---
+
+## Reusable Module Summary
+
+If you only want the reusable maze engine:
+
+1. build/install `mazegen`,
+2. import a generator and a solver,
+3. generate a maze,
+4. solve it,
+5. access the grid through `Maze.get_maze()`.
+
+This part is intended for reuse in future Python projects.

a_maze_ing.py

@@ -1,7 +1,7 @@
 from typing import Any
 from numpy.typing import NDArray
-from src.AMazeIng import AMazeIng
-from src.parsing.Parsing import DataMaze as Parsing
+from AMazeIng import AMazeIng
+from parsing.Parsing import DataMaze as Parsing
 from mlx import Mlx
 import time
 
@@ -474,7 +474,7 @@ class MazeMLX:
         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, amazing
+            self.win_ptr, 2, 1 << 0, self.handle_key_press_mteriier, amazing
         )
         self.mlx.mlx_loop(self.mlx_ptr)
 

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"
@@ -30,5 +30,8 @@ requires = ["setuptools>=78.1.0", "wheel>=0.45.1"]
 build-backend = "setuptools.build_meta"
 
 [tool.setuptools]
-package-dir = {"" = "src/amaz_lib"}
+package-dir = {"" = "src"}
+
+[tool.setuptools.packages.find]
+where = ["src"]
 

src/AMazeIng.py

@@ -2,7 +2,7 @@ from typing import Generator
 from typing_extensions import Self
 from pydantic import BaseModel, Field, model_validator, ConfigDict
 
-from .amaz_lib import Maze, MazeGenerator, MazeSolver
+from mazegen import Maze, MazeGenerator, MazeSolver
 
 
 class AMazeIng(BaseModel):

src/amaz_lib/__init__.py

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

src/mazegen/MazeGenerator.py

@@ -2,7 +2,7 @@ from abc import ABC, abstractmethod
 from typing import Generator, Any
 import numpy as np
 from numpy.typing import NDArray
-from .Cell import Cell
+from mazegen.Cell import Cell
 import math
 import random
 

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,5 +1,5 @@
-from ..amaz_lib import DepthFirstSearch, Kruskal
-from ..amaz_lib import AStar, DepthFirstSearchSolver
+from mazegen import DepthFirstSearch, Kruskal
+from mazegen import AStar, DepthFirstSearchSolver
 from typing import Any
 
 

tests/test_Cell.py

@@ -1,4 +1,4 @@
-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:

tests/test_MazeGenerator.py

@@ -1,5 +1,5 @@
 import numpy
-from amaz_lib.MazeGenerator import DepthFirstSearch
+from mazegen import DepthFirstSearch
 
 
 class TestMazeGenerator:

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
+from mazegen import AStar, Maze
 
 
 def test_solver() -> None:

uv.lock

@@ -6,36 +6,6 @@ resolution-markers = [
     "python_full_version < '3.11'",
 ]
 
-[[package]]
-name = "a-maze-ing"
-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 = "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"