keybinds 1.3.2__tar.gz → 1.3.4__tar.gz

{keybinds-1.3.2 → keybinds-1.3.4}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: keybinds
-Version: 1.3.2
+Version: 1.3.4
 Summary: Flexible global keyboard & mouse hotkeys for Windows
 Author: echolane
 License: MIT License
@@ -55,7 +55,7 @@ Flexible global keyboard & mouse hotkeys for Windows.
 ![Python](https://img.shields.io/badge/python-3.7%2B-blue)
 ![Platform](https://img.shields.io/badge/platform-windows-lightgrey)
 ![License](https://img.shields.io/badge/license-MIT-green)
-![Status](https://img.shields.io/badge/status-active-success)
+![Status](https://img.shields.io/badge/status-maintenance-yellow)
 ![PyPI](https://img.shields.io/pypi/v/keybinds)
 
 **keybinds** is a Python library for global keyboard and mouse binds on Windows, with support for hotkeys, logical key binds, text matching, and text abbreviations.
@@ -194,18 +194,25 @@ Top-level helpers use the default hook. If you use multiple hooks, prefer `hook.
 
 ## Bind state and waiting
 
-All bind objects expose two small runtime helpers:
+All bind objects expose small runtime helpers:
 
 ```python
 if bind.is_pressed():
-    print("bind is currently active")
+    print("full chord is currently held")
+
+if bind.any_pressed():
+    print("at least one key/button of this bind is held")
+
+print(bind.pressed_keys())  # held VKs for this bind, or [button] for mouse
 
 bind.wait()          # wait until the bind fires
 bind.wait(0.5)       # wait up to 0.5s, returns True/False
 ```
 
-`is_pressed()` checks whether the bind is currently pressed.
-`wait(timeout=None)` blocks until the bind fires and returns `True`, or returns `False` on timeout.
+- `is_pressed()` — the full chord is held.  
+- `any_pressed()` — any key/button of this bind is held.  
+- `pressed_keys()` — those keys (VKs, or the mouse button).  
+- `wait(timeout=None)` — block until the bind fires (`False` on timeout).
 
 ---
 

{keybinds-1.3.2 → keybinds-1.3.4}/README.md

@@ -5,7 +5,7 @@ Flexible global keyboard & mouse hotkeys for Windows.
 ![Python](https://img.shields.io/badge/python-3.7%2B-blue)
 ![Platform](https://img.shields.io/badge/platform-windows-lightgrey)
 ![License](https://img.shields.io/badge/license-MIT-green)
-![Status](https://img.shields.io/badge/status-active-success)
+![Status](https://img.shields.io/badge/status-maintenance-yellow)
 ![PyPI](https://img.shields.io/pypi/v/keybinds)
 
 **keybinds** is a Python library for global keyboard and mouse binds on Windows, with support for hotkeys, logical key binds, text matching, and text abbreviations.
@@ -144,18 +144,25 @@ Top-level helpers use the default hook. If you use multiple hooks, prefer `hook.
 
 ## Bind state and waiting
 
-All bind objects expose two small runtime helpers:
+All bind objects expose small runtime helpers:
 
 ```python
 if bind.is_pressed():
-    print("bind is currently active")
+    print("full chord is currently held")
+
+if bind.any_pressed():
+    print("at least one key/button of this bind is held")
+
+print(bind.pressed_keys())  # held VKs for this bind, or [button] for mouse
 
 bind.wait()          # wait until the bind fires
 bind.wait(0.5)       # wait up to 0.5s, returns True/False
 ```
 
-`is_pressed()` checks whether the bind is currently pressed.
-`wait(timeout=None)` blocks until the bind fires and returns `True`, or returns `False` on timeout.
+- `is_pressed()` — the full chord is held.  
+- `any_pressed()` — any key/button of this bind is held.  
+- `pressed_keys()` — those keys (VKs, or the mouse button).  
+- `wait(timeout=None)` — block until the bind fires (`False` on timeout).
 
 ---
 

{keybinds-1.3.2 → keybinds-1.3.4}/keybinds/__init__.py

@@ -1,48 +1,48 @@
-import sys
-
-if sys.platform != "win32":
-    raise RuntimeError("keybinds works on Windows only")
-
-from . import winput
-
-from .types import (
-    Trigger,
-    SuppressPolicy,
-    ChordPolicy,
-    OrderPolicy,
-    FocusPolicy,
-    InjectedPolicy,
-    TextBoundaryPolicy,
-    TextBackspacePolicy,
-    OsKeyRepeatPolicy,
-    ReplacementPolicy,
-    Timing,
-    Constraints,
-    Checks,
-    BindConfig,
-    MouseButton,
-    MouseBindConfig,
-    LogicalConfig,
-    Callback,
-    Predicate,
-)
-
-
-from .bind import Bind, LogicalBind, TextAbbreviationBind, KeyboardBind, MouseBind, Hook, get_default_hook, set_default_hook, join, unbind
-from .decorators import bind_key, bind_logical, bind_text, add_abbreviation, bind_abbreviation, bind_mouse
-from . import presets
-
-from ._backend import reinstall_hooks, rehook
-
-from ._constants import register_key_token
-
-__version__ = "1.3.2"
-
-__all__ = [
-    "Trigger","SuppressPolicy","ChordPolicy","OrderPolicy","FocusPolicy","InjectedPolicy","TextBoundaryPolicy","TextBackspacePolicy","OsKeyRepeatPolicy","ReplacementPolicy",
-    "Timing","Constraints","Checks","BindConfig",
-    "MouseButton","MouseBindConfig","Callback","Predicate","LogicalConfig",
-    "Bind","LogicalBind","TextAbbreviationBind","KeyboardBind","MouseBind","Hook","get_default_hook","set_default_hook","join","unbind",
-    "bind_key","bind_logical","bind_text","add_abbreviation","bind_abbreviation","bind_mouse","presets","register_key_token","winput",
-    "reinstall_hooks","rehook"
-]
+import sys
+
+if sys.platform != "win32":
+    raise RuntimeError("keybinds works on Windows only")
+
+from . import winput
+
+from .types import (
+    Trigger,
+    SuppressPolicy,
+    ChordPolicy,
+    OrderPolicy,
+    FocusPolicy,
+    InjectedPolicy,
+    TextBoundaryPolicy,
+    TextBackspacePolicy,
+    OsKeyRepeatPolicy,
+    ReplacementPolicy,
+    Timing,
+    Constraints,
+    Checks,
+    BindConfig,
+    MouseButton,
+    MouseBindConfig,
+    LogicalConfig,
+    Callback,
+    Predicate,
+)
+
+
+from .bind import Bind, LogicalBind, TextAbbreviationBind, KeyboardBind, MouseBind, Hook, get_default_hook, set_default_hook, join, unbind
+from .decorators import bind_key, bind_logical, bind_text, add_abbreviation, bind_abbreviation, bind_mouse
+from . import presets
+
+from ._backend import reinstall_hooks, rehook
+
+from ._constants import register_key_token
+
+__version__ = "1.3.4"
+
+__all__ = [
+    "Trigger","SuppressPolicy","ChordPolicy","OrderPolicy","FocusPolicy","InjectedPolicy","TextBoundaryPolicy","TextBackspacePolicy","OsKeyRepeatPolicy","ReplacementPolicy",
+    "Timing","Constraints","Checks","BindConfig",
+    "MouseButton","MouseBindConfig","Callback","Predicate","LogicalConfig",
+    "Bind","LogicalBind","TextAbbreviationBind","KeyboardBind","MouseBind","Hook","get_default_hook","set_default_hook","join","unbind",
+    "bind_key","bind_logical","bind_text","add_abbreviation","bind_abbreviation","bind_mouse","presets","register_key_token","winput",
+    "reinstall_hooks","rehook"
+]

{keybinds-1.3.2 → keybinds-1.3.4}/keybinds/_backend.py

@@ -1,6 +1,7 @@
 # keybinds/_backend.py
 from __future__ import annotations
 
+import atexit
 import threading
 import weakref
 from traceback import print_exc
@@ -54,6 +55,8 @@ class _GlobalBackend:
         self._thread_id: Optional[int] = None
         self._thread_ready = threading.Event()
         self._state_lock = threading.RLock()
+        self._atexit_registered = False
+        self._shutdown_lock = threading.Lock()
 
     @classmethod
     def instance(cls) -> _GlobalBackend:
@@ -75,14 +78,20 @@ class _GlobalBackend:
                 stop_dispatcher()
             except Exception:
                 pass
+            try:
+                if not self._alive_hooks():
+                    self.shutdown()
+            except Exception:
+                pass
 
         with self._hooks_lock:
             self._hooks.append(weakref.ref(hook_obj, _on_hook_gc))
 
+        self._ensure_atexit()
         self._ensure_thread()
 
     def unregister(self, hook_obj) -> None:
-        """Unregister a Hook frontend."""
+        """Unregister a Hook frontend. Last hook tears down the backend."""
         with self._hooks_lock:
             new_list = []
             for r in self._hooks:
@@ -93,6 +102,42 @@ class _GlobalBackend:
                     continue
                 new_list.append(r)
             self._hooks = new_list
+            remaining = bool(new_list)
+        if not remaining:
+            self.shutdown()
+
+    def _ensure_atexit(self) -> None:
+        if self._atexit_registered:
+            return
+        atexit.register(_atexit_shutdown_backend)
+        self._atexit_registered = True
+
+    def shutdown(self) -> None:
+        """Remove LL hooks and ask the backend thread to exit. Idempotent.
+
+        Does not join the backend thread: Unhook already frees the input chain.
+        """
+        with self._shutdown_lock:
+            with self._hooks_lock:
+                thread_id = self._thread_id
+
+            self._unhook_now()
+
+            if thread_id is not None:
+                try:
+                    winput.post_thread_message(thread_id, winput.WM_QUIT, 0, 0)
+                except Exception:
+                    pass
+
+    def _unhook_now(self) -> None:
+        try:
+            winput.unhook_keyboard()
+        except Exception:
+            pass
+        try:
+            winput.unhook_mouse()
+        except Exception:
+            pass
 
     def reinstall_hooks(self) -> None:
         if not self._thread_started:
@@ -136,7 +181,8 @@ class _GlobalBackend:
 
     def _ensure_thread(self) -> None:
         with self._hooks_lock:
-            if self._thread_started:
+            t = self._thread
+            if t is not None and t.is_alive():
                 return
             self._thread_started = True
 
@@ -147,15 +193,7 @@ class _GlobalBackend:
 
     def _on_backend_message(self, msg) -> bool:
         if int(msg.message) == WM_KEYBINDS_REINSTALL:
-            try:
-                winput.unhook_keyboard()
-            except Exception:
-                pass
-            try:
-                winput.unhook_mouse()
-            except Exception:
-                pass
-
+            self._unhook_now()
             self._clear_pressed_state()
             self._reset_all_hook_runtime_states()
 
@@ -179,15 +217,7 @@ class _GlobalBackend:
         except Exception:
             print_exc()
         finally:
-            try:
-                winput.unhook_keyboard()
-            except Exception:
-                pass
-            try:
-                winput.unhook_mouse()
-            except Exception:
-                pass
-
+            self._unhook_now()
             self._clear_pressed_state()
             with self._hooks_lock:
                 self._thread_started = False
@@ -327,6 +357,16 @@ class _GlobalBackend:
         return flags
 
 
+def _atexit_shutdown_backend() -> None:
+    inst = _GlobalBackend._instance
+    if inst is None:
+        return
+    try:
+        inst.shutdown()
+    except Exception:
+        pass
+
+
 def reinstall_hooks() -> None:
     """
     Reinstall global keyboard/mouse hooks so keybinds is placed later