Skip to content

Getting Started

Installation

You can install blacksquare using pip or uv:

uv add blacksquare

pip install blacksquare

pip install "blacksquare[pdf]"

Creating Your First Puzzle

1. Initialize a Grid

You can create an empty square or rectangular grid by specifying dimensions:

from blacksquare import Crossword, Symmetry

# 15x15 standard weekday crossword with rotational symmetry
xw = Crossword(15, 15, symmetry=Symmetry.ROTATIONAL)

2. Add Black Squares

Black squares can be assigned using (row, col) coordinates. Because symmetry is enabled by default, setting a black block automatically updates the symmetric cell:

from blacksquare import BLACK

xw[0, 4] = BLACK  # Also places BLACK at [14, 10] symmetrically

3. Inspect the Grid

Print your grid to the console with numbers and clues:

xw.pprint(numbers=True)

In Jupyter notebooks, simply typing xw on the last line renders a styled HTML crossword grid.

Next Steps