Blacksquare

Build Status Documentation Status

Blacksquare is a Python package for crossword creators. It aims to be an intuitive interface for working with crossword puzzles programmatically. It features high-performance grid solving powered by a Rust backend, rich HTML rendering that plugs nicely into Jupyter notebooks, native Across Lite (.puz) file import and export (with support for rebuses and circles), and .pdf export in the New York Times submission format (requires the [pdf] extra).

Native HTML rendering in Jupyter

Jupyter example

Basic features

The interface is built to use Python's indexing syntax to express high-level crossword concepts.

>>> from blacksquare import Crossword, BLACK, EMPTY, ACROSS, DOWN, DEFAULT_WORDLIST
>>> xw = Crossword(num_rows=7)
# (row, column) indexing for individual cells
>>> xw[3,3] = BLACK
>>> xw.pprint(numbers=True)
┌───┬───┬───┬───┬───┬───┬───┐
│ 1 │ 2 │ 3 │ 4 │ 5 │ 6 │ 7 │
├───┼───┼───┼───┼───┼───┼───┤
│ 8 │   │   │   │   │   │   │
├───┼───┼───┼───┼───┼───┼───┤
│ 9 │   │   │   │   │   │   │
├───┼───┼───┼───┼───┼───┼───┤
│10 │   │   │███│11 │   │   │
├───┼───┼───┼───┼───┼───┼───┤
│12 │   │   │13 │   │   │   │
├───┼───┼───┼───┼───┼───┼───┤
│14 │   │   │   │   │   │   │
├───┼───┼───┼───┼───┼───┼───┤
│15 │   │   │   │   │   │   │
└───┴───┴───┴───┴───┴───┴───┘
# (direction, number) indexing for words
>>> xw[ACROSS, 10] = 'DOE'
>>> xw[DOWN, 3] = xw[DOWN, 3].find_matches().words[0]
# Only last digits of numbers fit in this view
>>> xw.pprint()
┌───┬───┬───┬───┬───┬───┬───┐
│¹  │²  │³B │⁴  │⁵  │⁶  │⁷  │
├───┼───┼───┼───┼───┼───┼───┤
│⁸  │   │ A │   │   │   │   │
├───┼───┼───┼───┼───┼───┼───┤
│⁹  │   │ R │   │   │   │   │
├───┼───┼───┼───┼───┼───┼───┤
│⁰D │ O │ E │███│¹  │   │   │
├───┼───┼───┼───┼───┼───┼───┤
│²  │   │ X │³  │   │   │   │
├───┼───┼───┼───┼───┼───┼───┤
│⁴  │   │ A │   │   │   │   │
├───┼───┼───┼───┼───┼───┼───┤
│⁵  │   │ M │   │   │   │   │
└───┴───┴───┴───┴───┴───┴───┘
# We can also index into Word objects
>>> xw[DOWN, 3][0] = EMPTY
>>> xw[DOWN, 3].value
' AREXAM'

Puzzles can be imported and exported easily.

>>> xw.to_puz('puzzle.puz')
>>> xw = Crossword.from_puz('puzzle.puz')
>>> xw.to_pdf('puzzle.pdf', header=['Name', 'Address', 'Email'])

There are useful utility functions for navigating.

>>> unfilled_words = list(xw.iterwords(only_open=True))
>>> xw[DOWN, 13].crosses
[Word(Across 12: "??X????"),
 Word(Across 14: "??A????"),
 Word(Across 15: "??M????")]

Clues can be attached to words.

>>> xw[ACROSS, 10].clue = "A deer, a female deer"
>>> xw.clues
{(<Across>, 1): '',
 (<Across>, 8): '',
 (<Across>, 9): '',
 (<Across>, 10): 'A deer, a female deer',
 (<Across>, 11): '',
 (<Across>, 12): '',
 (<Across>, 14): '',
 (<Across>, 15): '',
 (<Down>, 1): '',
 (<Down>, 2): '',
 (<Down>, 3): '',
 (<Down>, 4): '',
 (<Down>, 5): '',
 (<Down>, 6): '',
 (<Down>, 7): '',
 (<Down>, 13): ''}

You can also copy grid objects, to support things like custom branching searches.

>>> new_xw = xw.copy()
>>> new_xw[ACROSS, 11] = 'ABC'

Rebuses, cell styling (circles and shading), and rule validation are supported out of the box.

>>> from blacksquare import Rebus
>>> xw[0, 2] = Rebus("HEART")
>>> xw[1, 1].circled = True
>>> xw[2, 2].shaded = True
>>> xw.check()  # verifies connectivity, symmetry, word lengths, and duplicate fills
ValidationResult(is_valid=True, errors=[], warnings=[])
>>> xw.stats()  # returns grid statistics (word counts, open cells, letter frequencies, etc.)

A core feature of blacksquare are the utilities to help find valid fills, powered by a fast heuristic-guided backtracking solver written in Rust.

>>> matches = xw[DOWN, 1].find_matches()
>>> matches[0]
ScoredWord(word='SANDBAG', score=26.863017541323376)
# This returns a new valid Crossword fill, with optional randomness and word list control.
>>> filled = xw.fill(temperature=1, word_list=DEFAULT_WORDLIST.score_filter(0.5))

Custom word lists are supported and can be passed into the Crossword constructor or any of the solving methods. The default word list used is from spread the word(list). (Please note that the word list carries a CC BY-NC-SA license.)

Installation

pip install blacksquare

or if you want to enable pdf export

pip install "blacksquare[pdf]"

Development setup

Blacksquare requires Python 3.10+ and a Rust toolchain.

Clone the repository:

git clone https://github.com/pmaher86/blacksquare.git
cd blacksquare

Install dependencies and compile the Rust extension in editable mode (using uv):
```
uv sync --all-groups --all-extras
uv run maturin develop
```
Run the test suite:
```
uv run pytest
```

Run code formatting, linting, and type checking:

uv run ruff check .
uv run ruff format --check .
uv run ty check src

Build or serve documentation locally:
```
uv run mkdocs serve
```

Download files

Download the file for your platform. If you're not sure which to choose, learn more about installing packages.

Source Distribution

blacksquare-0.10.0.tar.gz (1.8 MB view details)

Uploaded Sep 2, 2026 Source

Built Distributions

If you're not sure about the file name format, learn more about wheel file names.

The dropdown lists show the available interpreters, ABIs, and platforms. Enable javascript to be able to filter the list of wheel files.

blacksquare-0.10.0-cp310-abi3-win_amd64.whl (1.9 MB view details)

Uploaded Sep 2, 2026 CPython 3.10+Windows x86-64

blacksquare-0.10.0-cp310-abi3-manylinux_2_17_x86_64.manylinux2014_x86_64.whl (2.1 MB view details)

Uploaded Sep 2, 2026 CPython 3.10+manylinux: glibc 2.17+ x86-64

blacksquare-0.10.0-cp310-abi3-manylinux_2_17_aarch64.manylinux2014_aarch64.whl (2.1 MB view details)

Uploaded Sep 2, 2026 CPython 3.10+manylinux: glibc 2.17+ ARM64

blacksquare-0.10.0-cp310-abi3-macosx_11_0_arm64.whl (2.0 MB view details)

Uploaded Sep 2, 2026 CPython 3.10+macOS 11.0+ ARM64

blacksquare-0.10.0-cp310-abi3-macosx_10_12_x86_64.whl (2.0 MB view details)

Uploaded Sep 2, 2026 CPython 3.10+macOS 10.12+ x86-64

File details

Details for the file blacksquare-0.10.0.tar.gz.

File metadata

Download URL: blacksquare-0.10.0.tar.gz
Upload date: Sep 2, 2026
Size: 1.8 MB
Tags: Source
Uploaded using Trusted Publishing? Yes
Uploaded via: twine/7.0.0 CPython/3.13.14

File hashes

Hashes for blacksquare-0.10.0.tar.gz
Algorithm	Hash digest
SHA256	`6d51cb2d8850cee8651934b31fb55ad4c9973b13def2e741e06775fc1935a269`
MD5	`4037114e10c038af756574b5782647f5`
BLAKE2b-256	`2da1caaf15c7ea1b6dafcb52cd419c0664e6be1bc78db291d097b08ed3baf9fa`

See more details on using hashes here.

Provenance

The following attestation bundles were made for blacksquare-0.10.0.tar.gz:

Publisher: build-and-deploy.yaml on pmaher86/blacksquare

Attestations: Values shown here reflect the state when the release was signed and may no longer be current.

Statement:
- Statement type: https://in-toto.io/Statement/v1
- Predicate type: https://docs.pypi.org/attestations/publish/v1
- Subject name: blacksquare-0.10.0.tar.gz
- Subject digest: 6d51cb2d8850cee8651934b31fb55ad4c9973b13def2e741e06775fc1935a269
- Sigstore transparency entry: 2682663699
- Sigstore integration time: Sep 2, 2026
Source repository:
- Permalink: pmaher86/blacksquare@58edc87c2dcdc1d98935cd922c8c82d9158ac557
- Branch / Tag: refs/tags/v0.10.0
- Owner: https://github.com/pmaher86
- Access: public
Publication detail:
- Token Issuer: https://token.actions.githubusercontent.com
- Runner Environment: github-hosted
- Publication workflow: build-and-deploy.yaml@58edc87c2dcdc1d98935cd922c8c82d9158ac557
- Trigger Event: push

File details

Details for the file blacksquare-0.10.0-cp310-abi3-win_amd64.whl.

File metadata

Download URL: blacksquare-0.10.0-cp310-abi3-win_amd64.whl
Upload date: Sep 2, 2026
Size: 1.9 MB
Tags: CPython 3.10+, Windows x86-64
Uploaded using Trusted Publishing? Yes
Uploaded via: twine/7.0.0 CPython/3.13.14

File hashes

Hashes for blacksquare-0.10.0-cp310-abi3-win_amd64.whl
Algorithm	Hash digest
SHA256	`fafd3d19c6da655edbcb239f34d1a018dd76ceb482edb33ba94e42e79475cd18`
MD5	`66ddec5b087bddb8624f995036493e12`
BLAKE2b-256	`8e04d214e8e733ec44dc6661e296a27e414de052035bc3078065c393a4a946ac`

See more details on using hashes here.

Provenance

The following attestation bundles were made for blacksquare-0.10.0-cp310-abi3-win_amd64.whl:

Publisher: build-and-deploy.yaml on pmaher86/blacksquare

Attestations: Values shown here reflect the state when the release was signed and may no longer be current.

Statement:
- Statement type: https://in-toto.io/Statement/v1
- Predicate type: https://docs.pypi.org/attestations/publish/v1
- Subject name: blacksquare-0.10.0-cp310-abi3-win_amd64.whl
- Subject digest: fafd3d19c6da655edbcb239f34d1a018dd76ceb482edb33ba94e42e79475cd18
- Sigstore transparency entry: 2682664003
- Sigstore integration time: Sep 2, 2026
Source repository:
- Permalink: pmaher86/blacksquare@58edc87c2dcdc1d98935cd922c8c82d9158ac557
- Branch / Tag: refs/tags/v0.10.0
- Owner: https://github.com/pmaher86
- Access: public
Publication detail:
- Token Issuer: https://token.actions.githubusercontent.com
- Runner Environment: github-hosted
- Publication workflow: build-and-deploy.yaml@58edc87c2dcdc1d98935cd922c8c82d9158ac557
- Trigger Event: push

File details

Details for the file blacksquare-0.10.0-cp310-abi3-manylinux_2_17_x86_64.manylinux2014_x86_64.whl.

File metadata

Download URL: blacksquare-0.10.0-cp310-abi3-manylinux_2_17_x86_64.manylinux2014_x86_64.whl
Upload date: Sep 2, 2026
Size: 2.1 MB
Tags: CPython 3.10+, manylinux: glibc 2.17+ x86-64
Uploaded using Trusted Publishing? Yes
Uploaded via: twine/7.0.0 CPython/3.13.14

File hashes

Hashes for blacksquare-0.10.0-cp310-abi3-manylinux_2_17_x86_64.manylinux2014_x86_64.whl
Algorithm	Hash digest
SHA256	`38578b5fdd3c0054217c733fa3f560ca0a316c5ec01a6a90c7049ff80bf892b4`
MD5	`2d96fa36f2fdede4675e82c62f620484`
BLAKE2b-256	`0c5a01843d132c079aba48150e5c79aec576477f1e37a2bb6e6e37315b697a63`

See more details on using hashes here.

Provenance

The following attestation bundles were made for blacksquare-0.10.0-cp310-abi3-manylinux_2_17_x86_64.manylinux2014_x86_64.whl:

Publisher: build-and-deploy.yaml on pmaher86/blacksquare

Attestations: Values shown here reflect the state when the release was signed and may no longer be current.

Statement:
- Statement type: https://in-toto.io/Statement/v1
- Predicate type: https://docs.pypi.org/attestations/publish/v1
- Subject name: blacksquare-0.10.0-cp310-abi3-manylinux_2_17_x86_64.manylinux2014_x86_64.whl
- Subject digest: 38578b5fdd3c0054217c733fa3f560ca0a316c5ec01a6a90c7049ff80bf892b4
- Sigstore transparency entry: 2682663933
- Sigstore integration time: Sep 2, 2026
Source repository:
- Permalink: pmaher86/blacksquare@58edc87c2dcdc1d98935cd922c8c82d9158ac557
- Branch / Tag: refs/tags/v0.10.0
- Owner: https://github.com/pmaher86
- Access: public
Publication detail:
- Token Issuer: https://token.actions.githubusercontent.com
- Runner Environment: github-hosted
- Publication workflow: build-and-deploy.yaml@58edc87c2dcdc1d98935cd922c8c82d9158ac557
- Trigger Event: push

File details

Details for the file blacksquare-0.10.0-cp310-abi3-manylinux_2_17_aarch64.manylinux2014_aarch64.whl.

File metadata

Download URL: blacksquare-0.10.0-cp310-abi3-manylinux_2_17_aarch64.manylinux2014_aarch64.whl
Upload date: Sep 2, 2026
Size: 2.1 MB
Tags: CPython 3.10+, manylinux: glibc 2.17+ ARM64
Uploaded using Trusted Publishing? Yes
Uploaded via: twine/7.0.0 CPython/3.13.14

File hashes

Hashes for blacksquare-0.10.0-cp310-abi3-manylinux_2_17_aarch64.manylinux2014_aarch64.whl
Algorithm	Hash digest
SHA256	`16ea7a240054e376553ceeecd2d947d3180a89bf9d13ce41ca40fa728972885f`
MD5	`fe1d4b21d4bb55f0ae7030cc32399f71`
BLAKE2b-256	`4d148c30552ed168fb926135a2f501232e69c021ad182097b4e0e44220aabdb6`

See more details on using hashes here.

Provenance

The following attestation bundles were made for blacksquare-0.10.0-cp310-abi3-manylinux_2_17_aarch64.manylinux2014_aarch64.whl:

Publisher: build-and-deploy.yaml on pmaher86/blacksquare

Attestations: Values shown here reflect the state when the release was signed and may no longer be current.

Statement:
- Statement type: https://in-toto.io/Statement/v1
- Predicate type: https://docs.pypi.org/attestations/publish/v1
- Subject name: blacksquare-0.10.0-cp310-abi3-manylinux_2_17_aarch64.manylinux2014_aarch64.whl
- Subject digest: 16ea7a240054e376553ceeecd2d947d3180a89bf9d13ce41ca40fa728972885f
- Sigstore transparency entry: 2682664051
- Sigstore integration time: Sep 2, 2026
Source repository:
- Permalink: pmaher86/blacksquare@58edc87c2dcdc1d98935cd922c8c82d9158ac557
- Branch / Tag: refs/tags/v0.10.0
- Owner: https://github.com/pmaher86
- Access: public
Publication detail:
- Token Issuer: https://token.actions.githubusercontent.com
- Runner Environment: github-hosted
- Publication workflow: build-and-deploy.yaml@58edc87c2dcdc1d98935cd922c8c82d9158ac557
- Trigger Event: push

File details

Details for the file blacksquare-0.10.0-cp310-abi3-macosx_11_0_arm64.whl.

File metadata

Download URL: blacksquare-0.10.0-cp310-abi3-macosx_11_0_arm64.whl
Upload date: Sep 2, 2026
Size: 2.0 MB
Tags: CPython 3.10+, macOS 11.0+ ARM64
Uploaded using Trusted Publishing? Yes
Uploaded via: twine/7.0.0 CPython/3.13.14

File hashes

Hashes for blacksquare-0.10.0-cp310-abi3-macosx_11_0_arm64.whl
Algorithm	Hash digest
SHA256	`f2b617fed99ecc0a34311cace02b10743968bb357a30bfaaa07dc7babbfe8e75`
MD5	`5005d96497b3ebf1ab3ac24438937d07`
BLAKE2b-256	`2f0984e37cc48c03b86be30d611cddfe335b63522a2016f654a90d3ee3a136ea`

See more details on using hashes here.

Provenance

The following attestation bundles were made for blacksquare-0.10.0-cp310-abi3-macosx_11_0_arm64.whl:

Publisher: build-and-deploy.yaml on pmaher86/blacksquare

Attestations: Values shown here reflect the state when the release was signed and may no longer be current.

Statement:
- Statement type: https://in-toto.io/Statement/v1
- Predicate type: https://docs.pypi.org/attestations/publish/v1
- Subject name: blacksquare-0.10.0-cp310-abi3-macosx_11_0_arm64.whl
- Subject digest: f2b617fed99ecc0a34311cace02b10743968bb357a30bfaaa07dc7babbfe8e75
- Sigstore transparency entry: 2682663847
- Sigstore integration time: Sep 2, 2026
Source repository:
- Permalink: pmaher86/blacksquare@58edc87c2dcdc1d98935cd922c8c82d9158ac557
- Branch / Tag: refs/tags/v0.10.0
- Owner: https://github.com/pmaher86
- Access: public
Publication detail:
- Token Issuer: https://token.actions.githubusercontent.com
- Runner Environment: github-hosted
- Publication workflow: build-and-deploy.yaml@58edc87c2dcdc1d98935cd922c8c82d9158ac557
- Trigger Event: push

File details

Details for the file blacksquare-0.10.0-cp310-abi3-macosx_10_12_x86_64.whl.

File metadata

Download URL: blacksquare-0.10.0-cp310-abi3-macosx_10_12_x86_64.whl
Upload date: Sep 2, 2026
Size: 2.0 MB
Tags: CPython 3.10+, macOS 10.12+ x86-64
Uploaded using Trusted Publishing? Yes
Uploaded via: twine/7.0.0 CPython/3.13.14

File hashes

Hashes for blacksquare-0.10.0-cp310-abi3-macosx_10_12_x86_64.whl
Algorithm	Hash digest
SHA256	`102fe51c08dd7d52bc06a1ba23be8a2bd350086674487531dd715b7eaa15ceae`
MD5	`a4b255195f4fee9ef2c0e4582d6322f7`
BLAKE2b-256	`ce560eec2ff0ef33b95efe62ac50ed3516ebc9a2c2f7ced45e28e0f89d68b2cd`

See more details on using hashes here.

Provenance

The following attestation bundles were made for blacksquare-0.10.0-cp310-abi3-macosx_10_12_x86_64.whl:

Publisher: build-and-deploy.yaml on pmaher86/blacksquare

Attestations: Values shown here reflect the state when the release was signed and may no longer be current.

Statement:
- Statement type: https://in-toto.io/Statement/v1
- Predicate type: https://docs.pypi.org/attestations/publish/v1
- Subject name: blacksquare-0.10.0-cp310-abi3-macosx_10_12_x86_64.whl
- Subject digest: 102fe51c08dd7d52bc06a1ba23be8a2bd350086674487531dd715b7eaa15ceae
- Sigstore transparency entry: 2682663789
- Sigstore integration time: Sep 2, 2026
Source repository:
- Permalink: pmaher86/blacksquare@58edc87c2dcdc1d98935cd922c8c82d9158ac557
- Branch / Tag: refs/tags/v0.10.0
- Owner: https://github.com/pmaher86
- Access: public
Publication detail:
- Token Issuer: https://token.actions.githubusercontent.com
- Runner Environment: github-hosted
- Publication workflow: build-and-deploy.yaml@58edc87c2dcdc1d98935cd922c8c82d9158ac557
- Trigger Event: push