pycrossword
0.2
Pure-Python implementation of a crossword puzzle generator and editor
|
Core crossword implementation - a grid of characters + internal Word objects. More...
Public Member Functions | |
def | __init__ (self, data, data_type='grid', info=CWInfo(), on_reset=None, on_clear=None, on_change=None, on_clear_word=None, on_putchar=None) |
Constructor initializes the words and grid from the given grid data. More... | |
def | initialize (self, data, data_type='grid') |
Initializes the internal char grid and words collection from given data. More... | |
def | validate (self, grid) |
Checks if the grid is appropriate. More... | |
def | reset (self, grid=None, update_internal_strings=False) |
Reconstructs the internal grid from the given grid data. More... | |
def | from_words (self, words, update_internal_strings=False) |
Constructs the internal grid, dimensions and words from the given collection of Word objects. More... | |
def | grid_from_file (self, gridfile) |
Util function that reads a text file into a list of strings suitable as internal grid data. More... | |
def | from_file (self, filename, file_format=None) |
Initializes grid data from a crossword file, text file, or JSON-formatter Word collection dump. More... | |
def | to_file (self, filename, file_format=None) |
Exports the crossword grid to a file. More... | |
def | update_word_strings (self) |
Updates the internal strings for each word in grid. More... | |
def | is_complete (self) |
Checks if all the words are completed (have no blanks left). More... | |
def | remove_row (self, row) |
Removes the given row from grid. More... | |
def | remove_column (self, col) |
Removes the given column from grid. More... | |
def | add_row (self, index=-1, char=BLANK) |
Inserts a new row after the one given by index . More... | |
def | add_column (self, index=-1, char=BLANK) |
Inserts a new column after the one given by 'index'. More... | |
def | reflect_bottom (self, mirror=True, reverse=True, border='') |
Duplicates the current grid by reflecting its cells downwards. More... | |
def | reflect_top (self, mirror=True, reverse=True, border='') |
Duplicates the current grid by reflecting its cells upwards. More... | |
def | reflect_right (self, mirror=True, reverse=True, border='') |
Duplicates the current grid by reflecting its cells to the right. More... | |
def | reflect_left (self, mirror=True, reverse=True, border='') |
Duplicates the current grid by reflecting its cells to the left. More... | |
def | reflect (self, direction='d', mirror=True, reverse=True, border='') |
Duplicates the current grid by reflecting its cells in a given direction. More... | |
def | intersects_of (self, word, word_coord_tuples=True) |
Finds all words intersecting the given word. More... | |
def | find_incomplete (self, method='most-complete', exclude=None) |
Retrieves a next incomplete word (fully or partially blank). More... | |
def | count_incomplete (self) |
Counts incomplete words (those containing at least one crossword::BLANK). More... | |
def | get_word_str (self, w) |
Gets the text of a Word object in the grid. More... | |
def | is_word_complete (self, w) |
Checks if a word is complete (has no blanks). More... | |
def | is_word_blank (self, w) |
Checks if a word is blank (consists entirely of crossword::BLANK characters). More... | |
def | find (self, word) |
Finds a Word object in the Wordgrid::words collection. More... | |
def | find_by_coord (self, coord, start_coord=True) |
Retrieves words intersecting the given coordinate. More... | |
def | find_by_coord_dir (self, coord, direction) |
Gets a word by its start coordinate and direction. More... | |
def | find_by_str (self, str_word) |
Gets a word by its text representation. More... | |
def | find_by_num_dir (self, num, direction) |
Gets a word by its sequential number and direction. More... | |
def | find_by_clue (self, clue) |
Gets a word by its clue text. More... | |
def | get_char (self, coord) |
Gets the text character stored in the given grid coordinate. More... | |
def | put_char (self, coord, char) |
Puts a character into a given coordinate (replacing the existing one). More... | |
def | clear (self) |
Clears all the words in the collection. More... | |
def | change_word (self, word, str new_word) |
Replaces the text representation of a given word. More... | |
def | clear_word (self, word, force_clear=False) |
Clears the given word making its characters blank. More... | |
def | sort (self) |
Sorts the words collection by the word coordinates. More... | |
def | print_word (self, w) |
Gets a human-readable representation of a word. More... | |
def | print_words (self) |
Serializes (converts) the grid into a single human-readable string. More... | |
def | print_clues (self) |
Serializes (converts) all clues into a single human-readable string. More... | |
def | word_list (self, strings=True) |
Returns the collection (list ) of all words in grid. More... | |
def | tostr (self) |
Concatenates Wordgrid::grid into a single newline-delimited string. More... | |
def | update_stats (self) |
Updates Wordgrid::stats dict with current handy statistics. More... | |
def | save (self) |
Saves all words to Wordgrid::old_words to be able to restore() later. More... | |
def | restore (self) |
Restores words from Wordgrid::old_words written by save(). More... | |
def | __contains__ (self, word) |
The in operator overload: checks if words contain a given word. More... | |
def | __bool__ (self) |
Convenience for is_complete(). More... | |
def | __len__ (self) |
Python len() overload: returns number of words in grid. More... | |
def | __str__ (self) |
Python str() convertion overload: represents a pretty output of the grid. More... | |
Public Attributes | |
info | |
CWInfo crossword meta info, such as title, author, etc. More... | |
on_reset | |
callback function triggered when the grid is reset via reset() More... | |
on_clear | |
callback function triggered when the grid is cleared via clear() More... | |
on_change | |
callback function triggered when a word is changed via change_word() More... | |
on_clear_word | |
callback function triggered when a word is cleared via clear_word() More... | |
on_putchar | |
callback function triggered when a charater is set in the grid via put_char() More... | |
old_words | |
backup of Wordgrid::words used in save() and restore() More... | |
words | |
internal words list (list of Word objects) More... | |
grid | |
internal 2-dimensional character grid, e.g. More... | |
width | |
number of columns in grid More... | |
height | |
number of rows in grid More... | |
stats | |
stats dictionary - various handy stats like grid dimensions, word count etc. More... | |
Private Member Functions | |
def | _parse_ipuz (self, filename) |
Util function to parse IPUZ files. More... | |
def | _save_ipuz (self, filename, ipuz_version='2', ipuz_kind='1') |
Util function to save the grid and info to an IPUZ file. More... | |
def | _parse_xpf (self, filename) |
Util function to parse XPF files. More... | |
def | _save_xpf (self, filename, xpf_version='1.0') |
Util function to save the grid and info to an XPF file. More... | |
def | _strip_html (self, text) |
Util function: converts HTML to plain text. More... | |
def | _validate_char (self, char) |
Validates characters to use in the crossword grid. More... | |
def | _validate_coord (self, coord) |
Checks if the given coordinate lies within the grid dimensions. More... | |
def | _cell_count (self, condition=None) |
Counts grid cells that satisfy a given condition. More... | |
def | _word_count (self, condition=None) |
Counts words that satisfy a given condition. More... | |
def | _word_lengths (self) |
Returns an array of word lengths. More... | |
Core crossword implementation - a grid of characters + internal Word objects.
This class provides most of the methods required to operate with crosswords on the low level, such as adding/deleting words, file I/O, replacing characters, checking word completeness, counting grid stats and so on. Low-level methods work on the internal character grid, i.e. with individual characters. Higher-level methods work with Word objects (i.e. words). The class implements a 2-way correspondence between characters and words.
def pycross.crossword.Wordgrid.__init__ | ( | self, | |
data, | |||
data_type = 'grid' , |
|||
info = CWInfo() , |
|||
on_reset = None , |
|||
on_clear = None , |
|||
on_change = None , |
|||
on_clear_word = None , |
|||
on_putchar = None |
|||
) |
Constructor initializes the words and grid from the given grid data.
data | list | str the input data to initialize the grid from; can be any of:
|
data_type | str hint used by the program to process the 'data' argument, can be any of:
|
info | CWInfo crossword meta information, default = CWInfo default constructor |
on_reset | callable callback function triggered when the grid is reset via reset(). Callback parameters are:
|
on_clear | callable callback function triggered when the grid is cleared via clear() Callback parameters are:
|
on_change | callable callback function triggered when a word is changed via change_word() Callback parameters are:
|
on_clear_word | callable callback function triggered when a word is cleared via clear_word() Callback parameters are:
|
on_putchar | callable callback function triggered when a charater is set in the grid via put_char() Callback parameters are:
|
crossword::CWError | wrong 'data_type' value |
def pycross.crossword.Wordgrid.__bool__ | ( | self | ) |
Convenience for is_complete().
bool
True
if grid is complete, False
otherwise def pycross.crossword.Wordgrid.__contains__ | ( | self, | |
word | |||
) |
The in
operator overload: checks if words contain a given word.
bool
True
if found, False
otherwise crossword::CWError | word argument is incorrect |
def pycross.crossword.Wordgrid.__len__ | ( | self | ) |
Python len()
overload: returns number of words in grid.
int
number of words in grid def pycross.crossword.Wordgrid.__str__ | ( | self | ) |
Python str()
convertion overload: represents a pretty output of the grid.
str
grid as tabular-formatted text
|
private |
Counts grid cells that satisfy a given condition.
condition | callable callback function - the condition to satisfy. The callback's arguments are (in the sequential order):
|
int
number of cells that meet the given condition
|
private |
Util function to parse IPUZ files.
Resets Wordgrid::grid and Wordgrid::info from the file data.
filename | str path to the source file (*.ipuz) |
|
private |
Util function to parse XPF files.
Resets Wordgrid::grid and Wordgrid::info from the file data.
filename | str path to the source file (*.xpf) |
|
private |
Util function to save the grid and info to an IPUZ file.
Exports data from Wordgrid::grid and Wordgrid::info to the file. Since IPUZ files are JSON-formatted, json.dump() is used for exporting.
filename | str path to the source file (*.ipuz) |
ipuz_version | str IPUZ API version (=2) |
ipuz_kind | str IPUZ puzzle kind (=crossword) |
|
private |
Util function to save the grid and info to an XPF file.
Exports data from Wordgrid::grid and Wordgrid::info to the file. Since XPF files are XML-formatted, ElementTree (DOM) is used for exporting.
filename | str path to the source file (*.xpf) |
xpf_version | str XPF API version (=1.0) |
|
private |
Util function: converts HTML to plain text.
text | str HTML-formatted text |
str
plain text
|
private |
Validates characters to use in the crossword grid.
Only [a-z] (in any language, not ony ASCII!), crossword::BLANK, crossword::FILLER, and crossword::FILLER2 characters are allowed.
char | str character to validate |
crossword::CWError | invalid character |
|
private |
Checks if the given coordinate lies within the grid dimensions.
coord | 2-tuple coordinate to validate |
crossword::CWError | coordinate out of range |
|
private |
Counts words that satisfy a given condition.
condition | callable callback function - the condition to satisfy. The callback takes a single argument - a Word object and returns True if the condition is satisfied and False otherwise. If 'condition' is None , all words will be counted. |
int
number of words that meet the given condition
|
private |
Returns an array of word lengths.
list
of int
array of word lengths def pycross.crossword.Wordgrid.add_column | ( | self, | |
index = -1 , |
|||
char = BLANK |
|||
) |
Inserts a new column after the one given by 'index'.
If index == -1
, appends a column after the last one.
index | int index of column after which a new one will be inserted |
char | str fill character for new column (default = crossword::BLANK) |
def pycross.crossword.Wordgrid.add_row | ( | self, | |
index = -1 , |
|||
char = BLANK |
|||
) |
Inserts a new row after the one given by index
.
If index == -1
, appends a row after the last one.
index | int index of row after which a new one will be inserted |
char | str fill character for new row (default = crossword::BLANK) |
def pycross.crossword.Wordgrid.change_word | ( | self, | |
word, | |||
str | new_word | ||
) |
Replaces the text representation of a given word.
The Wordgrid::on_change callback is called after the replacement.
word | Word the Word object to replace the text for |
new_word | str the new text for the word, e.g. "father" |
crossword::CWError | word not found in grid or new text has incorrect length (different from the given word's length) |
def pycross.crossword.Wordgrid.clear | ( | self | ) |
Clears all the words in the collection.
This method effectively puts crossword::BLANK into all non-blocked cells of the grid. The internal text representations of each Word object are not updated - call update_word_strings() after this operation if required. The Wordgrid::on_clear callback is called after clearing.
def pycross.crossword.Wordgrid.clear_word | ( | self, | |
word, | |||
force_clear = False |
|||
) |
Clears the given word making its characters blank.
word | Word the Word object to clear |
force_clear | bool if True , ALL the characters in the word will be replaced by crossword::BLANK, regardless of intersecting words, if any. Otherwise (if False, which is the default), only the free characters will be cleared (that is, those not intersecting with other words). The Wordgrid::on_clear_word callback is called after clearing. |
def pycross.crossword.Wordgrid.count_incomplete | ( | self | ) |
Counts incomplete words (those containing at least one crossword::BLANK).
int
number of incomplete words def pycross.crossword.Wordgrid.find | ( | self, | |
word | |||
) |
def pycross.crossword.Wordgrid.find_by_clue | ( | self, | |
clue | |||
) |
Gets a word by its clue text.
clue | str the clue text to search for, e.g. "US largest state" |
def pycross.crossword.Wordgrid.find_by_coord | ( | self, | |
coord, | |||
start_coord = True |
|||
) |
Retrieves words intersecting the given coordinate.
The method retrieves at most 2 words (across and down) for a given coordinate in the grid.
coord | 2-tuple the (x, y) coordinate in the grid to find words for |
start_coord | bool if True (default), only those words that start in that coordinate will be returned; otherwise, all intersecting words are returned |
def pycross.crossword.Wordgrid.find_by_coord_dir | ( | self, | |
coord, | |||
direction | |||
) |
def pycross.crossword.Wordgrid.find_by_num_dir | ( | self, | |
num, | |||
direction | |||
) |
def pycross.crossword.Wordgrid.find_by_str | ( | self, | |
str_word | |||
) |
Gets a word by its text representation.
str_word | str the text to search for, e.g. "father" |
def pycross.crossword.Wordgrid.find_incomplete | ( | self, | |
method = 'most-complete' , |
|||
exclude = None |
|||
) |
Retrieves a next incomplete word (fully or partially blank).
method | str governs the search algorithm; it can be one of:
|
exclude | callable allows excluding words from search. It accepts a single argument - a Word object, and returns True to exclude it and False otherwise |
def pycross.crossword.Wordgrid.from_file | ( | self, | |
filename, | |||
file_format = None |
|||
) |
Initializes grid data from a crossword file, text file, or JSON-formatter Word collection dump.
filename | str path to the source file The file type can be any of:
|
file_format | str hint to tell the program the file format (must be 'xpf', 'ipuz', 'json' or None ). If None , the file type will be guessed from the file extension. |
def pycross.crossword.Wordgrid.from_words | ( | self, | |
words, | |||
update_internal_strings = False |
|||
) |
Constructs the internal grid, dimensions and words from the given collection of Word objects.
This is essentially the reverse of reset(), which constructs words from a given grid structure.
words | iterable collection of source Word objects used to populate the grid |
update_internal_strings | bool tells the function to update each Word object's string representation |
crossword::CWError | None 'words' argument is not initialized or inappropriate |
def pycross.crossword.Wordgrid.get_char | ( | self, | |
coord | |||
) |
Gets the text character stored in the given grid coordinate.
coord | 2-tuple the grid coordinate |
str
the single character contained in that coordinate crossword::CWError | coordinate out of range |
def pycross.crossword.Wordgrid.get_word_str | ( | self, | |
w | |||
) |
Gets the text of a Word object in the grid.
Since the internal structure of Wordgrid is a matrix of characters rather than an array of words, word strings (text representations) are not available at runtime and must be requested with this method.
str
the text representation of the word (e.g. "father") def pycross.crossword.Wordgrid.grid_from_file | ( | self, | |
gridfile | |||
) |
Util function that reads a text file into a list of strings suitable as internal grid data.
gridfile | str path to the source text file |
list
of str
grid rows as a list of concatenated strings def pycross.crossword.Wordgrid.initialize | ( | self, | |
data, | |||
data_type = 'grid' |
|||
) |
Initializes the internal char grid and words collection from given data.
crossword::CWError | wrong 'data_type' value |
def pycross.crossword.Wordgrid.intersects_of | ( | self, | |
word, | |||
word_coord_tuples = True |
|||
) |
Finds all words intersecting the given word.
def pycross.crossword.Wordgrid.is_complete | ( | self | ) |
Checks if all the words are completed (have no blanks left).
bool
True
if grid contains no blanks, False
otherwise def pycross.crossword.Wordgrid.is_word_blank | ( | self, | |
w | |||
) |
Checks if a word is blank (consists entirely of crossword::BLANK characters).
bool
True
if the word has no characters other than crossword::BLANK, False
otherwise def pycross.crossword.Wordgrid.is_word_complete | ( | self, | |
w | |||
) |
Checks if a word is complete (has no blanks).
bool
True
if the word has no crossword::BLANK characters, False
otherwise def pycross.crossword.Wordgrid.print_clues | ( | self | ) |
Serializes (converts) all clues into a single human-readable string.
str
the text representation of the clues in the format: [word_number] word_direction clue text [word_number] word_direction clue text ...
def pycross.crossword.Wordgrid.print_word | ( | self, | |
w | |||
) |
Gets a human-readable representation of a word.
str
a string formatted like so: '(coord_x, coord_y) dir word_text' crossword::CWError | word is not found in grid |
def pycross.crossword.Wordgrid.print_words | ( | self | ) |
Serializes (converts) the grid into a single human-readable string.
str
the text representation of the crossword grid in a tabular format, e.g. Num Coord Value ---------------------------- ACROSS: ---------------------------- 1 (0, 0) father 5 (0, 10) quit 9 (0, 15) storm ---------------------------- DOWN: ---------------------------- ...
def pycross.crossword.Wordgrid.put_char | ( | self, | |
coord, | |||
char | |||
) |
Puts a character into a given coordinate (replacing the existing one).
The Wordgrid::on_putchar callback is called after putting the character.
coord | 2-tuple the grid coordinate to write to |
char | str the character to put |
crossword::CWError | invalid character |
def pycross.crossword.Wordgrid.reflect | ( | self, | |
direction = 'd' , |
|||
mirror = True , |
|||
reverse = True , |
|||
border = '' |
|||
) |
Duplicates the current grid by reflecting its cells in a given direction.
direction | str the direction to duplicate / reflect the current grid:
|
mirror | bool if True (default), reflection will be mirror-like (symmetrical against bottom line). |
reverse | bool if True (default), reflection will be inverted from left to right. |
border | str fill pattern for a border (row or column) between the existing and reflected blocks of cells. |
If both mirror
and reflect
are False
, a simle copy-paste duplication will be performed. If border
is an empty string (default), no extra row will be put between the existing and the new (reflected) cells. Otherwise, border
is a 2-character pattern for the extra row, e.g. '* ' means sequence of crossword::FILLER and crossword::BLANK, '**' means all filled, etc.
def pycross.crossword.Wordgrid.reflect_bottom | ( | self, | |
mirror = True , |
|||
reverse = True , |
|||
border = '' |
|||
) |
Duplicates the current grid by reflecting its cells downwards.
def pycross.crossword.Wordgrid.reflect_left | ( | self, | |
mirror = True , |
|||
reverse = True , |
|||
border = '' |
|||
) |
Duplicates the current grid by reflecting its cells to the left.
def pycross.crossword.Wordgrid.reflect_right | ( | self, | |
mirror = True , |
|||
reverse = True , |
|||
border = '' |
|||
) |
Duplicates the current grid by reflecting its cells to the right.
def pycross.crossword.Wordgrid.reflect_top | ( | self, | |
mirror = True , |
|||
reverse = True , |
|||
border = '' |
|||
) |
Duplicates the current grid by reflecting its cells upwards.
def pycross.crossword.Wordgrid.remove_column | ( | self, | |
col | |||
) |
Removes the given column from grid.
col | int index of column to delete |
def pycross.crossword.Wordgrid.remove_row | ( | self, | |
row | |||
) |
Removes the given row from grid.
row | int index of row to delete |
def pycross.crossword.Wordgrid.reset | ( | self, | |
grid = None , |
|||
update_internal_strings = False |
|||
) |
Reconstructs the internal grid from the given grid data.
The following class members are fully re-initialized:
None
grid | list | str crossword grid – see 'data' argument in init() If None , Wordgrid::grid will be used, if initialized (otherwise, an exception will be raised) |
update_internal_strings | bool tells the function to update each Word object's string representation |
crossword::CWError | empty / null 'grid' argument and Wordgrid::grid not initialized |
def pycross.crossword.Wordgrid.restore | ( | self | ) |
Restores words from Wordgrid::old_words written by save().
def pycross.crossword.Wordgrid.save | ( | self | ) |
Saves all words to Wordgrid::old_words to be able to restore() later.
def pycross.crossword.Wordgrid.sort | ( | self | ) |
Sorts the words collection by the word coordinates.
The sorting is performed in the assending order: first on rows, then on columns. This corresponds to the typical crossword word numeration.
def pycross.crossword.Wordgrid.to_file | ( | self, | |
filename, | |||
file_format = None |
|||
) |
Exports the crossword grid to a file.
def pycross.crossword.Wordgrid.tostr | ( | self | ) |
Concatenates Wordgrid::grid into a single newline-delimited string.
str
the concatenated grid string, e.g. father*__it*__ _*_*_*act_v_ty ...
def pycross.crossword.Wordgrid.update_stats | ( | self | ) |
Updates Wordgrid::stats dict with current handy statistics.
def pycross.crossword.Wordgrid.update_word_strings | ( | self | ) |
Updates the internal strings for each word in grid.
def pycross.crossword.Wordgrid.validate | ( | self, | |
grid | |||
) |
Checks if the grid is appropriate.
The grid must:
str
or list
typegrid | list | str crossword grid: either a newline-delimited single string or a 2-dimension list of individual characters (of type str ) |
crossword::CWError | incorrectly formatted grid |
def pycross.crossword.Wordgrid.word_list | ( | self, | |
strings = True |
|||
) |
pycross.crossword.Wordgrid.grid |
internal 2-dimensional character grid, e.g.
[['f', 'a', 't', 'h', 'e', 'r', '*', '_', 'o', 'm'], [...]]
pycross.crossword.Wordgrid.height |
number of rows in grid
pycross.crossword.Wordgrid.info |
CWInfo
crossword meta info, such as title, author, etc.
pycross.crossword.Wordgrid.old_words |
backup of Wordgrid::words used in save() and restore()
pycross.crossword.Wordgrid.on_change |
callback function triggered when a word is changed via change_word()
pycross.crossword.Wordgrid.on_clear |
callback function triggered when the grid is cleared via clear()
pycross.crossword.Wordgrid.on_clear_word |
callback function triggered when a word is cleared via clear_word()
pycross.crossword.Wordgrid.on_putchar |
callback function triggered when a charater is set in the grid via put_char()
pycross.crossword.Wordgrid.on_reset |
callback function triggered when the grid is reset via reset()
pycross.crossword.Wordgrid.stats |
stats dictionary - various handy stats like grid dimensions, word count etc.
pycross.crossword.Wordgrid.width |
number of columns in grid
pycross.crossword.Wordgrid.words |
internal words list (list
of Word objects)