mazewright 0.1.0

A Python package for generating and visualizing mazes

Mazewright

A Python package for generating and visualizing perfect mazes using various algorithms.

Features

• Multiple algorithms: Recursive Backtracker, Prim's, and Kruskal's algorithms
• Clean API: Simple, intuitive interface for maze generation
• Visualization: Built-in matplotlib rendering with customizable styling
• CLI tool: Generate mazes from the command line
• Type hints: Full type annotations for better IDE support
• Well-tested: Comprehensive test suite ensuring perfect maze generation

Installation

pip install -e .

For development:

pip install -e ".[dev]"

Quick Start (30 seconds)

Python API

from mazewright import generate
from mazewright.visualize import save

# Generate a 20x20 maze using Prim's algorithm
maze = generate(20, 20, algorithm="prim")

# Save to file
save(maze, "my_maze.png")

Command Line

# Generate a maze with default settings
python -m mazewright

# Customize size and algorithm
python -m mazewright --rows 30 --cols 30 --algo kruskal --out maze.png

# Fine-tune appearance
python -m mazewright --rows 15 --cols 20 --cell-size 25 --wall-width 3

API Reference

Core Functions

# Generate a maze
maze = generate(rows=10, cols=10, algorithm="backtracker")

# Available algorithms:
# - "backtracker": Recursive backtracker (DFS)
# - "prim": Prim's algorithm (frontier growth)
# - "kruskal": Kruskal's algorithm (union-find)

Maze Object

from mazewright import Maze, Wall

# Create empty maze
maze = Maze(rows=10, cols=10)

# Access cells
cell = maze[0, 0]

# Check walls
if cell.has_wall(Wall.NORTH):
    print("Wall to the north")

# Carve passages manually
maze.carve(0, 0, 0, 1)  # Connect (0,0) to (0,1)

Visualization

from mazewright.visualize import render, save

# Render to matplotlib figure
fig = render(maze, cell_size=1.0, wall_width=2.0)

# Save to file
save(maze, "output.png", cell_size=20, wall_width=2, dpi=100)

Example Output

Running python -m mazewright --rows 15 --cols 15 --algo prim generates mazes like:

Algorithms

Recursive Backtracker

• Produces long, winding passages
• Low branching factor
• Implemented as iterative DFS for efficiency

Prim's Algorithm

• More uniform branching
• Grows from a frontier of cells
• Good balance of corridors and branches

Kruskal's Algorithm

• Most uniform distribution
• Uses union-find data structure
• Treats maze as a graph problem

Development

Setup

# Install with dev dependencies
pip install -e ".[dev]"

# Install pre-commit hooks
pre-commit install

Testing

pytest

Code Quality

# Format code
black mazewright tests

# Lint
ruff check mazewright tests

Architecture

mazewright/
├── __init__.py         # Public API
├── maze.py             # Core data structures
├── visualize.py        # Rendering engine
├── algorithms/
│   ├── backtracker.py  # Recursive backtracker
│   ├── prim.py         # Prim's algorithm
│   └── kruskal.py      # Kruskal's with union-find
└── __main__.py         # CLI entry point

Future Enhancements (v0.2+)

• Export formats: SVG, ASCII art
• Solver: Path-finding with visualization
• More algorithms: Wilson's, Aldous-Broder, Hunt-and-Kill
• Masks: Non-rectangular grids, shaped mazes
• Themes: Preset visual styles
• Animation: Step-by-step generation visualization

License

MIT

Version

v0.1.0 - Initial release with core functionality