keybinds 0.0.1__py3-none-any.whl

keybinds/__init__.py

@@ -0,0 +1,42 @@
+import sys
+
+if sys.platform != "win32":
+    raise RuntimeError("keybinds works on Windows only")
+
+from importlib.metadata import version, PackageNotFoundError
+
+from . import winput
+
+from .types import (
+    Trigger,
+    SuppressPolicy,
+    ChordPolicy,
+    OrderPolicy,
+    Timing,
+    Constraints,
+    Checks,
+    BindConfig,
+    MouseButton,
+    MouseBindConfig,
+    Callback,
+    Predicate,
+)
+
+from .bind import Bind, MouseBind, Hook, get_default_hook, set_default_hook, join
+from .decorators import bind_key, bind_mouse
+from . import presets
+
+from ._constants import register_key_token
+
+try:
+    __version__ = version("keybinds")
+except PackageNotFoundError:
+    __version__ = "0.0.0"
+
+__all__ = [
+    "Trigger","SuppressPolicy","ChordPolicy","OrderPolicy",
+    "Timing","Constraints","Checks","BindConfig",
+    "MouseButton","MouseBindConfig","Callback","Predicate",
+    "Bind","MouseBind","Hook","get_default_hook","set_default_hook","join",
+    "bind_key","bind_mouse","presets","register_key_token","winput"
+]

keybinds/_backend.py

@@ -0,0 +1,244 @@
+# keybinds/_backend.py
+from __future__ import annotations
+
+import threading
+import weakref
+from traceback import print_exc
+from typing import Optional, List
+
+from . import winput
+
+from ._constants import (
+    WM_KEYDOWN, WM_SYSKEYDOWN, WM_KEYUP, WM_SYSKEYUP,
+    WM_LBUTTONDOWN, WM_LBUTTONUP,
+    WM_RBUTTONDOWN, WM_RBUTTONUP,
+    WM_MBUTTONDOWN, WM_MBUTTONUP,
+    WM_XBUTTONDOWN, WM_XBUTTONUP,
+)
+from .types import MouseButton
+from ._state import InputState
+
+
+class _GlobalBackend:
+    """
+    One per-process backend:
+      - installs winput hooks once
+      - runs wait_messages() once
+      - dispatches events to all active Hook instances
+    """
+
+    _instance: Optional["_GlobalBackend"] = None
+    _instance_lock = threading.Lock()
+
+    def __init__(self) -> None:
+        self._hooks: List[weakref.ReferenceType] = []
+        self._hooks_lock = threading.Lock()
+
+        self._thread: Optional[threading.Thread] = None
+        self._thread_started = False
+
+        # physical only
+        self._pressed_keys: set[int] = set()
+        self._pressed_mouse: set[MouseButton] = set()
+
+        # physical + injected
+        self._pressed_keys_all: set[int] = set()
+        self._pressed_mouse_all: set[MouseButton] = set()
+
+        # injected only
+        self._pressed_keys_injected: set[int] = set()
+        self._pressed_mouse_injected: set[MouseButton] = set()
+
+    @classmethod
+    def instance(cls) -> _GlobalBackend:
+        with cls._instance_lock:
+            if cls._instance is None:
+                cls._instance = _GlobalBackend()
+            return cls._instance
+
+    # -------------------------
+    # lifecycle
+    # -------------------------
+
+    def register(self, hook_obj) -> None:
+        """Register a Hook frontend and ensure backend thread is running."""
+        with self._hooks_lock:
+            self._hooks.append(weakref.ref(hook_obj))
+
+        self._ensure_thread()
+
+    def unregister(self, hook_obj) -> None:
+        """Unregister a Hook frontend. (We keep backend thread alive; optional stop can be added later.)"""
+        with self._hooks_lock:
+            new_list = []
+            for r in self._hooks:
+                o = r()
+                if o is None:
+                    continue
+                if o is hook_obj:
+                    continue
+                new_list.append(r)
+            self._hooks = new_list
+
+    def _ensure_thread(self) -> None:
+        with self._hooks_lock:
+            if self._thread_started:
+                return
+            self._thread_started = True
+
+        t = threading.Thread(target=self._thread_main, name="keybinds-backend", daemon=True)
+        self._thread = t
+        t.start()
+
+    def _thread_main(self) -> None:
+        # Install hooks and pump messages on the SAME thread.
+        try:
+            winput.hook_keyboard(self._on_keyboard)
+            winput.hook_mouse(self._on_mouse)
+            winput.wait_messages()
+        except Exception:
+            # If something goes wrong, try to unhook to restore input.
+            try:
+                winput.unhook_keyboard()
+            except Exception:
+                pass
+            try:
+                winput.unhook_mouse()
+            except Exception:
+                pass
+
+    # -------------------------
+    # dispatch
+    # -------------------------
+
+    def _alive_hooks(self) -> list:
+        """Return strong refs to currently alive Hook objects."""
+        out = []
+        with self._hooks_lock:
+            new_refs = []
+            for r in self._hooks:
+                o = r()
+                if o is None:
+                    continue
+                out.append(o)
+                new_refs.append(r)
+            self._hooks = new_refs
+        return out
+
+    def _on_keyboard(self, event: winput.KeyboardEvent) -> int:
+        vk = int(event.vkCode)
+        is_down = event.action in (WM_KEYDOWN, WM_SYSKEYDOWN)
+        is_up = event.action in (WM_KEYUP, WM_SYSKEYUP)
+
+        injected = bool(getattr(event, "injected", False))
+
+        # Choose domain for repeat detection on KEYDOWN only
+        if is_down:
+            base = self._pressed_keys_injected if injected else self._pressed_keys
+            was_down = vk in base
+        else:
+            was_down = False
+
+        if is_down:
+            self._pressed_keys_all.add(vk)
+        elif is_up:
+            self._pressed_keys_all.discard(vk)
+
+        if is_down:
+            if injected:
+                self._pressed_keys_injected.add(vk)
+            else:
+                self._pressed_keys.add(vk)
+
+        elif is_up:
+            self._pressed_keys.discard(vk)
+            self._pressed_keys_injected.discard(vk)
+
+        # Mark OS auto-repeat (keydown while already pressed in that domain)
+        try:
+            setattr(event, "_sb_is_repeat", bool(is_down and was_down))
+        except Exception:
+            pass
+
+        state = InputState(
+            self._pressed_keys,
+            self._pressed_mouse,
+            self._pressed_keys_all,
+            self._pressed_mouse_all,
+            self._pressed_keys_injected,
+            self._pressed_mouse_injected,
+        )
+
+        flags = winput.WP_CONTINUE
+        for h in self._alive_hooks():
+            try:
+                flags |= h._handle_keyboard_event(event, state)
+            except Exception:
+                print_exc()
+        return flags
+
+    def _on_mouse(self, event: winput.MouseEvent) -> int:
+        # Hard filter: only handle button up/down (everything else is noise).
+        act = event.action
+        if act not in (
+            WM_LBUTTONDOWN, WM_LBUTTONUP,
+            WM_RBUTTONDOWN, WM_RBUTTONUP,
+            WM_MBUTTONDOWN, WM_MBUTTONUP,
+            WM_XBUTTONDOWN, WM_XBUTTONUP,
+        ):
+            return winput.WP_CONTINUE
+
+        injected = bool(getattr(event, "injected", False))
+
+        def _apply(target: set[MouseButton]) -> None:
+            if act == WM_LBUTTONDOWN:
+                target.add(MouseButton.LEFT)
+            elif act == WM_LBUTTONUP:
+                target.discard(MouseButton.LEFT)
+            elif act == WM_RBUTTONDOWN:
+                target.add(MouseButton.RIGHT)
+            elif act == WM_RBUTTONUP:
+                target.discard(MouseButton.RIGHT)
+            elif act == WM_MBUTTONDOWN:
+                target.add(MouseButton.MIDDLE)
+            elif act == WM_MBUTTONUP:
+                target.discard(MouseButton.MIDDLE)
+            elif act == WM_XBUTTONDOWN:
+                which = int(getattr(event, "additional_data", 0) or 0)
+                if which == 1:
+                    target.add(MouseButton.X1)
+                elif which == 2:
+                    target.add(MouseButton.X2)
+            elif act == WM_XBUTTONUP:
+                which = int(getattr(event, "additional_data", 0) or 0)
+                if which == 1:
+                    target.discard(MouseButton.X1)
+                elif which == 2:
+                    target.discard(MouseButton.X2)
+
+        # Update ALL-state always
+        _apply(self._pressed_mouse_all)
+
+        # Update injected-only state only for injected events
+        if injected:
+            _apply(self._pressed_mouse_injected)
+        else:
+            # Update PHYSICAL-state only for non-injected events
+            _apply(self._pressed_mouse)
+
+        state = InputState(
+            self._pressed_keys,
+            self._pressed_mouse,
+            self._pressed_keys_all,
+            self._pressed_mouse_all,
+            self._pressed_keys_injected,
+            self._pressed_mouse_injected,
+        )
+
+        flags = winput.WP_CONTINUE
+        for h in self._alive_hooks():
+            try:
+                flags |= h._handle_mouse_event(event, state)
+            except Exception:
+                pass
+        return flags

keybinds/_constants.py

@@ -0,0 +1,124 @@
+from __future__ import annotations
+
+from typing import Dict, Set
+
+from . import winput
+
+# Common VK codes (fallbacks); winput also exposes VK_* constants.
+VK_SHIFT = getattr(winput, "VK_SHIFT", 0x10)
+VK_CONTROL = getattr(winput, "VK_CONTROL", 0x11)
+VK_MENU = getattr(winput, "VK_MENU", 0x12)  # ALT
+VK_LSHIFT = getattr(winput, "VK_LSHIFT", 0xA0)
+VK_RSHIFT = getattr(winput, "VK_RSHIFT", 0xA1)
+VK_LCONTROL = getattr(winput, "VK_LCONTROL", 0xA2)
+VK_RCONTROL = getattr(winput, "VK_RCONTROL", 0xA3)
+VK_LMENU = getattr(winput, "VK_LMENU", 0xA4)
+VK_RMENU = getattr(winput, "VK_RMENU", 0xA5)
+VK_LWIN = getattr(winput, "VK_LWIN", 0x5B)
+VK_RWIN = getattr(winput, "VK_RWIN", 0x5C)
+
+# Mouse wParams
+WM_LBUTTONDOWN = winput.WM_LBUTTONDOWN
+WM_LBUTTONUP = winput.WM_LBUTTONUP
+WM_RBUTTONDOWN = winput.WM_RBUTTONDOWN
+WM_RBUTTONUP = winput.WM_RBUTTONUP
+WM_MBUTTONDOWN = winput.WM_MBUTTONDOWN
+WM_MBUTTONUP = winput.WM_MBUTTONUP
+WM_XBUTTONDOWN = winput.WM_XBUTTONDOWN
+WM_XBUTTONUP = winput.WM_XBUTTONUP
+
+WM_KEYDOWN = winput.WM_KEYDOWN
+WM_KEYUP = winput.WM_KEYUP
+WM_SYSKEYDOWN = winput.WM_SYSKEYDOWN
+WM_SYSKEYUP = winput.WM_SYSKEYUP
+
+# mouse move/wheel constants may exist; values are stable win32.
+WM_MOUSEMOVE = getattr(winput, "WM_MOUSEMOVE", 0x0200)
+WM_MOUSEWHEEL = getattr(winput, "WM_MOUSEWHEEL", 0x020A)
+WM_MOUSEHWHEEL = getattr(winput, "WM_MOUSEHWHEEL", 0x020E)
+
+
+_MOD_GROUPS: Dict[str, Set[int]] = {
+    "shift": {VK_SHIFT, VK_LSHIFT, VK_RSHIFT},
+    "ctrl": {VK_CONTROL, VK_LCONTROL, VK_RCONTROL},
+    "control": {VK_CONTROL, VK_LCONTROL, VK_RCONTROL},
+    "alt": {VK_MENU, VK_LMENU, VK_RMENU},
+    "menu": {VK_MENU, VK_LMENU, VK_RMENU},
+    "win": {VK_LWIN, VK_RWIN},
+    "lwin": {VK_LWIN},
+    "rwin": {VK_RWIN},
+}
+
+
+SPECIAL_KEYS: Dict[str, int] = {
+    "esc": getattr(winput, "VK_ESCAPE", 0x1B),
+    "escape": getattr(winput, "VK_ESCAPE", 0x1B),
+    "enter": getattr(winput, "VK_RETURN", 0x0D),
+    "return": getattr(winput, "VK_RETURN", 0x0D),
+    "tab": getattr(winput, "VK_TAB", 0x09),
+    "space": getattr(winput, "VK_SPACE", 0x20),
+    "backspace": getattr(winput, "VK_BACK", 0x08),
+    "delete": getattr(winput, "VK_DELETE", 0x2E),
+    "del": getattr(winput, "VK_DELETE", 0x2E),
+    "insert": getattr(winput, "VK_INSERT", 0x2D),
+    "home": getattr(winput, "VK_HOME", 0x24),
+    "end": getattr(winput, "VK_END", 0x23),
+    "pgup": getattr(winput, "VK_PRIOR", 0x21),
+    "pageup": getattr(winput, "VK_PRIOR", 0x21),
+    "pgdn": getattr(winput, "VK_NEXT", 0x22),
+    "pagedown": getattr(winput, "VK_NEXT", 0x22),
+    "up": getattr(winput, "VK_UP", 0x26),
+    "down": getattr(winput, "VK_DOWN", 0x28),
+    "left": getattr(winput, "VK_LEFT", 0x25),
+    "right": getattr(winput, "VK_RIGHT", 0x27),
+    "volumeup": getattr(winput, "VK_VOLUMEUP", 0xAF),
+    "volumedown": getattr(winput, "VK_VOLUMEDOWN", 0xAE),
+    "mute": getattr(winput, "VK_VOLUMEMUTE", 0xAD),
+}
+
+SPECIAL_KEYS.update({
+    "`": getattr(winput, "VK_OEM_3", 0xC0),        # `~
+    "backtick": getattr(winput, "VK_OEM_3", 0xC0),
+    "grave": getattr(winput, "VK_OEM_3", 0xC0),
+    "tilde": getattr(winput, "VK_OEM_3", 0xC0),
+
+    "-": getattr(winput, "VK_OEM_MINUS", 0xBD),   # -_
+    "=": getattr(winput, "VK_OEM_PLUS", 0xBB),    # =+
+    "[": getattr(winput, "VK_OEM_4", 0xDB),       # [{
+    "]": getattr(winput, "VK_OEM_6", 0xDD),       # ]}
+    "\\": getattr(winput, "VK_OEM_5", 0xDC),      # \|
+    ";": getattr(winput, "VK_OEM_1", 0xBA),       # ;:
+    "'": getattr(winput, "VK_OEM_7", 0xDE),       # '"
+    ",": getattr(winput, "VK_OEM_COMMA", 0xBC),   # ,<
+    ".": getattr(winput, "VK_OEM_PERIOD", 0xBE),  # .>
+    "/": getattr(winput, "VK_OEM_2", 0xBF),       # /?
+})
+
+for i in range(1, 25):
+    SPECIAL_KEYS[f"f{i}"] = getattr(winput, f"VK_F{i}", 0x70 + (i - 1))
+
+
+def is_modifier_vk(vk: int) -> bool:
+    return vk in (
+        VK_SHIFT,
+        VK_LSHIFT,
+        VK_RSHIFT,
+        VK_CONTROL,
+        VK_LCONTROL,
+        VK_RCONTROL,
+        VK_MENU,
+        VK_LMENU,
+        VK_RMENU,
+        VK_LWIN,
+        VK_RWIN,
+    )
+
+
+def register_key_token(name: str, vk: int) -> None:
+    """
+    Register a custom key token at runtime.
+
+    Example:
+        register_key_token("`", 0xC0)
+    """
+    SPECIAL_KEYS[name.lower()] = vk

keybinds/_dispatcher.py

@@ -0,0 +1,40 @@
+from __future__ import annotations
+
+import queue
+import threading
+from traceback import print_exc
+from typing import Callable, List, Optional
+
+
+class _CallbackDispatcher:
+    """Executes user callbacks on a small worker pool.
+
+    Critical for low-level hooks: do *not* create a new Thread per event.
+    """
+
+    def __init__(self, workers: int = 1) -> None:
+        self._q: "queue.SimpleQueue[Optional[Callable[[], None]]]" = queue.SimpleQueue()
+        self._threads: List[threading.Thread] = []
+        self._workers = max(1, int(workers))
+        for i in range(self._workers):
+            t = threading.Thread(target=self._worker, name=f"bind-worker-{i}", daemon=True)
+            t.start()
+            self._threads.append(t)
+
+    def submit(self, fn: Callable[[], None]) -> None:
+        self._q.put(fn)
+
+    def stop(self) -> None:
+        for _ in range(self._workers):
+            self._q.put(None)
+
+    def _worker(self) -> None:
+        while True:
+            fn = self._q.get()
+            if fn is None:
+                return
+            try:
+                fn()
+            except Exception:
+                # never let user callbacks kill the worker
+                print_exc()

keybinds/_hook.py

@@ -0,0 +1,215 @@
+from __future__ import annotations
+
+import signal
+import threading
+from contextlib import contextmanager
+from typing import Callable, Optional, Union, Generator
+
+from ._backend import _GlobalBackend
+from ._dispatcher import _CallbackDispatcher
+from ._keyboard import Bind
+from ._mouse import MouseBind
+from .types import BindConfig, MouseBindConfig, MouseButton
+
+_default_hook: Optional[Hook] = None
+
+
+def get_default_hook() -> Hook:
+    global _default_hook
+    if _default_hook is None:
+        _default_hook = Hook()
+    return _default_hook
+
+
+def set_default_hook(hook: Hook) -> None:
+    global _default_hook
+    _default_hook = hook
+
+
+def join(hook: Optional[Hook] = None) -> None:
+    """Block until the hook is stopped.
+
+    If hook is None, the default hook will be used.
+    """
+
+    if hook is None:
+        hook = get_default_hook()
+
+    def handler(sig, frame):
+        hook.stop()
+
+    signal.signal(signal.SIGINT, handler)
+
+    try:
+        hook.wait()
+    finally:
+        hook.close()
+
+
+class Hook:
+    def __init__(
+        self,
+        *,
+        callback_workers: int = 1,
+        default_config: Optional[BindConfig] = None,
+        default_mouse_config: Optional[MouseBindConfig] = None,
+    ) -> None:
+        self._lock = threading.Lock()
+        self._stop_event = threading.Event()
+
+        self._pause_count = 0
+        self._paused = False
+
+        self.default_config = default_config
+        self.default_mouse_config = default_mouse_config
+
+        self._dispatcher = _CallbackDispatcher(workers=callback_workers)
+
+        # binds live in this frontend
+        self._keyboard_binds: list[Bind] = []
+        self._mouse_binds: list[MouseBind] = []
+
+        # snapshots used by backend hot path (tuples are cheap to iterate)
+        self._keyboard_snapshot: tuple[Bind, ...] = ()
+        self._mouse_snapshot: tuple[MouseBind, ...] = ()
+
+        # Attach to global backend (installs hooks once)
+        _GlobalBackend.instance().register(self)
+
+    # -------------------------
+    # public API
+    # -------------------------
+
+    def bind(self, expr: str, callback: Callable[[], None], *, config: Optional[BindConfig] = None, hwnd=None) -> Bind:
+        cfg = config or self.default_config or BindConfig()
+        b = Bind(expr, callback, config=cfg, hwnd=hwnd, dispatch=self._dispatcher.submit)
+        with self._lock:
+            self._keyboard_binds.append(b)
+            self._keyboard_snapshot = tuple(self._keyboard_binds)
+        return b
+
+    def bind_mouse(self, button: Union[MouseButton, str], callback: Callable[[], None], *, config: Optional[MouseBindConfig] = None, hwnd=None) -> MouseBind:
+        cfg = config or self.default_mouse_config or MouseBindConfig()
+        b = MouseBind(button, callback, config=cfg, hwnd=hwnd, dispatch=self._dispatcher.submit)
+        with self._lock:
+            self._mouse_binds.append(b)
+            self._mouse_snapshot = tuple(self._mouse_binds)
+        return b
+
+    def unbind(self, b: Bind) -> None:
+        with self._lock:
+            try:
+                self._keyboard_binds.remove(b)
+            except ValueError:
+                return
+            self._keyboard_snapshot = tuple(self._keyboard_binds)
+
+    def unbind_mouse(self, b: MouseBind) -> None:
+        with self._lock:
+            try:
+                self._mouse_binds.remove(b)
+            except ValueError:
+                return
+            self._mouse_snapshot = tuple(self._mouse_binds)
+
+    def pause(self) -> None:
+        """Pause the hook (no callbacks will be called until resume() is called).
+
+        Useful for temporarily disabling the hook while it's running.
+        """
+        with self._lock:
+            self._pause_count += 1
+            self._paused = True
+
+    def resume(self) -> None:
+        """Resume the hook (callbacks will be called again after calling pause()).
+
+        Useful for re-enabling the hook after temporarily disabling it with pause().
+        """
+        with self._lock:
+            if self._pause_count == 0:
+                return
+            self._pause_count -= 1
+            if self._pause_count == 0:
+                self._paused = False
+
+    def is_paused(self) -> bool:
+        """Get whether the hook is currently paused.
+
+        Returns True if the hook is paused, False otherwise.
+        """
+        return self._paused
+
+    @contextmanager
+    def paused(self) -> Generator[None, None, None]:
+        """Pause and resume the hook using the with statement.
+
+        Example:
+            >>> with hook.paused():
+                # do something that requires the hook to be paused
+        """
+        self.pause()
+        try:
+            yield
+        finally:
+            self.resume()
+
+    def stop(self) -> None:
+        """Signal to stop waiting in wait().
+
+        After calling stop(), wait() will return True as soon as possible.
+        """
+        self._stop_event.set()
+
+    def wait(self, timeout: Optional[float] = None) -> bool:
+        """Wait for stop() to be called.
+
+        If timeout is not None, wait up to that amount of time (in seconds) for stop() to be called.
+        Returns True if stop() was called, False otherwise.
+        """
+        if timeout is not None:
+            return self._stop_event.wait(timeout)
+
+        try:
+            while not self._stop_event.wait(0.2):
+                pass
+            return True
+        except KeyboardInterrupt:
+            return True
+
+    def join(self) -> None:
+        """Block until the hook is stopped."""
+        join(self)
+
+    def close(self) -> None:
+        # just detach this frontend; backend keeps running if others exist
+        _GlobalBackend.instance().unregister(self)
+        self._dispatcher.stop()
+
+    # -------------------------
+    # called by backend
+    # -------------------------
+
+    def _handle_keyboard_event(self, event, state) -> int:
+        if self._paused:
+            return 0
+
+        snap = self._keyboard_snapshot
+        if not snap:
+            return 0  # winput.WP_CONTINUE (backend ORs anyway)
+        flags = 0
+        for b in snap:
+            flags |= b.handle(event, state)
+        return flags
+
+    def _handle_mouse_event(self, event, state) -> int:
+        if self._paused:
+            return 0
+
+        snap = self._mouse_snapshot
+        if not snap:
+            return 0
+        flags = 0
+        for b in snap:
+            flags |= b.handle(event, state)
+        return flags