squared_maze 0.1.0__tar.gz

squared_maze-0.1.0/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2025
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

squared_maze-0.1.0/PKG-INFO

@@ -0,0 +1,103 @@
+Metadata-Version: 2.4
+Name: squared_maze
+Version: 0.1.0
+Summary: Maze generator and A* solver with ASCII and image rendering
+Author-email: Jaime Pizarroso <jpizarroso@comillas.edu>
+License: MIT
+Keywords: maze,astar,generator,puzzle,visualization
+Classifier: Programming Language :: Python :: 3
+Classifier: License :: OSI Approved :: MIT License
+Classifier: Operating System :: OS Independent
+Requires-Python: >=3.8
+Description-Content-Type: text/markdown
+License-File: LICENSE
+Requires-Dist: Pillow>=9.0.0
+Dynamic: license-file
+
+# squared_maze
+
+Tiny Python package to generate grid mazes, solve them with A* and render
+ASCII and PNG visualizations. The project includes utilities to pick valid
+start/end cells, force a maze to become unsolvable, or introduce additional
+solutions by breaking walls.
+
+Features
+- Generate perfect mazes (recursive backtracker) as a grid where `1` is
+	walkable and `0` is a wall.
+- Solve with A* (`src/squared_maze/solver.py`).
+- Render ASCII (`grid_to_ascii`) with customizable symbols.
+- Render PNG images (Pillow) with start (green), end (red), path (blue),
+	walls (dark gray) and floors (light gray).
+- Helpers: `find_valid_cell`, `make_unsolvable`, `make_multiple_solutions`.
+
+Quick install
+
+This project requires Python 3.8+ and Pillow for image output. Install the
+dependency into your environment:
+
+```bash
+pip install pillow
+```
+
+Running the example notebook
+
+Open the example notebook `examples/maze_example.ipynb` with Jupyter or run it
+in a supported environment (VS Code/Jupyter Lab). The notebook demonstrates:
+- generating and solving a maze
+- saving two images (with and without the path)
+- creating an unsolvable variant
+- creating a variant with multiple distinct solutions
+
+If running the notebook from the repository you may need to add the project
+`src` folder to `PYTHONPATH`. From the repository root you can run a small
+script or open a Python REPL like this:
+
+```bash
+python3 -c "import sys; from pathlib import Path; sys.path.insert(0, str(Path('src').resolve())); from squared_maze import generate_maze, astar, grid_to_ascii; g=generate_maze(12,20,seed=42); print(grid_to_ascii(g, None))"
+```
+
+Basic usage (script)
+
+```python
+from squared_maze import (
+		generate_maze,
+		astar,
+		grid_to_ascii,
+		save_images,
+		find_valid_cell,
+)
+
+# generate
+grid = generate_maze(12, 20, seed=42)
+start = find_valid_cell(grid, seed=1)
+end = find_valid_cell(grid, exclude={start}, seed=2)
+path = astar(grid, start, end)
+
+print(grid_to_ascii(grid, path, start, end))
+save_images(grid, path, start, end, cell_size=24, out_prefix='maze_out')
+```
+
+API (key functions)
+- `generate_maze(rows, cols, seed=None)` -> grid
+- `astar(grid, start, end)` -> list of coordinates or `None`
+- `grid_to_ascii(grid, path=None, start=None, end=None, ...)` -> str (customizable symbols)
+- `save_images(grid, path=None, start=None, end=None, cell_size=16, out_prefix='maze')` -> (fn_no, fn_yes)
+- `find_valid_cell(grid, exclude=None, seed=None)` -> (row, col)
+- `make_unsolvable(grid, start, end, astar_fn, ...)` -> bool (modifies grid)
+- `make_multiple_solutions(grid, start, end, astar_fn, ...)` -> bool (modifies grid)
+
+Notes
+- The generator produces a perfect maze (a spanning tree). That means there
+	is exactly one path between any two room cells until you deliberately
+	break walls (e.g. with `make_multiple_solutions`). Use `find_valid_cell`
+	to pick valid walkable start/end cells.
+- Images are saved to the working directory. Filenames are returned by
+	`save_images`.
+
+Contributing
+- Small, self-contained patches are welcome. Please keep docstrings and
+	code PEP8-compatible and add a short test if you change core behaviour.
+
+License
+- This repository does not include an explicit license file. Add one if you
+	intend to publish or share the code.

squared_maze-0.1.0/README.md

@@ -0,0 +1,87 @@
+# squared_maze
+
+Tiny Python package to generate grid mazes, solve them with A* and render
+ASCII and PNG visualizations. The project includes utilities to pick valid
+start/end cells, force a maze to become unsolvable, or introduce additional
+solutions by breaking walls.
+
+Features
+- Generate perfect mazes (recursive backtracker) as a grid where `1` is
+	walkable and `0` is a wall.
+- Solve with A* (`src/squared_maze/solver.py`).
+- Render ASCII (`grid_to_ascii`) with customizable symbols.
+- Render PNG images (Pillow) with start (green), end (red), path (blue),
+	walls (dark gray) and floors (light gray).
+- Helpers: `find_valid_cell`, `make_unsolvable`, `make_multiple_solutions`.
+
+Quick install
+
+This project requires Python 3.8+ and Pillow for image output. Install the
+dependency into your environment:
+
+```bash
+pip install pillow
+```
+
+Running the example notebook
+
+Open the example notebook `examples/maze_example.ipynb` with Jupyter or run it
+in a supported environment (VS Code/Jupyter Lab). The notebook demonstrates:
+- generating and solving a maze
+- saving two images (with and without the path)
+- creating an unsolvable variant
+- creating a variant with multiple distinct solutions
+
+If running the notebook from the repository you may need to add the project
+`src` folder to `PYTHONPATH`. From the repository root you can run a small
+script or open a Python REPL like this:
+
+```bash
+python3 -c "import sys; from pathlib import Path; sys.path.insert(0, str(Path('src').resolve())); from squared_maze import generate_maze, astar, grid_to_ascii; g=generate_maze(12,20,seed=42); print(grid_to_ascii(g, None))"
+```
+
+Basic usage (script)
+
+```python
+from squared_maze import (
+		generate_maze,
+		astar,
+		grid_to_ascii,
+		save_images,
+		find_valid_cell,
+)
+
+# generate
+grid = generate_maze(12, 20, seed=42)
+start = find_valid_cell(grid, seed=1)
+end = find_valid_cell(grid, exclude={start}, seed=2)
+path = astar(grid, start, end)
+
+print(grid_to_ascii(grid, path, start, end))
+save_images(grid, path, start, end, cell_size=24, out_prefix='maze_out')
+```
+
+API (key functions)
+- `generate_maze(rows, cols, seed=None)` -> grid
+- `astar(grid, start, end)` -> list of coordinates or `None`
+- `grid_to_ascii(grid, path=None, start=None, end=None, ...)` -> str (customizable symbols)
+- `save_images(grid, path=None, start=None, end=None, cell_size=16, out_prefix='maze')` -> (fn_no, fn_yes)
+- `find_valid_cell(grid, exclude=None, seed=None)` -> (row, col)
+- `make_unsolvable(grid, start, end, astar_fn, ...)` -> bool (modifies grid)
+- `make_multiple_solutions(grid, start, end, astar_fn, ...)` -> bool (modifies grid)
+
+Notes
+- The generator produces a perfect maze (a spanning tree). That means there
+	is exactly one path between any two room cells until you deliberately
+	break walls (e.g. with `make_multiple_solutions`). Use `find_valid_cell`
+	to pick valid walkable start/end cells.
+- Images are saved to the working directory. Filenames are returned by
+	`save_images`.
+
+Contributing
+- Small, self-contained patches are welcome. Please keep docstrings and
+	code PEP8-compatible and add a short test if you change core behaviour.
+
+License
+- This repository does not include an explicit license file. Add one if you
+	intend to publish or share the code.

squared_maze-0.1.0/pyproject.toml

@@ -0,0 +1,17 @@
+[project]
+name = "squared_maze"
+version = "0.1.0"
+description = "Maze generator and A* solver with ASCII and image rendering"
+readme = "README.md"
+requires-python = ">=3.8"
+license = { text = "MIT" }
+authors = [ { name = "Jaime Pizarroso", email = "jpizarroso@comillas.edu" } ]
+keywords = ["maze", "astar", "generator", "puzzle", "visualization"]
+classifiers = [
+	"Programming Language :: Python :: 3",
+	"License :: OSI Approved :: MIT License",
+	"Operating System :: OS Independent",
+]
+dependencies = [
+	"Pillow>=9.0.0"
+]

squared_maze-0.1.0/setup.cfg

@@ -0,0 +1,4 @@
+[egg_info]
+tag_build = 
+tag_date = 0
+

squared_maze-0.1.0/src/squared_maze/__init__.py

@@ -0,0 +1,17 @@
+"""Top-level package for maze generator and solver.
+
+Expose main helpers: generate_maze, solve_maze, render helpers.
+"""
+from .generator import generate_maze, find_valid_cell, make_multiple_solutions, make_unsolvable
+from .solver import astar
+from .render import grid_to_ascii, save_images
+
+__all__ = [
+	"generate_maze",
+	"find_valid_cell",
+	"make_multiple_solutions",
+	"make_unsolvable",
+	"astar",
+	"grid_to_ascii",
+	"save_images",
+]

squared_maze-0.1.0/src/squared_maze/generator.py

@@ -0,0 +1,293 @@
+"""Maze generation utilities.
+
+This module implements a randomized depth-first search (recursive backtracker)
+to carve a perfect maze into a grid that includes walls as cells. The
+public function `generate_maze` accepts the number of logical rows and columns
+and returns a grid of size (2*rows+1) x (2*cols+1) where 1 indicates a
+walkable cell and 0 indicates a wall.
+
+The grid layout uses odd indices for rooms/cells and even indices for walls.
+This makes it simple to carve passages by stepping two cells at a time and
+clearing the intermediate wall.
+
+All functions follow Google style docstrings and minimal external deps.
+"""
+from __future__ import annotations
+
+import random
+from typing import List, Optional, Tuple, Set, Callable
+
+
+def _make_grid(rows: int, cols: int) -> List[List[int]]:
+    """Create a grid initialized with walls (0).
+
+    Args:
+        rows: number of logical rows (rooms).
+        cols: number of logical columns (rooms).
+
+    Returns:
+        A list of lists representing the grid with shape (2*rows+1) x (2*cols+1).
+    """
+    height = 2 * rows + 1
+    width = 2 * cols + 1
+    return [[0 for _ in range(width)] for _ in range(height)]
+
+
+def generate_maze(rows: int, cols: int, seed: Optional[int] = None) -> List[List[int]]:
+    """Generate a perfect maze using recursive backtracker.
+
+    The returned grid is (2*rows+1) x (2*cols+1) with:
+    - 1: walkable cell
+    - 0: wall
+
+    Args:
+        rows: number of logical rows (rooms).
+        cols: number of logical columns (rooms).
+        seed: optional random seed for reproducibility.
+
+    Returns:
+        A 2D grid of ints (1 walkable, 0 wall).
+
+    Raises:
+        ValueError: if rows or cols are less than 1.
+    """
+    if rows < 1 or cols < 1:
+        raise ValueError("rows and cols must be >= 1")
+
+    rng = random.Random(seed)
+    grid = _make_grid(rows, cols)
+
+    # Helper to convert room coordinates (r,c) in [0,rows) to grid coords
+    def to_grid(rc: Tuple[int, int]) -> Tuple[int, int]:
+        r, c = rc
+        return 2 * r + 1, 2 * c + 1
+
+    visited = [[False for _ in range(cols)] for _ in range(rows)]
+
+    # Neighbor deltas in room coordinates (4-connectivity)
+    deltas = [(0, 1), (1, 0), (0, -1), (-1, 0)]
+
+    def carve(r: int, c: int) -> None:
+        """Recursively carve passages starting from room (r,c)."""
+        visited[r][c] = True
+        gr, gc = to_grid((r, c))
+        grid[gr][gc] = 1
+
+        # randomize neighbor order
+        rng.shuffle(deltas)
+        for dr, dc in deltas:
+            nr, nc = r + dr, c + dc
+            if 0 <= nr < rows and 0 <= nc < cols and not visited[nr][nc]:
+                # remove wall between (r,c) and (nr,nc)
+                gr2, gc2 = to_grid((nr, nc))
+                wall_r, wall_c = (gr + gr2) // 2, (gc + gc2) // 2
+                grid[wall_r][wall_c] = 1
+                carve(nr, nc)
+
+    carve(0, 0)
+
+    return grid
+
+
+def find_valid_cell(grid: List[List[int]], exclude: Optional[Set[Tuple[int, int]]] = None,
+                    seed: Optional[int] = None) -> Tuple[int, int]:
+    """Return a random valid (walkable) cell coordinate from the grid.
+
+    The function scans the provided `grid` (where 1 means walkable and 0 means
+    wall) and returns a randomly chosen coordinate (row, col) such that the
+    cell is walkable and not in the optional `exclude` set.
+
+    Args:
+        grid: 2D grid produced by :func:`generate_maze` where 1 is walkable.
+        exclude: optional set of coordinates to avoid (for example the start
+            when choosing an end cell).
+        seed: optional integer seed for reproducible selection. If omitted a
+            default random source is used.
+
+    Returns:
+        A tuple (row, col) pointing to a walkable cell in the grid.
+
+    Raises:
+        ValueError: if no valid cell can be found (for example a grid with no
+            walkable cells or all walkable cells are excluded).
+    """
+    rng = random.Random(seed)
+    rows = len(grid)
+    if rows == 0:
+        raise ValueError("grid must be non-empty")
+    cols = len(grid[0])
+
+    exclude = exclude or set()
+
+    # collect all walkable cells not in exclude
+    candidates: List[Tuple[int, int]] = [
+        (r, c)
+        for r in range(rows)
+        for c in range(cols)
+        if grid[r][c] == 1 and (r, c) not in exclude
+    ]
+
+    if not candidates:
+        raise ValueError("no valid walkable cells available to choose from")
+
+    return rng.choice(candidates)
+
+
+def make_multiple_solutions(
+    grid: List[List[int]],
+    start: Tuple[int, int],
+    end: Tuple[int, int],
+    astar_fn: Callable,
+    max_tries: int = 200,
+    seed: Optional[int] = None,
+) -> bool:
+    """Modify ``grid`` by breaking walls until the maze has multiple solutions.
+
+    This function attempts to create an alternate path between ``start`` and
+    ``end`` by turning wall cells (0) into walkable cells (1). After each
+    candidate wall removal it calls ``astar_fn(grid, start, end)`` to check if
+    the returned path differs from the original one. The grid is modified in
+    place and the function returns True on success.
+
+    Args:
+        grid: 2D grid where 1 is walkable and 0 is wall.
+        start: start coordinate (row, col).
+        end: end coordinate (row, col).
+        astar_fn: function implementing A* search with signature
+            ``astar_fn(grid, start, end) -> Optional[List[Tuple[int,int]]]``.
+        max_tries: maximum number of candidate walls to try.
+        seed: optional seed for reproducibility.
+
+    Returns:
+        True if the grid was modified to produce multiple distinct solutions
+        between start and end, False otherwise.
+
+    Raises:
+        ValueError: if start or end are not walkable.
+    """
+    rng = random.Random(seed)
+
+    if grid[start[0]][start[1]] != 1 or grid[end[0]][end[1]] != 1:
+        raise ValueError("start and end must be walkable cells (grid value 1)")
+
+    orig_path = astar_fn(grid, start, end)
+    if not orig_path:
+        # nothing to make multiple if they are not connected
+        return False
+
+    rows = len(grid)
+    cols = len(grid[0])
+
+    # candidate wall cells that when removed connect two or more walkable neighbors
+    candidates: List[Tuple[int, int]] = []
+    for r in range(rows):
+        for c in range(cols):
+            if grid[r][c] != 0:
+                continue
+            neighs = 0
+            for dr, dc in ((0, 1), (1, 0), (0, -1), (-1, 0)):
+                nr, nc = r + dr, c + dc
+                if 0 <= nr < rows and 0 <= nc < cols and grid[nr][nc] == 1:
+                    neighs += 1
+            if neighs >= 2:
+                candidates.append((r, c))
+
+    rng.shuffle(candidates)
+
+    tries = 0
+    for (r, c) in candidates:
+        if tries >= max_tries:
+            break
+        tries += 1
+        # try removing this wall
+        grid[r][c] = 1
+        new_path = astar_fn(grid, start, end)
+        if new_path and new_path != orig_path:
+            return True
+        # revert
+        grid[r][c] = 0
+
+    return False
+
+
+def make_unsolvable(
+    grid: List[List[int]],
+    start: Tuple[int, int],
+    end: Tuple[int, int],
+    astar_fn: Callable,
+    seed: Optional[int] = None,
+    max_tries: int = 100,
+) -> bool:
+    """Modify ``grid`` to make the maze unsolvable between ``start`` and
+    ``end``.
+
+    The function finds an existing path between ``start`` and ``end`` and
+    then blocks one or more intermediate cells along that path (not start or
+    end) to disconnect the endpoints. Returns True if the grid was modified
+    and the two points are no longer connected.
+
+    Args:
+        grid: 2D grid where 1 is walkable and 0 is wall.
+        start: start coordinate (row, col).
+        end: end coordinate (row, col).
+        astar_fn: function implementing A* search with signature
+            ``astar_fn(grid, start, end) -> Optional[List[Tuple[int,int]]]``.
+        seed: optional seed for reproducibility.
+        max_tries: maximum attempts to block different intermediate cells.
+
+    Returns:
+        True if the grid was modified so that no path exists between start and end,
+        False if unsuccessful.
+
+    Raises:
+        ValueError: if start or end are not walkable.
+    """
+    rng = random.Random(seed)
+
+    if grid[start[0]][start[1]] != 1 or grid[end[0]][end[1]] != 1:
+        raise ValueError("start and end must be walkable cells (grid value 1)")
+
+    path = astar_fn(grid, start, end)
+    if not path:
+        # already unsolvable
+        return True
+
+    # consider intermediate path cells (exclude start/end)
+    intermediates = [p for p in path[1:-1]]
+    if not intermediates:
+        # direct neighbors — blocking one neighbor should work though
+        intermediates = [path[1]] if len(path) > 1 else []
+
+    rng.shuffle(intermediates)
+    tries = 0
+    for cell in intermediates:
+        if tries >= max_tries:
+            break
+        tries += 1
+        r, c = cell
+        saved = grid[r][c]
+        grid[r][c] = 0
+        if not astar_fn(grid, start, end):
+            return True
+        # revert and try next
+        grid[r][c] = saved
+
+    # as a fallback, try blocking additional nearby walkable cells
+    rows = len(grid)
+    cols = len(grid[0])
+    all_walkables = [(r, c) for r in range(rows) for c in range(cols) if grid[r][c] == 1 and (r, c) not in (start, end)]
+    rng.shuffle(all_walkables)
+    for (r, c) in all_walkables[:max_tries]:
+        saved = grid[r][c]
+        grid[r][c] = 0
+        if not astar_fn(grid, start, end):
+            return True
+        grid[r][c] = saved
+
+    return False
+
+
+if __name__ == "__main__":
+    g = generate_maze(5, 10, seed=1)
+    for row in g:
+        print(''.join(['.' if c else '#' for c in row]))

squared_maze-0.1.0/src/squared_maze/render.py

@@ -0,0 +1,157 @@
+"""Rendering utilities for the maze: ASCII and images.
+
+The image functions use Pillow to create a visualization of the grid. Walls are
+dark gray, walkable light gray, start green, end red, and path cells blue.
+Thin black separators are drawn between cells.
+"""
+from __future__ import annotations
+
+from typing import List, Optional, Tuple
+
+from PIL import Image, ImageDraw
+
+Coord = Tuple[int, int]
+
+
+def grid_to_ascii(
+    grid: List[List[int]],
+    path: Optional[List[Coord]] = None,
+    start: Optional[Coord] = None,
+    end: Optional[Coord] = None,
+    start_sym: str = "S",
+    end_sym: str = "E",
+    wall_sym: str = "█",
+    path_sym: str = "*",
+    walkable_sym: str = ".",
+) -> str:
+    """Return an ASCII representation of the maze using customizable symbols.
+
+    The function renders the grid into a multiline string. By default the
+    following symbols are used:
+    - start: ``S``
+    - end: ``E``
+    - wall: ``█``
+    - path (non start/end cells): ``*``
+    - walkable cells: ``.``
+
+    Args:
+        grid: 2D grid where 1 is walkable and 0 is wall.
+        path: optional list of coordinates that form the solution path.
+        start: optional start coordinate to mark with ``start_sym``.
+        end: optional end coordinate to mark with ``end_sym``.
+        start_sym: symbol used for the start cell. Defaults to ``'S'``.
+        end_sym: symbol used for the end cell. Defaults to ``'E'``.
+        wall_sym: symbol used for walls. Defaults to ``'█'``.
+        path_sym: symbol used for path cells (excluding start/end). Defaults to ``'*'``.
+        walkable_sym: symbol used for ordinary walkable cells. Defaults to ``'.'``.
+
+    Returns:
+        A multiline string with characters representing the maze.
+    """
+
+    path_set = set(path) if path else set()
+    lines: List[str] = []
+    for r, row in enumerate(grid):
+        line_chars: List[str] = []
+        for c, cell in enumerate(row):
+            coord = (r, c)
+            if start is not None and coord == start:
+                line_chars.append(start_sym)
+            elif end is not None and coord == end:
+                line_chars.append(end_sym)
+            elif coord in path_set and coord != start and coord != end:
+                line_chars.append(path_sym)
+            elif cell == 0:
+                line_chars.append(wall_sym)
+            else:
+                line_chars.append(walkable_sym)
+        lines.append("".join(line_chars))
+    return "\n".join(lines)
+
+
+def save_images(grid: List[List[int]], path: Optional[List[Coord]] = None,
+                start: Optional[Coord] = None, end: Optional[Coord] = None,
+                cell_size: int = 16, out_prefix: str = "maze") -> Tuple[str, str]:
+    """Save two PNG images: one without the path and one including the path.
+
+    Args:
+        grid: 2D grid where 1 is walkable and 0 is wall.
+        path: optional solution path.
+        start: optional start coordinate.
+        end: optional end coordinate.
+        cell_size: size in pixels of each cell.
+        out_prefix: prefix for output filenames.
+
+    Returns:
+        Tuple of filenames (without_path_png, with_path_png).
+    """
+    rows = len(grid)
+    cols = len(grid[0])
+    # line thickness 1 pixel between cells
+    img_w = cols * cell_size + (cols + 1)
+    img_h = rows * cell_size + (rows + 1)
+
+    def draw(with_path: bool) -> Image.Image:
+        img = Image.new("RGB", (img_w, img_h), color=(0, 0, 0))
+        draw = ImageDraw.Draw(img)
+
+        wall_color = (40, 40, 40)        # very dark gray
+        floor_color = (211, 211, 211)    # lightgray
+        start_color = (0, 200, 0)
+        end_color = (200, 0, 0)
+        path_color = (0, 0, 200)
+
+        def cell_bbox(r: int, c: int):
+            x0 = c * cell_size + (c + 1)
+            y0 = r * cell_size + (r + 1)
+            x1 = x0 + cell_size - 1
+            y1 = y0 + cell_size - 1
+            return x0, y0, x1, y1
+
+        path_set = set(path) if path else set()
+
+        for r in range(rows):
+            for c in range(cols):
+                bbox = cell_bbox(r, c)
+                if grid[r][c] == 0:
+                    draw.rectangle(bbox, fill=wall_color)
+                else:
+                    draw.rectangle(bbox, fill=floor_color)
+
+        # draw path on top if requested
+        if with_path and path:
+            for (r, c) in path:
+                if (r, c) == start or (r, c) == end:
+                    continue
+                bbox = cell_bbox(r, c)
+                draw.rectangle(bbox, fill=path_color)
+
+        # draw start and end
+        if start:
+            draw.rectangle(cell_bbox(*start), fill=start_color)
+        if end:
+            draw.rectangle(cell_bbox(*end), fill=end_color)
+
+        # thin black separators already present as background; optionally draw outlines
+        return img
+
+    img_no = draw(False)
+    img_yes = draw(True)
+
+    fn_no = f"{out_prefix}.png"
+    fn_yes = f"{out_prefix}_path.png"
+    img_no.save(fn_no)
+    img_yes.save(fn_yes)
+    return fn_no, fn_yes
+
+
+if __name__ == "__main__":
+    from .generator import generate_maze
+    from .solver import astar
+
+    g = generate_maze(10, 16, seed=1)
+    start = (1, 1)
+    end = (len(g) - 2, len(g[0]) - 2)
+    p = astar(g, start, end)
+    print(grid_to_ascii(g, p, start, end))
+    save_images(g, p, start, end, cell_size=12, out_prefix="demo_maze")

squared_maze-0.1.0/src/squared_maze/solver.py

@@ -0,0 +1,90 @@
+"""A* path finding for the maze grid.
+
+This module implements a simple A* search over the grid produced by
+`generate_maze`. It expects a grid where 1 means walkable and 0 means wall.
+"""
+from __future__ import annotations
+
+import heapq
+from typing import List, Tuple, Optional, Dict
+
+
+Coord = Tuple[int, int]
+
+
+def _neighbors(grid: List[List[int]], node: Coord) -> List[Coord]:
+    rows = len(grid)
+    cols = len(grid[0])
+    r, c = node
+    nbrs = []
+    for dr, dc in ((0, 1), (1, 0), (0, -1), (-1, 0)):
+        nr, nc = r + dr, c + dc
+        if 0 <= nr < rows and 0 <= nc < cols and grid[nr][nc] == 1:
+            nbrs.append((nr, nc))
+    return nbrs
+
+
+def _heuristic(a: Coord, b: Coord) -> int:
+    # Manhattan distance
+    return abs(a[0] - b[0]) + abs(a[1] - b[1])
+
+
+def astar(grid: List[List[int]], start: Coord, goal: Coord) -> Optional[List[Coord]]:
+    """Find a path from start to goal using A*.
+
+    Args:
+        grid: 2D grid where 1 is walkable and 0 is wall.
+        start: (row, col) start coordinate.
+        goal: (row, col) goal coordinate.
+
+    Returns:
+        A list of coordinates from start to goal (inclusive) if a path exists,
+        otherwise None.
+    """
+    if grid[start[0]][start[1]] != 1 or grid[goal[0]][goal[1]] != 1:
+        return None
+
+    open_set: List[Tuple[int, Coord]] = []
+    heapq.heappush(open_set, (0, start))
+
+    came_from: Dict[Coord, Coord] = {}
+    gscore: Dict[Coord, int] = {start: 0}
+    fscore: Dict[Coord, int] = {start: _heuristic(start, goal)}
+
+    closed = set()
+
+    while open_set:
+        _, current = heapq.heappop(open_set)
+        if current == goal:
+            # reconstruct path
+            path = [current]
+            while path[-1] != start:
+                path.append(came_from[path[-1]])
+            path.reverse()
+            return path
+
+        closed.add(current)
+
+        for nbr in _neighbors(grid, current):
+            if nbr in closed:
+                continue
+            tentative_g = gscore[current] + 1
+            if tentative_g < gscore.get(nbr, 1_000_000):
+                came_from[nbr] = current
+                gscore[nbr] = tentative_g
+                f = tentative_g + _heuristic(nbr, goal)
+                fscore[nbr] = f
+                heapq.heappush(open_set, (f, nbr))
+
+    return None
+
+
+if __name__ == "__main__":
+    # quick smoke test
+    from .generator import generate_maze
+
+    g = generate_maze(5, 8, seed=2)
+    start = (1, 1)
+    goal = (len(g) - 2, len(g[0]) - 2)
+    p = astar(g, start, goal)
+    print("Path length:", len(p) if p else None)

squared_maze-0.1.0/src/squared_maze.egg-info/PKG-INFO

@@ -0,0 +1,103 @@
+Metadata-Version: 2.4
+Name: squared_maze
+Version: 0.1.0
+Summary: Maze generator and A* solver with ASCII and image rendering
+Author-email: Jaime Pizarroso <jpizarroso@comillas.edu>
+License: MIT
+Keywords: maze,astar,generator,puzzle,visualization
+Classifier: Programming Language :: Python :: 3
+Classifier: License :: OSI Approved :: MIT License
+Classifier: Operating System :: OS Independent
+Requires-Python: >=3.8
+Description-Content-Type: text/markdown
+License-File: LICENSE
+Requires-Dist: Pillow>=9.0.0
+Dynamic: license-file
+
+# squared_maze
+
+Tiny Python package to generate grid mazes, solve them with A* and render
+ASCII and PNG visualizations. The project includes utilities to pick valid
+start/end cells, force a maze to become unsolvable, or introduce additional
+solutions by breaking walls.
+
+Features
+- Generate perfect mazes (recursive backtracker) as a grid where `1` is
+	walkable and `0` is a wall.
+- Solve with A* (`src/squared_maze/solver.py`).
+- Render ASCII (`grid_to_ascii`) with customizable symbols.
+- Render PNG images (Pillow) with start (green), end (red), path (blue),
+	walls (dark gray) and floors (light gray).
+- Helpers: `find_valid_cell`, `make_unsolvable`, `make_multiple_solutions`.
+
+Quick install
+
+This project requires Python 3.8+ and Pillow for image output. Install the
+dependency into your environment:
+
+```bash
+pip install pillow
+```
+
+Running the example notebook
+
+Open the example notebook `examples/maze_example.ipynb` with Jupyter or run it
+in a supported environment (VS Code/Jupyter Lab). The notebook demonstrates:
+- generating and solving a maze
+- saving two images (with and without the path)
+- creating an unsolvable variant
+- creating a variant with multiple distinct solutions
+
+If running the notebook from the repository you may need to add the project
+`src` folder to `PYTHONPATH`. From the repository root you can run a small
+script or open a Python REPL like this:
+
+```bash
+python3 -c "import sys; from pathlib import Path; sys.path.insert(0, str(Path('src').resolve())); from squared_maze import generate_maze, astar, grid_to_ascii; g=generate_maze(12,20,seed=42); print(grid_to_ascii(g, None))"
+```
+
+Basic usage (script)
+
+```python
+from squared_maze import (
+		generate_maze,
+		astar,
+		grid_to_ascii,
+		save_images,
+		find_valid_cell,
+)
+
+# generate
+grid = generate_maze(12, 20, seed=42)
+start = find_valid_cell(grid, seed=1)
+end = find_valid_cell(grid, exclude={start}, seed=2)
+path = astar(grid, start, end)
+
+print(grid_to_ascii(grid, path, start, end))
+save_images(grid, path, start, end, cell_size=24, out_prefix='maze_out')
+```
+
+API (key functions)
+- `generate_maze(rows, cols, seed=None)` -> grid
+- `astar(grid, start, end)` -> list of coordinates or `None`
+- `grid_to_ascii(grid, path=None, start=None, end=None, ...)` -> str (customizable symbols)
+- `save_images(grid, path=None, start=None, end=None, cell_size=16, out_prefix='maze')` -> (fn_no, fn_yes)
+- `find_valid_cell(grid, exclude=None, seed=None)` -> (row, col)
+- `make_unsolvable(grid, start, end, astar_fn, ...)` -> bool (modifies grid)
+- `make_multiple_solutions(grid, start, end, astar_fn, ...)` -> bool (modifies grid)
+
+Notes
+- The generator produces a perfect maze (a spanning tree). That means there
+	is exactly one path between any two room cells until you deliberately
+	break walls (e.g. with `make_multiple_solutions`). Use `find_valid_cell`
+	to pick valid walkable start/end cells.
+- Images are saved to the working directory. Filenames are returned by
+	`save_images`.
+
+Contributing
+- Small, self-contained patches are welcome. Please keep docstrings and
+	code PEP8-compatible and add a short test if you change core behaviour.
+
+License
+- This repository does not include an explicit license file. Add one if you
+	intend to publish or share the code.

squared_maze-0.1.0/src/squared_maze.egg-info/SOURCES.txt

@@ -0,0 +1,12 @@
+LICENSE
+README.md
+pyproject.toml
+src/squared_maze/__init__.py
+src/squared_maze/generator.py
+src/squared_maze/render.py
+src/squared_maze/solver.py
+src/squared_maze.egg-info/PKG-INFO
+src/squared_maze.egg-info/SOURCES.txt
+src/squared_maze.egg-info/dependency_links.txt
+src/squared_maze.egg-info/requires.txt
+src/squared_maze.egg-info/top_level.txt

squared_maze-0.1.0/src/squared_maze.egg-info/dependency_links.txt

@@ -0,0 +1 @@
+

squared_maze-0.1.0/src/squared_maze.egg-info/requires.txt

@@ -0,0 +1 @@
+Pillow>=9.0.0

squared_maze-0.1.0/src/squared_maze.egg-info/top_level.txt

@@ -0,0 +1 @@
+squared_maze