Make awesome Word Search puzzles
Project description
Word-Search-Generator
Word-Search-Generator is a Python module for generating fun Word Search Puzzles.
Like most of my programming endeavors, Word-Search-Generator was born out of necessity. I needed an easy way to generate a bunch of word search puzzles for kid's food menus at the day job.
🤦♂️ Does the world need this? Probably not.
⏰ Did I spend way too much time on it? Yep!
✅ Does it come in handy? Heck yeah!
👍 Did I have fun making it? Absofreakinglutly!
Installation
Install Word-Search-Generator with pip
:
$ pip install word-search-generator
Usage
Just import the WordSearch class from the package, supply it with a list of words and you're set. 🧩
from word_search_generator import WordSearch
puzzle = WordSearch("dog, cat, pig, horse, donkey, turtle, goat, sheep")
👀 Wanna see it?
>>> puzzle.show() # or print(puzzle)
-----------------------
WORD SEARCH
-----------------------
Z T G H X Z D B A G S E
X U S O M W O Z E B H L
B R Y R P G N T W F E R
J T G S K X K R V G E T
D L N E T D E F Q O P U
N E V O L C Y X V L Z L
C O A P R Q S Q B S W V
A T G E F C A T N H J D
E Z O J X Z U B D V B R
S Q A M G P I G Q C G Y
X V T R J E F W I E R N
D O G Y H R S B V L S O
Find these words: CAT, DOG, DONKEY, GOAT, HORSE, PIG, SHEEP, TURTLE
* Words can go S, and E.
Answer Key: CAT E @ (6, 8), DOG E @ (1, 12), DONKEY S @ (7, 1), GOAT S @ (3, 8), HORSE S @ (4, 1), PIG E @ (6, 10), SHEEP S @ (11, 1), TURTLE S @ (2, 1)
ℹ️ The answer key uses 1-based indexing and a familiar (x, y) coordinate system. Directions are cardinal from first letter to last. * Please note that all key values inside of the api are 0-based.
🤷♂️ Can't find all of the words? You can view the answer key or highlight the hidden words in the output with puzzle.show(solution=True)
🔦.
>>> puzzle.key
{'SHEEP': {'start': Position(row=0, column=10), 'direction': 'S', 'secret': False},
'DONKEY': {'start': Position(row=0, column=6), 'direction': 'S', 'secret': False},
'PIG': {'start': Position(row=9, column=5), 'direction': 'E', 'secret': False},
'CAT': {'start': Position(row=7, column=5), 'direction': 'E', 'secret': False},
'GOAT': {'start': Position(row=7, column=2), 'direction': 'S', 'secret': False},
'DOG': {'start': Position(row=11, column=0), 'direction': 'E', 'secret': False},
'TURTLE': {'start': Position(row=0, column=1), 'direction': 'S', 'secret': False},
'HORSE': {'start': Position(row=0, column=3), 'direction': 'S', 'secret': False}}
🍰 Too easy? Up the difficulty level.
>>> puzzle.level = 3
>>> puzzle.show()
-----------------------
WORD SEARCH
-----------------------
W H Q Z M N M B P L F W
K Y K P D O L V A I N I
R X V E I C J C Z L M A
E Z H J O G F B J I G V
L F D Y E K N O D Y X F
E T I U Z O M T A C I E
D Q G M L B P E E H S X
I X W O H O R S E N C D
C M U R A K M Y C P I N
W P Y I C T C X O Y A K
Q D O G R N V E P F V C
Z F A C B E L T R U T A
Find these words: CAT, DOG, DONKEY, GOAT, HORSE, PIG, SHEEP, TURTLE
* Words can go N, SW, NW, SE, E, NE, W, and S.
Answer Key: CAT W @ (10, 6), DOG E @ (2, 11), DONKEY W @ (9, 5), GOAT SE @ (3, 7), HORSE E @ (5, 8), PIG SE @ (4, 2), SHEEP W @ (11, 7), TURTLE W @ (11, 12)
ℹ️ You'll find preset numeric levels listed in config.py, each with specific cardinal directions that words can travel.
You can also specify custom cardinal directions for your puzzle (e.g. N, NE, E, SE, S, SW, W, NW).
>>> puzzle.directions = "NW,SW"
>>> puzzle.show()
-----------------------
WORD SEARCH
-----------------------
O I Y O T F J F M R L R
K W R D C W E N G S H V
N P S W M K I S U M D P
E F A L O D T Z R O H D
X H Q P G U B U G O O B
J R C E R A S L H N H P
Q Y I T V H Z Y K Q I C
R W L T E P T E S G X F
A E A E A Q Y A R A L O
J H P Y C O P W C Y B D
A V I E L R G X U J G A
W C X H D I N V K L W Y
Find these words: CAT, DOG, DONKEY, GOAT, HORSE, PIG, SHEEP, TURTLE
* Words can go SW, and NW.
Answer Key: CAT NW @ (9, 10), DOG SW @ (11, 3), DONKEY SW @ (12, 4), GOAT NW @ (7, 11), HORSE NW @ (11, 6), PIG SW @ (12, 6), SHEEP SW @ (7, 6), TURTLE SW @ (7, 4)
😱 Still too easy? Go expert mode. Works in the CLI too!
> from word_search_generator import WordSearch
> from word_search_generator.utils import get_random_words
> puzzle = WordSearch(secret_words=get_random_words(10), level=3,)
ℹ️ You'll notice the get_random_words()
function from the utils module used above. It generates {n} number of random words from a list of approximately 1000 American English dictionary words.
😓 Too hard? Go the easy route with puzzle.level = 1
or puzzle.directions = "E"
.
Settings
Word-Search-Generator offers a few options for puzzle generation.
>>> help(WordSearch.__init__)
Help on function __init__ in module word_search_generator:
__init__(self, words: Optional[str] = None, level: Union[int, str, NoneType] = None, size: Optional[int] = None, secret_words: Optional[str] = None, secret_level: Union[int, str, NoneType] = None)
Initialize a Word Search puzzle.
Args:
words (Optional[str], optional): A string of words separated by spaces,
commas, or new lines. Will be trimmed if more. Defaults to None.
level (Optional[int | str], optional): Difficulty level or potential
word directions. Defaults to 1.
size (Optional[int], optional): Puzzle size. Defaults to None.
secret_words (Optional[str], optional): A string of words separated by
spaces, commas, or new lines. Words will be 'secret' meaning they
will not be included in the word list. Defaults to None.
secret_level (Optional[int | str], optional): Difficulty level or
potential word directions for 'secret' words. Defaults to None.
words = "dog, cat, pig, horse, donkey, turtle, goat, sheep"
puzzle = WordSearch(words, level=3, size=25)
⚠️ Anytime puzzle settings are adjusted, an entirely new puzzle will be generated!
Words
A word search puzzle wouldn't be much without words... Puzzle words can be provided at time of creation or added after the fact. Words can be separated by spaces, commas, or new lines and Word-Search-Generator will sort them out for you.
puzzle = WordSearch("some random words to hide") # separated by a space
Editing Current Puzzle Words
🤦♂️ Leave out a word?
puzzle.add_words("new, words, to, add")
❌ Need to remove a word?
puzzle.remove_words("words, to, delete")
♻️ Replace all of the words?
puzzle.replace_words("replace, current, words, with, new, words")
⚠️ When words are added, removed, or replaced, an entirely new puzzle will be generated!
Level
Word-Search-Generator offers some preset difficulty levels. Some levels only allow for words to be placed left-to-right and others allow for right-to-left. You can find all of the preset numeric levels listed in config.py.
puzzle.level = 2
⚠️ Preset levels were the introduced in the first implementation of Word-Search-Generator for ease-of-use but have since been quasi-rolled in to the directions property. They will continue to be supported for backward compatibility.
Size
By default, the puzzle size (in characters) is determined by the amount of words provided and the difficulty level. Need a puzzle an exact size, override the default by setting puzzle.size
. All puzzles are square so size will be the width and height.
>>> puzzle.size = 55
ValueError: Puzzle size must be >= 5 and <= 50
>>> puzzle.size = 20
ℹ️ Puzzles are limited to 50 characters wide so that everything fits nicely on a US Letter or A4 sized sheet of paper.
⚠️ All provided words may not fit a specified puzzle size!
Secret Words
Word-Search-Generator accepts "secret" bonus that can up the difficulty of your puzzle. Secret words are not included in the word list and can have their own level or directions.
>>> puzzle = WordSearch("dog, cat, pig", level=1, secret_words="secret, boo")
puzzle.show()
-----------------------
WORD SEARCH
-----------------------
A U C Q X L H G C L K P
V K J A M D Y I N V S A
U M U Y J B O O M J N X
H D O Z F H Y Z B G S G
R U M A P D O G N U E P
B O P H B I C F J T C I
T J G K R V Y N X Q R G
S F U J P U K L I B E B
P H S K B F Y J Q C T X
G T L E P C N G U A K F
S H K H L D J I S T E O
P F P N Q C T D Q A K R
Find these words: CAT, DOG, PIG
* Words can go E, and S.
Answer Key: *BOO E @ (6, 3), CAT S @ (10, 9), DOG E @ (6, 5), PIG S @ (12, 5), *SECRET S @ (11, 4)
ℹ️ Secret words ARE included in the puzzle key (denoted by a '*').
Secret words can also have their own level or set of directions.
>>> puzzle.secret_directions="N,W"
-----------------------
WORD SEARCH
-----------------------
X J G P N C R Q O J C O
G S F M G A N P M V Z Y
N H P D F T E T B N C Q
O C G T K Y D F U Y P Y
O K U E B T L C R S M T
B J X R D A R D O G Q J
Y N T C T K Z S R W Z E
B C D E P I P I G M U C
M W F S H C Z J D W N G
J Q X Y U N F V I V H V
S T N P Z C A O N B I Y
W A D H E W S B K A R K
Find these words: CAT, DOG, PIG
* Words can go E, and S.
Answer Key: *BOO N @ (1, 6), CAT S @ (6, 1), DOG E @ (8, 6), PIG E @ (7, 8), *SECRET N @ (4, 9)
⚠️ You may have noticed above that the secret directions are not included in the puzzle directions unless they overlap with the valid directions for the regular puzzle words. I told you it ups the difficulty level 📈.
Saving Puzzles
Word-Search-Generator can save puzzles as PDF and CSV files. The file format for which each puzzle is saved is derived from the file extension in the provided path name. Defaults to PDF is no file extension if provided.
💾 Save as a PDF.
puzzle.save(path="~/Desktop/puzzle.pdf")
"~/Desktop/puzzle.pdf"
💾 Save as a CSV.
puzzle.save(path="puzzle.csv")
"./puzzle.csv"
ℹ️ Using the Word-Search-Generator CLI Integration and redirections in your terminal you can also save the puzzle to a text file.
$ word-search dog, cat, pig, horse -k > puzzle.txt
📁 View Sample Files: Word-Search PDF, Word-Search CSV, Word-Search TXT
CLI Integration
Word-Search-Generator works in your terminal too! 🙌
$ word-search -h
usage: word-search [-h] [-r RANDOM] [-x SECRET_WORDS | -rx RANDOM_SECRET_WORDS] [-d DIFFICULTY]
[-xd SECRET_DIFFICULTY] [-s SIZE] [-c] [-o OUTPUT] [--version]
[words ...]
Generate Word Search Puzzles!
Valid Levels: 1, 2, 3, 4, 8, 7
Valid Directions: N, NE, E, SE, S, SW, W, NW
* Directions are to be provided as a comma-separated list.
positional arguments:
words Words to include in the puzzle (default: stdin).
options:
-h, --help show this help message and exit
-r RANDOM, --random RANDOM
Generate {n} random words to include in the puzzle.
-x SECRET_WORDS, --secret-words SECRET_WORDS
Secret bonus words not included in the word list.
-rx RANDOM_SECRET_WORDS, --random-secret-words RANDOM_SECRET_WORDS
Generate {n} random secret words to include in the puzzle.
-d DIFFICULTY, --difficulty DIFFICULTY, -l DIFFICULTY, --level DIFFICULTY
Difficulty level (numeric) or cardinal directions puzzle words can go. See valid arguments
above.
-xd SECRET_DIFFICULTY, --secret-difficulty SECRET_DIFFICULTY
Difficulty level (numeric) or cardinal directions secret puzzle words can go. See valid
arguments above.
-s SIZE, --size SIZE Puzzle size >=5 and <=50
-c, --cheat Show the puzzle solution or include it within the `-o, --output` file.
-o OUTPUT, --output OUTPUT
Output path for saved puzzle. Specify export type by appending '.pdf' or '.csv' to your path
(default: PDF).
--version show program's version number and exit
Copyright 2022 Josh Duncan (joshbduncan.com)
💻 Generate a puzzle.
$ word-search works, from, the, cli, too
💻 Generate a puzzle 20 characters wide with difficulty level 1.
$ word-search works, from, the, cli, too -l 1 -s 20
💻 Generate a puzzle with 10 random dictionary words.
$ word-search -r 10
💻 Generate a puzzle and save as a csv.
$ word-search works, from, the, cli, too -o puzzle.csv
💻 Generate a puzzle and save as a pdf with the solution puzzle included.
$ word-search works, from, the, cli, too -o ~/Desktop/puzzle.pdf -c
ℹ️ You can also use words from a file...
$ cat words.txt | word-search
This really came in handy for those kid's food menus. I was able to take a folder full of .txt documents with themed words and generate dozens of level 1 Word Search Puzzles at exactly 15 characters in size super fast...
$ for f in tools/sample_word_lists/word*.txt; do word-search "$(cat $f)" -l 1 -s 15 -o $f.pdf; done
Puzzle saved: ~/.../words-5.txt.pdf
...
Puzzle saved: ~/.../words-50.txt.pdf
Expert Mode CLI
Really want to challenge yourself? Try this in the CLI. All words will be secret, just don't peek 🫣 at the key! Good luck!
$ word-search -rx 10 -l 3
-------------------
WORD SEARCH
-------------------
M Y C K R E H T I E
I D A E R I G D G Y
N K H O K B N R S T
D J A V F H I E H G
G S R G T D H C B W
P N P W Q T T E V F
A V O T L U Y N M O
U R N O C P N T A U
G X C H K E A Q J R
M I D U N I W R O H
Find these words: <ALL SECRET WORDS>
* Words can go W, SW, NW, SE, E, N, NE, and S.
Answer Key: *ANYTHING N @ (7, 9), *EITHER W @ (10, 1), *FOUR S @ (10, 6), *GROWTH NE @ (1, 9), *HOT N @ (4, 9), *MIND S @ (1, 1), *PERFORMANCE None @ None, *PUT N @ (6, 8), *READ W @ (5, 2), *RECENT S @ (8, 3)
Resources
Contributors
- Chris J.M. @duck57
Project details
Release history Release notifications | RSS feed
Download files
Download the file for your platform. If you're not sure which to choose, learn more about installing packages.
Source Distribution
Built Distribution
Hashes for word-search-generator-3.0.0b1.tar.gz
Algorithm | Hash digest | |
---|---|---|
SHA256 | c486a752d85b73f66ae643ebfd9cb711a4c90ceb3a901e329062bec7d72a75f6 |
|
MD5 | 2e7ef2549801482467586747b4e535f2 |
|
BLAKE2b-256 | 39797426ff94bc3c6db47ece5ea3afa154de2cfe69fa0c27ff86cb6a5f6d0a38 |
Hashes for word_search_generator-3.0.0b1-py3-none-any.whl
Algorithm | Hash digest | |
---|---|---|
SHA256 | a0e3be35347674ff85b1ebdfa4a1734dc3c763de9d165d3aa5b11824cd34e74c |
|
MD5 | afae402b228773e5eec700a486db70ef |
|
BLAKE2b-256 | 9b45af913f5a94635abfb49cf787de02ec822ba48747986896934db1a748ceb8 |