ksost 17

Kanji Stroke Order Study Tool

ksost

ksost stands for Kanji Stroke Order Study Tool. It is a small web application for studying kanji stroke order, written in Python and plain JavaScript.

The server has no runtime Python or JavaScript package dependencies, but there are some dependencies for development and to run the desktop wrapper, as well as some setup steps required to run from source. See Running From Source, Desktop Wrapper and Development.

Dependencies

• Python >= 3.14
• SQLite3
• optional Qt for desktop wrapper

Installing

ksost is currently packaged only as a PyPI package and can be installed by end users by running:

pip install ksost
# To include native desktop dependencies (won't work on Linux):
pip install 'ksost[desktop]'
# To include Qt desktop dependencies:
pip install 'ksost[desktop-qt]'

Running From Source

First initialize the dataset submodules. You can use git submodule for that, but prefer the make bootstrap target, which will also prepare the environment in other ways (see make targets):

make bootstrap

Then activate the venv and start the server using the command installed in it, or call the commands using the venv explicitly:

# Activating the venv
. .venv/bin/activate
ksost

# Without activating the venv
.venv/bin/ksost
# Or
.venv/bin/python -m ksost

These commands start the built-in HTTP server and initialize the configured SQLite database if needed.

If you want to initialize the database explicitly, you can also run:

ksost init-db

Desktop Wrapper

To run the desktop wrapper on Linux you need Qt installed on your system beforehand. The Python-level desktop dependencies are defined in pyproject.toml, and you can install them to your venv manually or with:

make desktop-qt
# In Windows/Mac you can probably use it without Qt, with just:
make desktop

Then run with:

ksost desktop
# Or force Qt:
ksost desktop qt

Configuration

Runtime configuration lives in ksost.toml. ksost looks for that file in this order, using only the first file it finds:

1. the file passed with -c or --config-file, if provided
2. the current working directory
3. the user config directory
4. the system config directories

When -c or --config-file is provided, the file must exist.

An example commented file is provided at ksost.toml.example.

On Linux, the user config directory is $XDG_CONFIG_HOME/ksost if XDG_CONFIG_HOME is set, otherwise ~/.config/ksost. System config directories are /etc/ksost followed by the entries in XDG_CONFIG_DIRS, or /etc/xdg/ksost if XDG_CONFIG_DIRS is not set.

Development

For development, create a virtual environment and install the dev optional-dependency group from pyproject.toml.

You can do that manually, or use the make target:

make dev

This also creates an untracked local override file at ksost/frontend/pwa.local.js if it does not exist yet. By default it keeps the normal PWA behavior:

export const PWA_ENABLED = true;

For local frontend testing, you can change that to false, which disables the service-worker/PWA behavior, making testing easier when you're constantly changing the static files.

To run the checks:

./scripts/check.sh && ./scripts/test.sh

make targets

You can see in Makefile the complete list of targets. In addition to the actual file targets, there are phony targets that group targets in useful functional groups. The top-level targets are:

• Bootstrap targets:
  • bootstrap
    • Includes submodules, which initializes git submodules
    • Includes data, which copies important files from submodules to the paths where the application expects them
    • Includes venv, which creates the Python virtual environment in .venv
  • dev
    • Includes bootstrap
    • Includes overrides, which creates the PWA override mentioned in Development
    • Installs the Python extra development dependencies from pyproject.toml
  • desktop
    • Includes bootstrap
    • Installs the Python extra desktop dependencies from pyproject.toml
  • desktop-qt
    • Same as desktop, including Qt dependencies
    • Should be used in Linux, instead of desktop
• Packaging targets:
  • arch
    • Depends on the Python package artifacts, see below
    • Updates the PKGBUILD source hash
    • Generates .SRCINFO
    • Runs makepkg -s to package for Arch Linux
    • Must be run outside an active Python venv
    • Not currently published on the AUR, PKGBUILD is here as a reference if someone desires to do so
  • docker
    • Builds the Docker image from dist/docker/Dockerfile
    • Uses package from PyPI instead of local files to build
    • Not currently published on any container registry, this target and the Dockerfile are available if someone desires to publish and maintain it
  • python
    • Creates both the python wheel and sdist packages, with our best effort to make both builds reproducible
    • Refuses to build when the git worktree has unstaged or untracked changes
    • Use make ALLOW_DIRTY=1 python to bypass
  • clean-dist
    • Remove all generated artifacts in dist/

License

ksost itself is licensed under MIT. This repository also includes third-party datasets under their own licenses. See LICENSE for the exact boundary and the referenced third-party license files.