keyhac 2.0.0__tar.gz

keyhac-2.0.0/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 craftware
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

keyhac-2.0.0/MANIFEST.in

@@ -0,0 +1,14 @@
+# Sdist contents (the wheel is governed by pyproject.toml's packages /
+# package-data). setuptools already ships the keyhac package sources, the
+# keyhac.ui assets declared as package-data, README, LICENSE and
+# pyproject.toml; the lines below prune everything not needed to install and
+# run Keyhac. Same scheme as XeFM's MANIFEST.in.
+
+# Development trees and build byproducts — kept out of the sdist.
+prune tests
+prune doc
+prune art
+prune tools
+prune macos_app
+prune windows_app
+global-exclude __pycache__ *.py[cod] .DS_Store

keyhac-2.0.0/PKG-INFO

@@ -0,0 +1,141 @@
+Metadata-Version: 2.4
+Name: keyhac
+Version: 2.0.0
+Summary: Keyhac 2 - Python-scriptable keyboard customization tool for Windows and macOS
+Author: craftware
+License-Expression: MIT
+Project-URL: Homepage, https://github.com/crftwr/keyhac2
+Project-URL: Repository, https://github.com/crftwr/keyhac2
+Project-URL: Issues, https://github.com/crftwr/keyhac2/issues
+Keywords: keyboard,hotkey,keymap,macro,remap,customization
+Classifier: Development Status :: 5 - Production/Stable
+Classifier: Environment :: MacOS X
+Classifier: Environment :: Win32 (MS Windows)
+Classifier: Intended Audience :: End Users/Desktop
+Classifier: Operating System :: MacOS
+Classifier: Operating System :: Microsoft :: Windows
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Programming Language :: Python :: 3.13
+Classifier: Topic :: Utilities
+Requires-Python: >=3.12
+Description-Content-Type: text/markdown
+License-File: LICENSE
+Requires-Dist: puikit>=1.0.8
+Requires-Dist: pyobjc-framework-Cocoa>=10; sys_platform == "darwin"
+Requires-Dist: pyobjc-framework-Quartz>=10; sys_platform == "darwin"
+Requires-Dist: pyobjc-framework-ApplicationServices>=10; sys_platform == "darwin"
+Provides-Extra: dev
+Requires-Dist: pytest>=8; extra == "dev"
+Dynamic: license-file
+
+# Keyhac 2
+
+Python-scriptable keyboard customization for **Windows and macOS**.
+
+Keyhac installs a system-wide keyboard hook and lets you script what your keys do in
+Python. You write one file, `~/.keyhac/config.py`, and it runs unchanged on both OSes —
+remapping keys, binding keys to Python functions, and driving windows, applications and
+the clipboard from the keyboard.
+
+Keyhac 2 is the successor to both
+[Keyhac for Windows](https://github.com/crftwr/keyhac) and
+[Keyhac for macOS](https://github.com/crftwr/keyhac-mac), rebuilt as one shared codebase.
+Its UI is built on [PuiKit](https://github.com/crftwr/puikit).
+
+## Features
+
+- **Key remapping**: key → key, key → key sequence, key → Python function.
+- **Per-application key tables**: match by app name, window title, Win32 window class,
+  or the full accessibility focus path (AX on macOS, UI Automation on Windows) — down to
+  "only in this app's text editor pane".
+- **User modifiers**: turn any key into a modifier of your own (User0–User3), invisible
+  to applications.
+- **One-shot modifiers**: tap a modifier alone for one action, hold it to modify.
+- **Multi-stroke key tables**: Emacs-style prefix keys, with a balloon showing the
+  armed prefix.
+- **Clipboard history**: persistent history in a popup chooser — type to filter,
+  Enter pastes into the app you came from. Plus fixed snippets and scriptable
+  clipboard-transform tools.
+- **Window control**: move, snap/tile, minimize, activate and launch applications,
+  multi-monitor aware.
+- **Keyboard macros**: record and replay keys.
+- **Mouse output**: send clicks, wheel scrolls and pointer moves from key bindings.
+- **Console window**: live log, last-key and focus-path inspector — see exactly what to
+  bind. Runs from the system tray (Windows) / menu-bar extra (macOS).
+
+## Screenshots
+
+| Console (macOS) | Console (Windows) |
+|---|---|
+| ![Keyhac console window on macOS: keyboard-hook toggle, log level selector, live key-event log, last-key and focus-path inspector](doc/images/console-mac.jpg) | ![Keyhac console window on Windows: keyboard-hook toggle, log level selector, live key-event log, last-key and focus-path inspector](doc/images/console-win.jpg) |
+
+| Menu-bar extra (macOS) | Task tray (Windows) |
+|---|---|
+| ![Keyhac menu-bar extra on macOS with its menu open: Open Console, Edit Config, Reload Config, Keyboard Hook, Quit Keyhac](doc/images/menubar-extra-icon-mac.jpg) | ![Keyhac task-tray icon on Windows with its menu open: Open Console, Edit Config, Reload Config, Keyboard Hook, Quit Keyhac](doc/images/tasktray-icon-win.jpg) |
+
+## Install
+
+Download from [Releases](https://github.com/crftwr/keyhac2/releases):
+
+- **macOS 15+** — `Keyhac-<version>-macos.dmg`: drag Keyhac.app into Applications and
+  launch it. Grant the Accessibility permission when prompted (required for the
+  keyboard hook).
+- **Windows 10/11 (x64)** — `Keyhac-<version>-win64.zip`: unzip anywhere and run
+  `Keyhac.exe`.
+
+Details, data locations and privacy notes: [doc/installation.md](doc/installation.md).
+
+## Quick start
+
+On first run Keyhac creates `~/.keyhac/config.py` from a fully commented template.
+Open it from the tray / menu-bar icon ("Edit Config"), edit, then "Reload Config".
+A config defines one function:
+
+```python
+from keyhac import *
+
+def configure(keymap):
+    kt = keymap.define_keytable(focus_path_pattern="*")   # active everywhere
+
+    kt["Fn-J"] = "Left"                        # key -> key
+    kt["Fn-A"] = "Home", "Shift-End"           # key -> sequence
+
+    def hello():                               # key -> Python function
+        print("Hello from config.py")
+    kt["Fn-H"] = hello
+
+    kt["Fn-V"] = ShowClipboardHistory()        # clipboard history popup
+
+    kt_browser = keymap.define_keytable(app="chrome|Safari")   # per-app table
+    kt_browser["Fn-R"] = "Cmd-R"
+```
+
+The full reference is [doc/configuration.md](doc/configuration.md); the shipped
+template ([keyhac/_config.py](keyhac/_config.py)) is a working tour of every feature.
+
+## Documentation
+
+- [Installation](doc/installation.md) — install, permissions, data files, privacy.
+- [Configuration](doc/configuration.md) — the complete config.py reference.
+- [Migrating from Keyhac for macOS](doc/migration-from-keyhac-mac.md) — mostly drop-in.
+- [Migrating from Keyhac for Windows](doc/migration-from-keyhac-win.md) — API renamed;
+  translation table.
+- [Developer documentation](doc/dev/) — architecture, platform layer, packaging,
+  testing. Project guide for coding agents: [CLAUDE.md](CLAUDE.md).
+
+## Running from source
+
+```sh
+python3 -m venv .venv
+.venv/bin/pip install -e ".[dev]"
+.venv/bin/python -m pytest          # engine + unit tests, no permissions needed
+.venv/bin/python -m keyhac          # run (macOS: needs Accessibility permission)
+```
+
+`python -m keyhac -d` enables debug logging, `--no-ui` runs headless (hook + engine
+only), `--config PATH` uses an alternate config file (its data files live beside it).
+
+## License
+
+MIT — see [LICENSE](LICENSE).

keyhac-2.0.0/README.md

@@ -0,0 +1,110 @@
+# Keyhac 2
+
+Python-scriptable keyboard customization for **Windows and macOS**.
+
+Keyhac installs a system-wide keyboard hook and lets you script what your keys do in
+Python. You write one file, `~/.keyhac/config.py`, and it runs unchanged on both OSes —
+remapping keys, binding keys to Python functions, and driving windows, applications and
+the clipboard from the keyboard.
+
+Keyhac 2 is the successor to both
+[Keyhac for Windows](https://github.com/crftwr/keyhac) and
+[Keyhac for macOS](https://github.com/crftwr/keyhac-mac), rebuilt as one shared codebase.
+Its UI is built on [PuiKit](https://github.com/crftwr/puikit).
+
+## Features
+
+- **Key remapping**: key → key, key → key sequence, key → Python function.
+- **Per-application key tables**: match by app name, window title, Win32 window class,
+  or the full accessibility focus path (AX on macOS, UI Automation on Windows) — down to
+  "only in this app's text editor pane".
+- **User modifiers**: turn any key into a modifier of your own (User0–User3), invisible
+  to applications.
+- **One-shot modifiers**: tap a modifier alone for one action, hold it to modify.
+- **Multi-stroke key tables**: Emacs-style prefix keys, with a balloon showing the
+  armed prefix.
+- **Clipboard history**: persistent history in a popup chooser — type to filter,
+  Enter pastes into the app you came from. Plus fixed snippets and scriptable
+  clipboard-transform tools.
+- **Window control**: move, snap/tile, minimize, activate and launch applications,
+  multi-monitor aware.
+- **Keyboard macros**: record and replay keys.
+- **Mouse output**: send clicks, wheel scrolls and pointer moves from key bindings.
+- **Console window**: live log, last-key and focus-path inspector — see exactly what to
+  bind. Runs from the system tray (Windows) / menu-bar extra (macOS).
+
+## Screenshots
+
+| Console (macOS) | Console (Windows) |
+|---|---|
+| ![Keyhac console window on macOS: keyboard-hook toggle, log level selector, live key-event log, last-key and focus-path inspector](doc/images/console-mac.jpg) | ![Keyhac console window on Windows: keyboard-hook toggle, log level selector, live key-event log, last-key and focus-path inspector](doc/images/console-win.jpg) |
+
+| Menu-bar extra (macOS) | Task tray (Windows) |
+|---|---|
+| ![Keyhac menu-bar extra on macOS with its menu open: Open Console, Edit Config, Reload Config, Keyboard Hook, Quit Keyhac](doc/images/menubar-extra-icon-mac.jpg) | ![Keyhac task-tray icon on Windows with its menu open: Open Console, Edit Config, Reload Config, Keyboard Hook, Quit Keyhac](doc/images/tasktray-icon-win.jpg) |
+
+## Install
+
+Download from [Releases](https://github.com/crftwr/keyhac2/releases):
+
+- **macOS 15+** — `Keyhac-<version>-macos.dmg`: drag Keyhac.app into Applications and
+  launch it. Grant the Accessibility permission when prompted (required for the
+  keyboard hook).
+- **Windows 10/11 (x64)** — `Keyhac-<version>-win64.zip`: unzip anywhere and run
+  `Keyhac.exe`.
+
+Details, data locations and privacy notes: [doc/installation.md](doc/installation.md).
+
+## Quick start
+
+On first run Keyhac creates `~/.keyhac/config.py` from a fully commented template.
+Open it from the tray / menu-bar icon ("Edit Config"), edit, then "Reload Config".
+A config defines one function:
+
+```python
+from keyhac import *
+
+def configure(keymap):
+    kt = keymap.define_keytable(focus_path_pattern="*")   # active everywhere
+
+    kt["Fn-J"] = "Left"                        # key -> key
+    kt["Fn-A"] = "Home", "Shift-End"           # key -> sequence
+
+    def hello():                               # key -> Python function
+        print("Hello from config.py")
+    kt["Fn-H"] = hello
+
+    kt["Fn-V"] = ShowClipboardHistory()        # clipboard history popup
+
+    kt_browser = keymap.define_keytable(app="chrome|Safari")   # per-app table
+    kt_browser["Fn-R"] = "Cmd-R"
+```
+
+The full reference is [doc/configuration.md](doc/configuration.md); the shipped
+template ([keyhac/_config.py](keyhac/_config.py)) is a working tour of every feature.
+
+## Documentation
+
+- [Installation](doc/installation.md) — install, permissions, data files, privacy.
+- [Configuration](doc/configuration.md) — the complete config.py reference.
+- [Migrating from Keyhac for macOS](doc/migration-from-keyhac-mac.md) — mostly drop-in.
+- [Migrating from Keyhac for Windows](doc/migration-from-keyhac-win.md) — API renamed;
+  translation table.
+- [Developer documentation](doc/dev/) — architecture, platform layer, packaging,
+  testing. Project guide for coding agents: [CLAUDE.md](CLAUDE.md).
+
+## Running from source
+
+```sh
+python3 -m venv .venv
+.venv/bin/pip install -e ".[dev]"
+.venv/bin/python -m pytest          # engine + unit tests, no permissions needed
+.venv/bin/python -m keyhac          # run (macOS: needs Accessibility permission)
+```
+
+`python -m keyhac -d` enables debug logging, `--no-ui` runs headless (hook + engine
+only), `--config PATH` uses an alternate config file (its data files live beside it).
+
+## License
+
+MIT — see [LICENSE](LICENSE).

keyhac-2.0.0/keyhac/__init__.py

@@ -0,0 +1,70 @@
+"""Keyhac 2 - Python-scriptable keyboard customization for Windows and macOS.
+
+Configuration files do `from keyhac import *` and get the user-facing API.
+"""
+
+__version__ = "2.0.0"
+
+from keyhac.core.keymap import Keymap
+from keyhac.core.key import KeyCondition, KeyTable
+from keyhac.core.focus import FocusCondition
+from keyhac.core.input import InputContext
+from keyhac.core.log import getLogger, Console
+from keyhac.core.action import (
+    ThreadedAction, LaunchApplication, InputText,
+    StartRecordingKeys, StopRecordingKeys, ToggleRecordingKeys,
+    PlaybackRecordedKeys,
+)
+from keyhac.core.clipboard_history import ClipboardHistory
+from keyhac.actions import (
+    ActivateWindow,
+    MouseButtonClick,
+    MouseButtonDown,
+    MouseButtonUp,
+    MouseHorizontalWheel,
+    MouseMove,
+    MouseWheel,
+    MoveWindow,
+    SnapWindow,
+    ChooserAction,
+    DateTimeSnippet,
+    ShowClipboardHistory,
+    ShowClipboardSnippets,
+    ShowClipboardTools,
+)
+from keyhac.platform.base import Focus, KeyEvent
+
+__all__ = [
+    "Keymap",
+    "KeyTable",
+    "KeyCondition",
+    "FocusCondition",
+    "InputContext",
+    "Focus",
+    "KeyEvent",
+    "ThreadedAction",
+    "LaunchApplication",
+    "InputText",
+    "StartRecordingKeys",
+    "StopRecordingKeys",
+    "ToggleRecordingKeys",
+    "PlaybackRecordedKeys",
+    "ClipboardHistory",
+    "ChooserAction",
+    "MouseButtonClick",
+    "MouseButtonDown",
+    "MouseButtonUp",
+    "MouseHorizontalWheel",
+    "MouseMove",
+    "MouseWheel",
+    "MoveWindow",
+    "SnapWindow",
+    "ActivateWindow",
+    "ShowClipboardHistory",
+    "ShowClipboardSnippets",
+    "ShowClipboardTools",
+    "DateTimeSnippet",
+    "getLogger",
+    "Console",
+    "__version__",
+]

keyhac-2.0.0/keyhac/__main__.py

@@ -0,0 +1,4 @@
+from keyhac.main import main
+import sys
+
+sys.exit(main())