Design and play procedurally generated crosswords
Project description
xpuz
An educational GUI/web package built with CustomTkinter
and Flask
that allows you to design and play procedurally generated crosswords.
- Download the latest source code: click here
Dependencies
Babel
customtkinter
Flask
flask_babel
Pillow
regex
platformdirs
pathvalidate
CTkToolTip
pycairo
is an optional dependency that is required if you want to make PDFs from your generated crosswords. After reading Installation and installing the package, also run pip install pycairo
. If you are on an operating system other than Windows, please also read pycairo's Getting Started to install the required headers for pycairo
.
[!WARNING]
Languages whose alphabets use complex glyphs (such as Mandarin and Japanese) are not supported when making PDFs.
Tested Python versions
- Windows: Python >= 3.7
- MacOS: Python >= 3.8
- Linux: Python >= 3.8
Requirements
-
Hardware
- RAM: >120MB (GUI only), >500MB (GUI and browser to play crossword)
- CPU: Any
- Storage: >30MB available space (the program and its dependencies)
-
Software
- OS: Windows, MacOS, Linux
- Browser: Not Internet Explorer
- Additional: Python and pip (see Installation)
Limitations
- Right-to-left scripts are not supported.
- Translations are made with a translation API, and therefore might be inaccurate.
- Generated crosswords may occasionally have a few missing words.
- If your OS scaling is higher than the default, the web application will likely be too big. Read Troubleshooting for more information.
Installation
[!IMPORTANT] Installing
xpuz
requires Python3 and pip. If you have Python3 installed without pip, click here to install it.
If you do not have Python3 installed, download the installer here, or install it with pyenv (recommended). Then, refer to the previous link on how to install pip.
Linux and MacOS users: You may not have Tkinter installed by default. Try runningsudo apt-get install python3-tk
on Linux orsudo pip install python3-tk
on MacOS if this is the case.
[!TIP] If using
python
orpip
doesn't work, try usingpython3
orpip3
.
- Make a virtual environment and activate it (recommended):
pip install virtualenv
python -m venv venv
MacOS/Unix: source venv/bin/activate
Windows: venv\scripts\activate
Windows users: If you cannot activate the virtual environment, try running Set-ExecutionPolicy Unrestricted -Scope Process
in your terminal, ensuring you follow all the prompts. Then, try this step again.
- Install the package in your system directory/virtual environment:
pip install xpuz
or, install the package in your home directory if you aren't using a virtual environment:
pip install --user xpuz
- Install pycairo if you want to make PDFs from your generated crosswords (read Dependencies for more information):
pip install pycairo
- Initialise the GUI through the entry point:
xpuz-ctk
or, run the package manually through the terminal (requires Git):
git clone https://github.com/tomasvana10/xpuz.git
cd xpuz
pip install -r requirements.txt
>>> import xpuz as xp
>>> xp.main()
- You can deactivate your virtual environment when you are done:
deactivate
Updating
-
Activate your virtual environment if you are using one.
-
Update the package:
pip install -U xpuz
Quickstart
You can utilise one of two scripts to quickly activate a virtual environment and update and start xpuz
.
- Read the
Important
section of Installation to install Python3 and pip - Windows users: Ensure you have script execution enabled. If you are unsure, run
Set-ExecutionPolicy Unrestricted -Scope Process
in your terminal and follow the prompts. - Download a quickstart file from the repository:
- Windows: quickstart-win.bat
- MacOS/Linux: quickstart-posix.sh
- Run the script:
- Windows: Double click the script file or call it in command-line with
.\path\to\quickstart-win.bat
. - MacOS/Linux: Call the script in the command-line with
source path/to/quickstart-posix.sh
.
- Windows: Double click the script file or call it in command-line with
Documentation
Check out the wiki here for information on usage, troubleshooting, FAQ, and more.
Third-party library acknowledgements
- Flask - Web framework for the crossword web application
- Babel - l10n functionality and management of message catalogues
- flask-babel - i18n integration for the Flask web application
- CustomTkinter - Creation of the main GUI
- platformdirs - Retrieving paths to platform-specific directories
- Google.Cloud.Translation.V2 - Translation of locales
- Pillow - Image processing services
- regex - Alternative to the standard
re
module, required for some functionality - Zoomooz.js - jQuery library for making webpage elements zoomable
- gulp.js - Toolkit to help automate the web app's JavaScript transpilation
- Babel.js - JavaScript transpiler
- Terser - JavaScript minifier
- CTkToolTip - Tooltips for forms in the crossword editor
- pathvalidate - Validating crossword name input
- platformdirs - Storing config and user-made crosswords
- Pycairo - Crossword PDF creation
- pywebview - Browser webview to play crossword
Other acknowledgements
- NYTimes Mini Crossword - Heavily inspired the design of the web application
- CSS Pattern - Background CSS patterns
- Pure CSS Toggle Switch - Toggle switch CSS patterns
- Jazzy Chords by NenadSimic -- https://freesound.org/s/150879/ -- License: Creative Commons 0
Gallery
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.