Skip to main content

Python library for handling crossword puzzles

Project description

Python library for handling crossword puzzles. This library provides a canonical data structure that can be used to represent crosswords in your application. It provides a Pythonic way to perform common operations on the grid, the words and the clues of the puzzle.

The library handles reading and writing to .ipuz files.


You can install using pip:

$ pip install crossword

Creating and modifying crosswords

You can create a crossword:

from crossword import Crossword

puzzle = Crossword(15, 15)

You can iterate over rows and cells:

for row in puzzle:
    for cell in row:

You also iterate using ‘cells’ (left-to-right, top-to-bottom):

for x, y in puzzle.cells:
    print(puzzle[x, y])

You can store a string as cell value but you can also specify attributes to store multiple values (such as cell content, styling and other cell propeties):

puzzle[x, y] = "A"

puzzle[x, y].puzzle = " "
puzzle[x, y].solution = "A"
puzzle[x, y].style = {'background-color': 'red'}

You can access a metadata attribute:

creator = puzzle.meta.creator

You can iterate over metadata:

for key, value in puzzle.meta():
    print(key, value)

You can set a clue for an entry:

puzzle.clues.across[1] = "This is a clue"
puzzle.clues.down[2] = "This is a clue"

You can iterate over all clues (first Across, then Down):

for direction, number, clue in puzzle.clues.all():
    print(direction, number, clue)

You can iterate over clues in a particular direction:

for number, clue in puzzle.clues.across():
    print(number, clue)
for number, clue in puzzle.clues.down():
    print(number, clue)

By default these functions iterate over the clues by numerical order of the specified clue numbers. If you wish to iterate over the clues in the order that they were inserted you can specify sort=None:


You can also specify a function yourself that will be used for sorting:

puzzle.clues.all(sort=lambda entry: ...)

You can use the following attributes as dictionaries (e.g., for conversion to JSON):

puzzle.content (the cells, clues and metadata in one dictionary)

You can use the following constants for values that represent block cells and empty cells:


A value of None may indicate that the default value is used (e.g., “#” for blocks in .ipuz puzzles).

Reading and writing crosswords

You can read a crossword from an .ipuz file using:

with open('puzzle.ipuz') as puzzle_file:
    ipuz_dict =  # may raise ipuz.IPUZException

puzzle = crossword.from_ipuz(ipuz_dict)

This requires the “ipuz” package to be installed:

You can write a crossword to an .ipuz file using:

ipuz_dict = crossword.to_ipuz(puzzle)

with open('puzzle.ipuz', 'w') as puzzle_file:

Project details

Release history Release notifications

History Node


History Node


This version
History Node


Download files

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

Filename, size & hash SHA256 hash help File type Python version Upload date
crossword-0.1.tar.gz (4.5 kB) Copy SHA256 hash SHA256 Source None Aug 17, 2014

Supported by

Elastic Elastic Search Pingdom Pingdom Monitoring Google Google BigQuery Sentry Sentry Error logging CloudAMQP CloudAMQP RabbitMQ AWS AWS Cloud computing Fastly Fastly CDN DigiCert DigiCert EV certificate StatusPage StatusPage Status page