Reading ipuz puzzles

The string data contains the puzzle in JSON or JSONP format:

import ipuz

try:
    puzzle = ipuz.read(data)
except ipuz.IPUZException:
    # invalid puzzle

This function provides:

  • Validation of puzzle structure in JSON or JSONP format.

  • Validation of missing mandatory fields.

  • Sanity checks for fields where possible.

The error messages are not intended as API but only for informative purposes. If you read a puzzle from a string and no exception was raised then your code should not need to perform validation to see whether the puzzle is well-formed. This library will check types of values and perform various sanity checks to see whether the JSON conforms to the ipuz specification.

ipuz.IPUZ_VERSIONS

You can use the constant ipuz.IPUZ_VERSIONS to see versions of the ipuz standard that the ipuz library can validate. This is a list containing the accepted integer values X for "http://ipuz.org/vX".

Puzzles with an ipuz version that is not in this list won’t be read by ipuz.read and this will result in an ipuz.IPUZException exception. The reason is that a future version of the standard may have introduced new features and attempting incomplete validation on such puzzles could lead to invalid puzzles being accepted by ipuz.read.

Validation for all puzzles

The ipuz.read function performs validation for fields that are common to all PuzzleKinds and validation for fields that are specific to a PuzzleKind. The function expects a puzzle in JSON or JSONP with either the default ipuz callback function or a differently named callback function.

Note that true, false and null in JSON / JSONP respectively become True, False and None in Python.

The follows checks are performed for fields that apply to all PuzzleKinds:

Field

Mandatory

Validation

version

Yes

Must be the string "http://ipuz.org/vX" where X is an integer of at least one.

kind

Yes

Must be a non-empty list of non-empty strings.

copyright

No

Must be a string.

publisher

No

Must be a string.

publication

No

Must be a string.

url

No

Must be a string.

uniqueid

No

Must be a string.

title

No

Must be a string.

intro

No

Must be a string.

explanation

No

Must be a string.

annotation

No

Must be a string.

author

No

Must be a string.

editor

No

Must be a string.

date

No

Must be a string with a date "mm/dd/yyyy".

notes

No

Must be a string.

difficulty

No

Must be a string.

origin

No

Must be a string.

block

No

Must be a string.

empty

No

Must be a string or integer.

styles

No

Must be a dictionary with StyleSpec values.

Validation for Acrostic puzzles

The following checks are performed for PuzzleKinds belonging to http://ipuz.org/acrostic:

Field

Mandatory

Validation

puzzle

Yes

Must be a list of lists containing LabeledCell values.

solution

No

Must be a list of lists containing CrosswordValue values.

clues

No

Must be a dictionary with Direction keys and lists of Clue values.

Validation for Answer puzzles

The following checks are performed for PuzzleKinds belonging to http://ipuz.org/answer:

Field

Mandatory

Validation

choices

No

Must be a list of strings.

randomize

No

Must be a boolean.

answer

No

Must be a string.

answers

No

Must be a list of strings.

enumeration

No

Must be a string.

enumerations

No

Must be a list of strings.

requiredanswers

No

Must be an integer of at least zero.

misses

No

Must be a dictionary with string keys and string values.

guesses

No

Must be a list of strings.

Validation for Block puzzles

The following checks are performed for PuzzleKinds belonging to http://ipuz.org/block:

Field

Mandatory

Validation

dimensions

Yes

Must be a dictionary containing "width" and "height" keys with integer values of at least one.

slide

No

Must be a boolean.

move

No

Must be a boolean.

rotatable

No

Must be a boolean.

flippable

No

Must be a boolean.

field

No

Must be a list of lists containing StyledCell values.

enter

No

Must be a dictionary with string keys and GroupSpec values.

start

No

Must be a dictionary with string keys and GroupSpec values.

saved

No

Must be a dictionary with string keys and GroupSpec values.

end

No

Must be a dictionary with string keys and GroupSpec values.

exit

No

Must be a dictionary with string keys and GroupSpec values.

Validation for Crossword puzzles

The following checks are performed for PuzzleKinds belonging to http://ipuz.org/crossword:

Field

Mandatory

Validation

dimensions

Yes

Must be a dictionary containing "width" and "height" keys with integer values of at least one.

puzzle

Yes

Must be a list of lists containing LabeledCell values.

saved

No

Must be a list of lists containing CrosswordValue values.

solution

No

Must be a list of lists containing CrosswordValue values.

zones

No

Must be a list of GroupSpec values.

clues

No

Must be a dictionary with Direction keys and lists of Clue values.

showenumerations

No

Must be a boolean.

clueplacement

No

Must be an element from ["before", "after", "blocks", null].

answer

No

Must be a string.

answers

No

Must be a list of strings.

enumeration

No

Must be a string.

enumerations

No

Must be a list of strings.

misses

No

Must be a dictionary with string keys and string values.

Validation for Fill puzzles

The following checks are performed for PuzzleKinds belonging to http://ipuz.org/fill:

Field

Mandatory

Validation

start

No

Must be a list of lists containing CrosswordValue values.

solution

No

Must be a list of lists containing CrosswordValue values.

answer

No

Must be a string.

answers

No

Must be a list of strings.

misses

No

Must be a dictionary with string keys and string values.

Validation for Sudoku puzzles

The following checks are performed for PuzzleKinds belonging to http://ipuz.org/sudoku:

Field

Mandatory

Validation

charset

No

Must be a string.

displaycharset

No

Must be a boolean.

boxes

No

Must be a boolean.

showoperators

No

Must be a boolean.

cageborder

No

Must be an element from ["thick", "dashed"].

puzzle

Yes

Must be a list of lists containing SudokuGiven values.

saved

No

Must be a list of lists containing SudokuGuess values.

solution

No

Must be a list of lists containing SudokuValue values.

zones

No

Must be a list of GroupSpec values.

cages

No

Must be a list of CalcSpec values.

Validation for WordSearch puzzles

The following checks are performed for PuzzleKinds belonging to http://ipuz.org/wordsearch:

Field

Mandatory

Validation

dimensions

Yes

Must be a dictionary containing "width" and "height" keys with integer values of at least one.

puzzle

No

Must be a list of lists containing CrosswordValue values.

solution

No

Must be a string, a list of strings or a dictionary with string keys and GroupSpec values.

dictionary

No

Must be a string or the boolean value false.

saved

No

Must be a list of strings.

showanswers

No

Must be an element from ["during", "after", null].

time

No

Must be an integer of at least zero.

points

No

Must be an element from ["linear", "log", null].

zigzag

No

Must be a boolean.

retrace

No

Must be a boolean.

useall

No

Must be a boolean.

misses

No

Must be a dictionary with string keys and string values.

Parameters

The ipuz.read function supports the following keyword parameters to configure what puzzles can be loaded:

  • puzzlekinds

    Specifies the "kind" values that your application supports. This means ipuz.read only accepts puzzles where all "kind" values are in your list. For example, if your application only loads crossword puzzles you can use puzzlekinds=["http://ipuz.org/crossword#1"]. By default ipuz.read accepts all official PuzzleKinds in the ipuz specification.

    Note that this is a list of exact strings so if your application supports both version one and two of the Crossword PuzzleKind then you must specify puzzlekinds=["http://ipuz.org/crossword#1", "http://ipuz.org/crossword#2"].

Extensions

For extensions to the ipuz specification the following validation is performed:

Field

Mandatory

Validation

volatile

No

Must be a dictionary with string keys and string values.

It is the application’s responsibility to ensure that the volatility of the fields is handled properly.