Metadata-Version: 2.4
Name: mazegen-42us
Version: 0.1.0
Summary: Reusable maze generator for A-Maze-ing
License: MIT
License-File: LICENSE.md
Author: abani-am
Requires-Python: >=3.10,<4.0
Classifier: License :: OSI Approved :: MIT License
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3.10
Classifier: Programming Language :: Python :: 3.11
Classifier: Programming Language :: Python :: 3.12
Classifier: Programming Language :: Python :: 3.13
Classifier: Programming Language :: Python :: 3.14
Requires-Dist: pydantic (>=2.0,<3.0)
Description-Content-Type: text/markdown

<strong> *This activity has been created as part of the 42 curriculum by abani-am, ialalawn* </strong>


---

# A-Maze-ing: Python Maze Generator

## Description
This project is a customizable maze generator built in Python. It generates both perfect mazes (a single valid path between entry and exit) and playable "Pac-Man" style boards (multiple loops, no dead-ends, with a central "42" pattern). It outputs the maze in a hexadecimal format and features an interactive visual representation in the terminal.

## Instructions
### Prerequisites
- Python 3.10+
- `make` utility

### Installation and Execution
1. Clone the repository and navigates to the root directory.
2. Install any required dependencies:

    **`make install`**
    
    - Run the maze generator with a configuration file:
    **`make run`**.  
    or manually: `python3 a_maze_ing.py config.txt`

    - To check the code against `flake8` and `mypy` standards:
    **`make lint`**


## Configuration File Format

The program requires a `.txt` configuration file passed as an argument. The file uses a `KEY=VALUE` format. Lines starting with # are ignored.
### Structure:
- `WIDTH`: Maze width (number of cells).
- `HEIGHT`: Maze height.
- `ENTRY`: Entry coordinates (x, y).
- `EXIT`: Exit coordinates (x, y).
- `OUTPUT_FILE`: The name of the text file where hexadecimal output will be saved.
- `PERFECT`: Boolean (`True` or `False`). `True` generates a single-path perfect maze.

**Example (`config.txt`):**

    # Maze Configuration
    WIDTH=20
    HEIGHT=15
    ENTRY=0,0
    EXIT=19,14
    OUTPUT_FILE=maze.txt
    PERFECT=True


## Algorithm Choices
- **Chosen Algorithm:** Depth-First Search (DFS)/Recursive Backtracker.
- **Why:** it naturally creates complex, winding corridors ideal for a perfect maze. It also provides a solid foundation for the `PERFECT=False` (Pac-Man) mode, where we run a secondary pass to break walls and eliminate dead-ends.

## Code Reusability
The core logic is package as a standalone Python module named `mazegen`.
- **How to reuse:** Install `mazegen-1.0.0-py3-none-any.whl` via pip, import `MazeGenerator` ,and call `maze.generate()` to access the 2D grid structure.

## Team and Project Management
- **Team Roles:** We adopted a strict **Pair Programming** approach throughout the development lifecycle. Both ***`abani-am`*** and ***`ialalawn`*** contributed equally to all phases, meaning we co-developed the architecture, logic, and algorithms together rather than working in isolated silos.
- **Anticipated Planning & Evolution:** Our development roadmap was built sequentially to ensure a solid foundation before tackling complex algorithms:
    1. **Setup & Packaging:** We started by initializing the environment, writing the configuration parser for `config.txt`, and configuring the `pyproject.toml` for standard packaging.
    2. **Documentation & Structure:** Drafted the `README.md` and established the project's file hierarchy early to align on end goals.
    3. **Generation Engine (DFS):** Focused on implementing the Depth-First Search algorithm and perfecting the bitwise operations to carve the maze accurately.
    4. **Solving Engine (BFS):** Concluded the project by implementing the Breadth-First Search algorithm to find the absolute shortest path.

- **What Worked Well & What Could Be Improved:** - *Worked Well:* Pair programming was highly effective, especially when debugging the complex bitwise math (`&`, `~`) and ensuring our code strictly adhered to `flake8` and `mypy` standards.

- **Tools Used:** Git/GitHub for version control, Make for task automation, Flake8/Mypy for linting, Whatsapp for team communication and task tracking.

## Resources
### Classic Reference

- Youtube tutorials on Maze Generation algorithms.
- Official Python 3 Documentation (specifically for `collection.deque` and Python Packaging Authority guidelines)

## AI Usage
Generative AI was utilized as a learning assistant and architectural guide throughout the project:

- **Architecture & Planning:** Used AI to map out the optimal path to the solution, determine the necessary file structure, and understand how to decouple the logic into an installable
`.whl` package.

- **Algorithm Selection:** Consulted AI to evaluate which algorithms would best fit the project's constraints, leading to the choice of DFS for generation and BFS for the shortest-path solver.

- **Concept Clarification:** Used to clarify complex low-level concepts, specifically bitwise math operations (~ and &) for wall manipulation.

