# pysuchsel
pysuchsel is a program to create "Suchsel" word puzzles (i.e., a rectangular
array of letters which have words hidden within that you need to find, aka
"word search"). It can also create crossword puzzles. For both, from a given
word list, grid size and filling rules, it creates an SVG image that can easily
printed.
For Suchsels, it can fill all the void spaces with random letters that are
uniformly distributed or it can choose a random distribution that satisfies a
natural language (German and English are supported), making the Suchsel much
more difficult. It also supports hiding words left-to-right, right-to-left,
top-to-bottom, bottom-to-top, diagonally-to-top-right, diagonally-to-top-left,
diagonally-to-bottom-right, diagonally-to-bottom-left or any combination of
these placements.
For crossword puzzles, it takes care there is not adjacent cells filled, it
enumerates the words and creates number fields in the resulting SVG.
## Installation
pysuchsel requrires an SVG library written by myself,
[pysvgedit](https://github.com/johndoe31415/pysvgedit). It can, however, be
easily installed via PyPi:
```
$ pip install pysuchsel
```
## Suchsel mode
You'll first have to create a file that contains all the words (e.g., using
pluma or vim). We'll call it words.txt
```
$ cat words.txt
SUCHSEL
PADDELFISCH
```
Our file only contains two words. Then, you can already call pysuchsel to place
them into a Suchsel puzzle:
```
$ pysuchsel suchsel words.txt my_first_suchsel.svg
```
If you want to see where they were placed, specify "-v" as well:
```
$ pysuchsel suchsel -v words.txt my_first_suchsel.svg
+--------------------------------+
| |
| |
| |
| |
| P A D D E L F I S C H |
| U |
| C |
| H |
| S |
| E |
| L |
| |
| |
| |
| |
| |
| |
| |
| |
| |
+--------------------------------+
```
You can influence the size with the "-x" and "-y" options:
```
$ pysuchsel suchsel -x 11 -y 11 -v words.txt my_first_suchsel.svg
+------------------------+
| P |
| A |
| D |
| D |
| E |
| L |
| F |
| I S U C H S E L |
| S |
| C |
| H |
+------------------------+
```
You can also specify that you'd like words to share letters, which is then
going to be the preference:
```
$ pysuchsel suchsel -c -x 11 -y 11 -v words.txt my_first_suchsel.svg
+------------------------+
| P |
| A |
| D |
| D |
| S U C H S E L |
| L |
| F |
| I |
| S |
| C |
| H |
+------------------------+
```
When you specify "--verbose" twice, it'll also show how the padded Suchsel
looks like on the command line:
```
$ pysuchsel suchsel -c -x 11 -y 11 -vv words.txt my_first_suchsel.svg
+------------------------+
| |
| |
| |
| |
| S |
| U |
| C |
| H |
| S |
| P A D D E L F I S C H |
| L |
+------------------------+
+------------------------+
| V C V P A B M O Z C K |
| G I M S T X M U S P D |
| T C P W H X W N E D L |
| A S B L H T J U K V Q |
| E L C M S U R T C W Z |
| Z M J C U Y G K Y Q D |
| J C Z E C B I X K J V |
| U T Q E H K Y A F R P |
| H R F A S K K N K V L |
| P A D D E L F I S C H |
| O N D N L E T A H T V |
+------------------------+
```
To specify placement, use the "-p" command line option. For example, to only
create diagonal placement to the bottom right, do:
```
$ pysuchsel suchsel -x 11 -y 11 -p dbr -v words.txt my_first_suchsel.svg
+------------------------+
| P S |
| A U |
| D C |
| D H |
| E S |
| L E |
| F L |
| I |
| S |
| C |
| H |
+------------------------+
```
To allow more than one placement method, specify them all. For example, only
allow top-to-bottom and bottom-to-top:
```
$ pysuchsel suchsel -x 11 -y 11 -p tb -p bt -v words.txt my_first_suchsel.svg
+------------------------+
| S H |
| U C |
| C S |
| H I |
| S F |
| E L |
| L E |
| D |
| D |
| A |
| P |
+------------------------+
```
To influence the padding of letters, look at the "--fill-rule" option. By
default, padded letters are placed in natural language distribution of English
(i.e., each letter has the same probability of occurrence and only A-Z are
placed). That makes uncommon letters (e.g., Q and Y in the German language)
rather frequent not stand out. For example:
```
$ pysuchsel suchsel -x 5 -y 11 -vv words.txt my_first_suchsel.svg
+------------+
| P |
| A |
| D |
| D S |
| E U |
| L C |
| F H |
| I S |
| S E |
| C L |
| H |
+------------+
+------------+
| P A L S I |
| A L U T T |
| D R W N H |
| D S E N R |
| E U T N T |
| L C S I W |
| F H D E D |
| I S N S E |
| S E E A R |
| C L S A W |
| H E T E A |
+------------+
```
You can now first switch to German language, which will include more letters
and choose the German language distribution:
```
$ pysuchsel suchsel -f de -x 5 -y 11 -vv words.txt my_first_suchsel.svg
+------------+
| P |
| A |
| S D |
| U D |
| C E |
| H L |
| S F |
| E I |
| L S |
| C |
| H |
+------------+
+------------+
| L D B P S |
| S E N A F |
| I S D D E |
| E U B D P |
| Ä C D E R |
| I H N L I |
| A S V F S |
| T E N I B |
| L L P S G |
| L S N C R |
| U N T H G |
+------------+
```
You'll see that German letters are placed as fillers (e..g, note the "Ä"), but
it only occurs once (because its character frequency in German language is
comparatively low). Now compare that to:
```
$ pysuchsel suchsel -f de --uniform-distribution -x 5 -y 11 -vv words.txt my_first_suchsel.svg
+------------+
| P |
| A S |
| D U |
| D C |
| E H |
| L S |
| F E |
| I L |
| S |
| C |
| H |
+------------+
+------------+
| V J P D B |
| T G A R S |
| X S D B U |
| I M D H C |
| N N E P H |
| E H L A S |
| Z A F Ö E |
| W J I ß L |
| W O S Z B |
| T G C V Ä |
| P Ö H C V |
+------------+
```
Where you'll see many more "Ä", "Ö", "Ü"s.
The solution to all puzzles is always included in every SVG as a separate
layer; check out "Layer -> Layers and Objects" in Inkscape, for example, and
choose the visibility that suits your needs.
This is how a PNG rendering then looks like:
And this is how the solution PNG looks like:
## Crossword Mode
For crossword mode, you need to use "pysuchsel crossword" instead of "pysuchsel
suchsel". Let's say we add a few more words to our list:
```
$ cat words.txt
SUCHSEL
PADDELFISCH
KREUZWORT
FLUGZEUG
XYLOPHON
```
Then, try to create a crossword:
```
$ pysuchsel crossword -v words.txt my_first_crossword.svg
Warning: could not place word "FLUGZEUG".
Warning: could not place word "KREUZWORT".
1: PADDELFISCH
2: SUCHSEL
3: XYLOPHON
+--------------------------------+
| |
| |
| |
| |
| |
| |
| v |
| P |
| A |
| D v |
| D X |
| E Y |
| L L |
| F O |
| I P |
| > S U C H S E L . |
| C O |
| H N |
| . . |
| |
+--------------------------------+
```
You'll notice that it was not possible to place all words. You can ask
pysuchsel to re-attempt until it finds a solution that places all words by
specifying the "-a" (or --creation-attempts) parameter:
```
$ pysuchsel crossword -v -a 50 words.txt my_first_crossword.svg
1: KREUZWORT
2: XYLOPHON
3: PADDELFISCH
4: SUCHSEL
5: FLUGZEUG
+--------------------------------+
| |
| |
| |
| |
| v |
| v S |
| X U |
| Y C |
| > P A D D E L F I S C H . |
| v O S |
| F P E |
| L H L |
| > K R E U Z W O R T . . |
| G N |
| Z . |
| E |
| U |
| G |
| . |
| |
+--------------------------------+
```
The rendering of this now looks like this:
## Solution Word Puzzle
Out of the word list, there can also be a puzzle be created that leads to a
specific solution word. This is called the "solution word" mode. For it to
work, you'll need a word list and specify the output word that you want to
create. pysuchsel will tell you if you have enough words to create that puzzle.
For example, you can do this:
```
$ pysuchsel solword -v words.txt solword.svg ITZI
#
1 PADDELFISCH
2 KREUZWORT
3 FLUGZEUG
4 MIRABELLE
```
This will also create a puzzle SVG ("solword.svg") which includes the solution
as own separate layers. This is how it looks:
## Crypto Puzzle Mode
pysuchsel can also generate crypto puzzles where each letter corresponds to a
ciphertext character. Only a few letters are revealed and the reader needs to
replace and infer the rest of the letter, possibly using a codeword in the end.
For this, a text file can be generated first:
```
$ cat secret.txt
HELLO THERE
THIS IS A
SECRET MESSAGE
```
Then, simply do:
```
$ pysuchsel crypto -a math secret.txt crypto_puzzle.svg
```
By default, the letters ERNSTL are revealed (on their first occurrence,
respectively). This is how the output looks like:
The alphabet that is used for ciphertext characters can also be chosen. To learn what is available, consult the help page:
```
$ pysuchsel crypto --help
[...]
-a {alpha,math,graph,zodiac,chess,runes}, --alphabet {alpha,math,graph,zodiac,chess,runes}
Name of the ciphertext alphabet(s) to use. Can be
specified multiple times, can be any of alpha, math,
graph, zodiac, chess, runes. Must be given at least
once.
```
To customize which letters are revealed, use the -r option. For example, to
reveal all vovels:
```
$ pysuchsel crypto -a math -r AEIOU secret.txt crypto_puzzle.svg
```
By specifying the -v option, you can see what the reader can definitely start
with (all the revealed letters are shown, although in the output SVG only the
first occurrence is ever shown):
```
$ pysuchsel crypto -v -a math -r AEIOU secret.txt crypto_puzzle.svg
_E__O __E_E
__I_ I_ A
_E__E_ _E__A_E
```
## License
GNU-GPL 3.
Raw data
{
"_id": null,
"home_page": "https://github.com/johndoe31415/pysuchsel",
"name": "pysuchsel",
"maintainer": "",
"docs_url": null,
"requires_python": "",
"maintainer_email": "",
"keywords": "puzzle,crossword,suchsel",
"author": "Johannes Bauer",
"author_email": "joe@johannes-bauer.com",
"download_url": "https://files.pythonhosted.org/packages/ca/07/7937b3ea868d30d32243cb65dc1a5a336ab7ec5d778c043aee9e3c31929c/pysuchsel-0.0.1.tar.gz",
"platform": null,
"description": "# pysuchsel\npysuchsel is a program to create \"Suchsel\" word puzzles (i.e., a rectangular\narray of letters which have words hidden within that you need to find, aka\n\"word search\"). It can also create crossword puzzles. For both, from a given\nword list, grid size and filling rules, it creates an SVG image that can easily\nprinted.\n\nFor Suchsels, it can fill all the void spaces with random letters that are\nuniformly distributed or it can choose a random distribution that satisfies a\nnatural language (German and English are supported), making the Suchsel much\nmore difficult. It also supports hiding words left-to-right, right-to-left,\ntop-to-bottom, bottom-to-top, diagonally-to-top-right, diagonally-to-top-left,\ndiagonally-to-bottom-right, diagonally-to-bottom-left or any combination of\nthese placements.\n\nFor crossword puzzles, it takes care there is not adjacent cells filled, it\nenumerates the words and creates number fields in the resulting SVG.\n\n## Installation\npysuchsel requrires an SVG library written by myself,\n[pysvgedit](https://github.com/johndoe31415/pysvgedit). It can, however, be\neasily installed via PyPi:\n\n```\n$ pip install pysuchsel\n```\n\n\n## Suchsel mode\nYou'll first have to create a file that contains all the words (e.g., using\npluma or vim). We'll call it words.txt\n\n```\n$ cat words.txt\nSUCHSEL\nPADDELFISCH\n```\n\nOur file only contains two words. Then, you can already call pysuchsel to place\nthem into a Suchsel puzzle:\n\n```\n$ pysuchsel suchsel words.txt my_first_suchsel.svg\n```\n\nIf you want to see where they were placed, specify \"-v\" as well:\n\n```\n$ pysuchsel suchsel -v words.txt my_first_suchsel.svg\n+--------------------------------+\n| |\n| |\n| |\n| |\n| P A D D E L F I S C H |\n| U |\n| C |\n| H |\n| S |\n| E |\n| L |\n| |\n| |\n| |\n| |\n| |\n| |\n| |\n| |\n| |\n+--------------------------------+\n```\n\nYou can influence the size with the \"-x\" and \"-y\" options:\n\n```\n$ pysuchsel suchsel -x 11 -y 11 -v words.txt my_first_suchsel.svg\n+------------------------+\n| P |\n| A |\n| D |\n| D |\n| E |\n| L |\n| F |\n| I S U C H S E L |\n| S |\n| C |\n| H |\n+------------------------+\n```\n\nYou can also specify that you'd like words to share letters, which is then\ngoing to be the preference:\n\n```\n$ pysuchsel suchsel -c -x 11 -y 11 -v words.txt my_first_suchsel.svg\n+------------------------+\n| P |\n| A |\n| D |\n| D |\n| S U C H S E L |\n| L |\n| F |\n| I |\n| S |\n| C |\n| H |\n+------------------------+\n```\n\nWhen you specify \"--verbose\" twice, it'll also show how the padded Suchsel\nlooks like on the command line:\n\n```\n$ pysuchsel suchsel -c -x 11 -y 11 -vv words.txt my_first_suchsel.svg\n+------------------------+\n| |\n| |\n| |\n| |\n| S |\n| U |\n| C |\n| H |\n| S |\n| P A D D E L F I S C H |\n| L |\n+------------------------+\n+------------------------+\n| V C V P A B M O Z C K |\n| G I M S T X M U S P D |\n| T C P W H X W N E D L |\n| A S B L H T J U K V Q |\n| E L C M S U R T C W Z |\n| Z M J C U Y G K Y Q D |\n| J C Z E C B I X K J V |\n| U T Q E H K Y A F R P |\n| H R F A S K K N K V L |\n| P A D D E L F I S C H |\n| O N D N L E T A H T V |\n+------------------------+\n```\n\nTo specify placement, use the \"-p\" command line option. For example, to only\ncreate diagonal placement to the bottom right, do:\n\n```\n$ pysuchsel suchsel -x 11 -y 11 -p dbr -v words.txt my_first_suchsel.svg\n+------------------------+\n| P S |\n| A U |\n| D C |\n| D H |\n| E S |\n| L E |\n| F L |\n| I |\n| S |\n| C |\n| H |\n+------------------------+\n```\n\nTo allow more than one placement method, specify them all. For example, only\nallow top-to-bottom and bottom-to-top:\n\n```\n$ pysuchsel suchsel -x 11 -y 11 -p tb -p bt -v words.txt my_first_suchsel.svg\n+------------------------+\n| S H |\n| U C |\n| C S |\n| H I |\n| S F |\n| E L |\n| L E |\n| D |\n| D |\n| A |\n| P |\n+------------------------+\n```\n\nTo influence the padding of letters, look at the \"--fill-rule\" option. By\ndefault, padded letters are placed in natural language distribution of English\n(i.e., each letter has the same probability of occurrence and only A-Z are\nplaced). That makes uncommon letters (e.g., Q and Y in the German language)\nrather frequent not stand out. For example:\n\n```\n$ pysuchsel suchsel -x 5 -y 11 -vv words.txt my_first_suchsel.svg\n+------------+\n| P |\n| A |\n| D |\n| D S |\n| E U |\n| L C |\n| F H |\n| I S |\n| S E |\n| C L |\n| H |\n+------------+\n+------------+\n| P A L S I |\n| A L U T T |\n| D R W N H |\n| D S E N R |\n| E U T N T |\n| L C S I W |\n| F H D E D |\n| I S N S E |\n| S E E A R |\n| C L S A W |\n| H E T E A |\n+------------+\n```\n\nYou can now first switch to German language, which will include more letters\nand choose the German language distribution:\n\n```\n$ pysuchsel suchsel -f de -x 5 -y 11 -vv words.txt my_first_suchsel.svg\n+------------+\n| P |\n| A |\n| S D |\n| U D |\n| C E |\n| H L |\n| S F |\n| E I |\n| L S |\n| C |\n| H |\n+------------+\n+------------+\n| L D B P S |\n| S E N A F |\n| I S D D E |\n| E U B D P |\n| \u00c4 C D E R |\n| I H N L I |\n| A S V F S |\n| T E N I B |\n| L L P S G |\n| L S N C R |\n| U N T H G |\n+------------+\n```\n\nYou'll see that German letters are placed as fillers (e..g, note the \"\u00c4\"), but\nit only occurs once (because its character frequency in German language is\ncomparatively low). Now compare that to:\n\n```\n$ pysuchsel suchsel -f de --uniform-distribution -x 5 -y 11 -vv words.txt my_first_suchsel.svg\n+------------+\n| P |\n| A S |\n| D U |\n| D C |\n| E H |\n| L S |\n| F E |\n| I L |\n| S |\n| C |\n| H |\n+------------+\n+------------+\n| V J P D B |\n| T G A R S |\n| X S D B U |\n| I M D H C |\n| N N E P H |\n| E H L A S |\n| Z A F \u00d6 E |\n| W J I \u00df L |\n| W O S Z B |\n| T G C V \u00c4 |\n| P \u00d6 H C V |\n+------------+\n```\n\nWhere you'll see many more \"\u00c4\", \"\u00d6\", \"\u00dc\"s.\n\nThe solution to all puzzles is always included in every SVG as a separate\nlayer; check out \"Layer -> Layers and Objects\" in Inkscape, for example, and\nchoose the visibility that suits your needs.\n\nThis is how a PNG rendering then looks like:\n\n\n\nAnd this is how the solution PNG looks like:\n\n\n\n\n## Crossword Mode\nFor crossword mode, you need to use \"pysuchsel crossword\" instead of \"pysuchsel\nsuchsel\". Let's say we add a few more words to our list:\n\n```\n$ cat words.txt\nSUCHSEL\nPADDELFISCH\nKREUZWORT\nFLUGZEUG\nXYLOPHON\n```\n\nThen, try to create a crossword:\n\n```\n$ pysuchsel crossword -v words.txt my_first_crossword.svg\nWarning: could not place word \"FLUGZEUG\".\nWarning: could not place word \"KREUZWORT\".\n 1: PADDELFISCH\n 2: SUCHSEL\n 3: XYLOPHON\n+--------------------------------+\n| |\n| |\n| |\n| |\n| |\n| |\n| v |\n| P |\n| A |\n| D v |\n| D X |\n| E Y |\n| L L |\n| F O |\n| I P |\n| > S U C H S E L . |\n| C O |\n| H N |\n| . . |\n| |\n+--------------------------------+\n```\n\nYou'll notice that it was not possible to place all words. You can ask\npysuchsel to re-attempt until it finds a solution that places all words by\nspecifying the \"-a\" (or --creation-attempts) parameter:\n\n```\n$ pysuchsel crossword -v -a 50 words.txt my_first_crossword.svg\n 1: KREUZWORT\n 2: XYLOPHON\n 3: PADDELFISCH\n 4: SUCHSEL\n 5: FLUGZEUG\n+--------------------------------+\n| |\n| |\n| |\n| |\n| v |\n| v S |\n| X U |\n| Y C |\n| > P A D D E L F I S C H . |\n| v O S |\n| F P E |\n| L H L |\n| > K R E U Z W O R T . . |\n| G N |\n| Z . |\n| E |\n| U |\n| G |\n| . |\n| |\n+--------------------------------+\n```\n\nThe rendering of this now looks like this:\n\n\n\n\n## Solution Word Puzzle\nOut of the word list, there can also be a puzzle be created that leads to a\nspecific solution word. This is called the \"solution word\" mode. For it to\nwork, you'll need a word list and specify the output word that you want to\ncreate. pysuchsel will tell you if you have enough words to create that puzzle.\nFor example, you can do this:\n\n```\n$ pysuchsel solword -v words.txt solword.svg ITZI\n #\n 1 PADDELFISCH\n 2 KREUZWORT\n 3 FLUGZEUG\n 4 MIRABELLE\n```\n\nThis will also create a puzzle SVG (\"solword.svg\") which includes the solution\nas own separate layers. This is how it looks:\n\n\n\n\n\n\n## Crypto Puzzle Mode\npysuchsel can also generate crypto puzzles where each letter corresponds to a\nciphertext character. Only a few letters are revealed and the reader needs to\nreplace and infer the rest of the letter, possibly using a codeword in the end.\n\nFor this, a text file can be generated first:\n\n```\n$ cat secret.txt\nHELLO THERE\nTHIS IS A\nSECRET MESSAGE\n```\n\nThen, simply do:\n\n```\n$ pysuchsel crypto -a math secret.txt crypto_puzzle.svg\n```\n\nBy default, the letters ERNSTL are revealed (on their first occurrence,\nrespectively). This is how the output looks like:\n\n\n\nThe alphabet that is used for ciphertext characters can also be chosen. To learn what is available, consult the help page:\n\n```\n$ pysuchsel crypto --help\n[...]\n -a {alpha,math,graph,zodiac,chess,runes}, --alphabet {alpha,math,graph,zodiac,chess,runes}\n Name of the ciphertext alphabet(s) to use. Can be\n specified multiple times, can be any of alpha, math,\n graph, zodiac, chess, runes. Must be given at least\n once.\n```\n\nTo customize which letters are revealed, use the -r option. For example, to\nreveal all vovels:\n\n```\n$ pysuchsel crypto -a math -r AEIOU secret.txt crypto_puzzle.svg\n```\n\nBy specifying the -v option, you can see what the reader can definitely start\nwith (all the revealed letters are shown, although in the output SVG only the\nfirst occurrence is ever shown):\n\n```\n$ pysuchsel crypto -v -a math -r AEIOU secret.txt crypto_puzzle.svg\n_E__O __E_E\n__I_ I_ A\n_E__E_ _E__A_E\n```\n\n\n## License\nGNU-GPL 3.\n",
"bugtrack_url": null,
"license": "gpl-3.0",
"summary": "Native Python library to create and edit SVG documents",
"version": "0.0.1",
"project_urls": {
"Download": "https://github.com/johndoe31415/pysuchsel/archive/v0.0.1.tar.gz",
"Homepage": "https://github.com/johndoe31415/pysuchsel"
},
"split_keywords": [
"puzzle",
"crossword",
"suchsel"
],
"urls": [
{
"comment_text": "",
"digests": {
"blake2b_256": "ca077937b3ea868d30d32243cb65dc1a5a336ab7ec5d778c043aee9e3c31929c",
"md5": "9212cccdb7a714e30225605c851977b9",
"sha256": "2e03f2647aac9ca1ad4a7f06c8046215483dc2b9bd916aebf338c840ad3b8a00"
},
"downloads": -1,
"filename": "pysuchsel-0.0.1.tar.gz",
"has_sig": false,
"md5_digest": "9212cccdb7a714e30225605c851977b9",
"packagetype": "sdist",
"python_version": "source",
"requires_python": null,
"size": 33356,
"upload_time": "2023-07-04T22:37:09",
"upload_time_iso_8601": "2023-07-04T22:37:09.763970Z",
"url": "https://files.pythonhosted.org/packages/ca/07/7937b3ea868d30d32243cb65dc1a5a336ab7ec5d778c043aee9e3c31929c/pysuchsel-0.0.1.tar.gz",
"yanked": false,
"yanked_reason": null
}
],
"upload_time": "2023-07-04 22:37:09",
"github": true,
"gitlab": false,
"bitbucket": false,
"codeberg": false,
"github_user": "johndoe31415",
"github_project": "pysuchsel",
"travis_ci": false,
"coveralls": false,
"github_actions": false,
"lcname": "pysuchsel"
}
JSON
