Skip to main content

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. It can also export mazes to PDDL for planning experiments.

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).
  • Export to PDDL (generate_pddl) as a domain+problem string.
  • 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:

pip install pillow

Then install the package

pip install squared_maze

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:

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)

from squared_maze import (
		generate_maze,
		astar,
		grid_to_ascii,
		save_images,
		generate_pddl,
		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')

# optional: export planning model (domain + problem)
pddl_text = generate_pddl(grid, start=start, end=end)
with open('maze.pddl', 'w', encoding='utf-8') as f:
	f.write(pddl_text)

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)
  • generate_pddl(grid, start=None, end=None, domain_name='maze', problem_name='maze_problem') -> str
  • 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.

Metadata

Release files for squared_maze 0.1.4

For a detailed explanation of source distributions (sdists) and built distributions (wheels), please see the package formats documentation.

Source distribution (sdist)

Source distribution for squared_maze 0.1.4
File Size Uploaded Provenance Actions
squared_maze-0.1.4.tar.gz 12.0 kB Without provenance Details for squared_maze-0.1.4.tar.gz

Built distribution (wheel)

Table of built distributions (wheels) for squared_maze 0.1.4
File Interpreter ABI Platform Actions
squared_maze-0.1.4-py3-none-any.whl Python 3 none any Details for squared_maze-0.1.4-py3-none-any.whl

Total release size: 23.9 kB

Release files / squared_maze-0.1.4.tar.gz

Download URL squared_maze-0.1.4.tar.gz
Size 12.0 kB
Tags Source
SHA-256 checksum
How to use checksums
da31c801bc4aeddf0fc590aa5a19378d326e9dc525c6a38cfc809db44eb7371d
BLAKE2b-256 checksum
How to use checksums
8b6a48a1433bb0178f8c04c7ce4a29118553c1f407c403e43e277b1b22cf1aca
Upload date
Uploaded using Trusted Publishing?
What is trusted publishing?
No
Uploaded via uv/0.7.13

Release files / squared_maze-0.1.4-py3-none-any.whl

Download URL squared_maze-0.1.4-py3-none-any.whl
Size 11.9 kB
Tags Python 3
SHA-256 checksum
How to use checksums
1db287f6ca5e4b44106f2dd2cb23c3453959250079f83548b302a709d0ba8556
BLAKE2b-256 checksum
How to use checksums
3ee13f1275cb96d9bc8f330f63d643f1752a6931410fc21cd525376eb4717cd7
Upload date
Uploaded using Trusted Publishing?
What is trusted publishing?
No
Uploaded via uv/0.7.13

Security for squared_maze 0.1.4

Provenance

Provenance describes where a file came from. On PyPI, provenance is shared via attestations, which provide a verifiable record of the build or publishing details. View details, limitations and caveats.

No provenance found

None of the files in this release were uploaded with provenance metadata.

A note on package security

PyPI is a repository for distributing packages, not a service for auditing them. While third-party security researchers and our staff do their best to detect and remove malicious packages, PyPI cannot guarantee the quality, security or suitability of any given package.

To learn more about protecting yourself from malicious actors, visit our package security documentation.

Anthropic, PBC Visionary sponsor Bloomberg Visionary sponsor Hudson River Trading Visionary sponsor Meta Visionary sponsor NVIDIA Visionary sponsor Microsoft Sustainability sponsor Depot Continuous Integration AWS Cloud computing and Security Sponsor Datadog Monitoring Fastly CDN Google Download Analytics Sentry Error logging StatusPage Status page