karabiner-configurator 0.1.0

Generate and apply Karabiner-Elements SpaceFN configurations

karabiner-configurator

Python library and CLI to generate Karabiner-Elements complex modifications, with support for a SpaceFN layer and hostname-based config overrides.

Install

pip install karabiner-configurator

CLI

# Apply rules to Karabiner profile and generate index.html
karabiner-configurator

# Use a custom config directory
karabiner-configurator /path/to/config

# Only generate HTML visualization
karabiner-configurator --html-only

# Apply rules without generating HTML
karabiner-configurator --no-html

# Show informative logs
karabiner-configurator --verbose

# Only show errors
karabiner-configurator --quiet

By default, the CLI looks for:

• config.default.json (required)
• config.<hostname>.json (optional)

Configuration is validated before rule generation; unknown definition keys fail fast with a clear error.

HTML rendering uses a Jinja template stored at karabiner_configurator/templates/keyboard.html.j2.

Library Usage

from karabiner_configurator import (
    main,
    load_config,
    apply_rules_to_karabiner,
    generate_html_keyboard,
)

config = load_config("/path/to/config")
rules = main(config["spacefn_definitions"], config["normal_definitions"])
apply_rules_to_karabiner(rules, config.get("profile_name", "VIM"))
generate_html_keyboard(config, "index.html")

Development

# Install editable package + dev tooling
pip install -e ".[dev]"

# Enable default local checks on every commit
pre-commit install

# Lint (ruff, 120 cols)
ruff check .

# Optional formatting check
ruff format --check .

# Type check (mypy)
mypy

# Run tests
python -m unittest discover -s tests -v

# Build package artifacts
python -m pip install build
python -m build

GitHub + PyPI Release Setup

The repository is prepared with:

• CI workflow: .github/workflows/ci.yml
• Publish workflow: .github/workflows/publish-pypi.yml
• PEP 621 packaging in pyproject.toml

One-time setup

1. Create a PyPI project named karabiner-configurator.
2. In PyPI project settings, add a trusted publisher for this GitHub repo and workflow: .github/workflows/publish-pypi.yml.
3. In GitHub, keep the pypi environment (created by workflow) or create it with your preferred protections.

Publish

1. Bump version in pyproject.toml.
2. Commit and push.
3. Create and publish a GitHub Release.
4. The Publish to PyPI workflow will build and upload the release to PyPI.

License

MIT