keybinds 1.3.4__tar.gz → 1.3.5__tar.gz

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

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: keybinds
-Version: 1.3.4
+Version: 1.3.5
 Summary: Flexible global keyboard & mouse hotkeys for Windows
 Author: echolane
 License: MIT License
@@ -55,14 +55,14 @@ 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-maintenance-yellow)
+![Status](https://img.shields.io/badge/status-active-success)
 ![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.
 
 It supports:
 - global keyboard binds: single keys, chords (`ctrl+e`), and sequences (`g,k,i`)
-- global mouse binds: `left`, `right`, `middle`, `x1`, `x2`
+- global mouse binds: `left`, `right`, `middle`, `x1`, `x2`, `wheel_up`, `wheel_down`
 - rich triggers: press, release, click, hold, repeat, double tap, and sequence
 - suppression and injected-input policies
 - sync and async callbacks
@@ -108,7 +108,7 @@ Stable decorator helpers:
 
 ```python
 import keybinds
-from keybinds.decorators import bind_key, bind_mouse
+from keybinds import bind_key, bind_mouse
 
 @bind_key("ctrl+e")
 def inventory():
@@ -127,7 +127,7 @@ Decorators use the default hook automatically.
 
 ```python
 import keybinds
-from keybinds.decorators import bind_logical, bind_text, bind_abbreviation
+from keybinds import bind_logical, bind_text, bind_abbreviation
 
 # Experimental API: may change in future releases.
 
@@ -227,7 +227,7 @@ hook.bind("ctrl+e", lambda: print("Pressed"))
 ### Release
 
 ```python
-from keybinds.types import BindConfig, Trigger
+from keybinds import BindConfig, Trigger
 
 hook.bind(
     "ctrl+t",
@@ -239,7 +239,7 @@ hook.bind(
 ### Hold
 
 ```python
-from keybinds.types import BindConfig, Trigger, Timing
+from keybinds import BindConfig, Trigger, Timing
 
 hook.bind(
     "h",
@@ -254,7 +254,7 @@ hook.bind(
 ### Repeat (auto-fire while held)
 
 ```python
-from keybinds.types import BindConfig, Trigger, Timing
+from keybinds import BindConfig, Trigger, Timing
 
 hook.bind(
     "space",
@@ -269,7 +269,7 @@ hook.bind(
 ### Double tap
 
 ```python
-from keybinds.types import BindConfig, Trigger
+from keybinds import BindConfig, Trigger
 
 hook.bind(
     "g",
@@ -281,7 +281,7 @@ hook.bind(
 ### Sequence
 
 ```python
-from keybinds.types import BindConfig, Trigger
+from keybinds import BindConfig, Trigger
 
 hook.bind(
     "g,k,i",
@@ -295,7 +295,7 @@ hook.bind(
 ## Mouse Basics
 
 ```python
-from keybinds.types import MouseBindConfig, Trigger
+from keybinds import MouseBindConfig, Trigger
 
 hook.bind_mouse(
     "middle",
@@ -312,12 +312,28 @@ Mouse buttons:
 - `x1`
 - `x2`
 
+Mouse wheel (only `Trigger.ON_PRESS`):
+
+- `wheel_up` / `wheel_down`
+- `wheel_left` / `wheel_right` — horizontal (many mice never emit these)
+
+Wheel units accumulate until `MouseBindConfig.wheel_delta` (default `120`, the Win32 notch). Smaller wheel steps add up until they reach `wheel_delta`. Scrolling the other way clears the leftover amount.
+
+```python
+hook.bind_mouse("wheel_up", lambda: print("scroll up"))
+hook.bind_mouse(
+    "wheel_down",
+    lambda: print("scroll down"),
+    config=MouseBindConfig(wheel_delta=40),
+)
+```
+
 ---
 
 ## Suppression (block input from apps)
 
 ```python
-from keybinds.types import BindConfig, SuppressPolicy
+from keybinds import BindConfig, SuppressPolicy
 
 hook.bind(
     "ctrl+r",
@@ -341,7 +357,7 @@ Policies:
 Control how injected input (macros, `SendInput`, automation tools) is handled:
 
 ```python
-from keybinds.types import BindConfig, InjectedPolicy
+from keybinds import BindConfig, InjectedPolicy
 
 hook.bind(
     "f1",
@@ -361,7 +377,7 @@ Policies:
 ## Strict Chords
 
 ```python
-from keybinds.types import BindConfig, Constraints, ChordPolicy
+from keybinds import BindConfig, Constraints, ChordPolicy
 
 hook.bind(
     "ctrl+shift+u",
@@ -397,8 +413,7 @@ Callbacks may be `async def`. If a callback returns an awaitable, **keybinds** s
 
 ```python
 import asyncio
-from keybinds import Hook
-from keybinds.decorators import bind_key
+from keybinds import Hook, bind_key
 
 hook = Hook()
 

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

@@ -5,14 +5,14 @@ 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-maintenance-yellow)
+![Status](https://img.shields.io/badge/status-active-success)
 ![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.
 
 It supports:
 - global keyboard binds: single keys, chords (`ctrl+e`), and sequences (`g,k,i`)
-- global mouse binds: `left`, `right`, `middle`, `x1`, `x2`
+- global mouse binds: `left`, `right`, `middle`, `x1`, `x2`, `wheel_up`, `wheel_down`
 - rich triggers: press, release, click, hold, repeat, double tap, and sequence
 - suppression and injected-input policies
 - sync and async callbacks
@@ -58,7 +58,7 @@ Stable decorator helpers:
 
 ```python
 import keybinds
-from keybinds.decorators import bind_key, bind_mouse
+from keybinds import bind_key, bind_mouse
 
 @bind_key("ctrl+e")
 def inventory():
@@ -77,7 +77,7 @@ Decorators use the default hook automatically.
 
 ```python
 import keybinds
-from keybinds.decorators import bind_logical, bind_text, bind_abbreviation
+from keybinds import bind_logical, bind_text, bind_abbreviation
 
 # Experimental API: may change in future releases.
 
@@ -177,7 +177,7 @@ hook.bind("ctrl+e", lambda: print("Pressed"))
 ### Release
 
 ```python
-from keybinds.types import BindConfig, Trigger
+from keybinds import BindConfig, Trigger
 
 hook.bind(
     "ctrl+t",
@@ -189,7 +189,7 @@ hook.bind(
 ### Hold
 
 ```python
-from keybinds.types import BindConfig, Trigger, Timing
+from keybinds import BindConfig, Trigger, Timing
 
 hook.bind(
     "h",
@@ -204,7 +204,7 @@ hook.bind(
 ### Repeat (auto-fire while held)
 
 ```python
-from keybinds.types import BindConfig, Trigger, Timing
+from keybinds import BindConfig, Trigger, Timing
 
 hook.bind(
     "space",
@@ -219,7 +219,7 @@ hook.bind(
 ### Double tap
 
 ```python
-from keybinds.types import BindConfig, Trigger
+from keybinds import BindConfig, Trigger
 
 hook.bind(
     "g",
@@ -231,7 +231,7 @@ hook.bind(
 ### Sequence
 
 ```python
-from keybinds.types import BindConfig, Trigger
+from keybinds import BindConfig, Trigger
 
 hook.bind(
     "g,k,i",
@@ -245,7 +245,7 @@ hook.bind(
 ## Mouse Basics
 
 ```python
-from keybinds.types import MouseBindConfig, Trigger
+from keybinds import MouseBindConfig, Trigger
 
 hook.bind_mouse(
     "middle",
@@ -262,12 +262,28 @@ Mouse buttons:
 - `x1`
 - `x2`
 
+Mouse wheel (only `Trigger.ON_PRESS`):
+
+- `wheel_up` / `wheel_down`
+- `wheel_left` / `wheel_right` — horizontal (many mice never emit these)
+
+Wheel units accumulate until `MouseBindConfig.wheel_delta` (default `120`, the Win32 notch). Smaller wheel steps add up until they reach `wheel_delta`. Scrolling the other way clears the leftover amount.
+
+```python
+hook.bind_mouse("wheel_up", lambda: print("scroll up"))
+hook.bind_mouse(
+    "wheel_down",
+    lambda: print("scroll down"),
+    config=MouseBindConfig(wheel_delta=40),
+)
+```
+
 ---
 
 ## Suppression (block input from apps)
 
 ```python
-from keybinds.types import BindConfig, SuppressPolicy
+from keybinds import BindConfig, SuppressPolicy
 
 hook.bind(
     "ctrl+r",
@@ -291,7 +307,7 @@ Policies:
 Control how injected input (macros, `SendInput`, automation tools) is handled:
 
 ```python
-from keybinds.types import BindConfig, InjectedPolicy
+from keybinds import BindConfig, InjectedPolicy
 
 hook.bind(
     "f1",
@@ -311,7 +327,7 @@ Policies:
 ## Strict Chords
 
 ```python
-from keybinds.types import BindConfig, Constraints, ChordPolicy
+from keybinds import BindConfig, Constraints, ChordPolicy
 
 hook.bind(
     "ctrl+shift+u",
@@ -347,8 +363,7 @@ Callbacks may be `async def`. If a callback returns an awaitable, **keybinds** s
 
 ```python
 import asyncio
-from keybinds import Hook
-from keybinds.decorators import bind_key
+from keybinds import Hook, bind_key
 
 hook = Hook()
 

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

@@ -21,6 +21,8 @@ from .types import (
     Checks,
     BindConfig,
     MouseButton,
+    WHEEL_BUTTONS,
+    is_wheel_button,
     MouseBindConfig,
     LogicalConfig,
     Callback,
@@ -36,12 +38,12 @@ from ._backend import reinstall_hooks, rehook
 
 from ._constants import register_key_token
 
-__version__ = "1.3.4"
+__version__ = "1.3.5"
 
 __all__ = [
     "Trigger","SuppressPolicy","ChordPolicy","OrderPolicy","FocusPolicy","InjectedPolicy","TextBoundaryPolicy","TextBackspacePolicy","OsKeyRepeatPolicy","ReplacementPolicy",
     "Timing","Constraints","Checks","BindConfig",
-    "MouseButton","MouseBindConfig","Callback","Predicate","LogicalConfig",
+    "MouseButton","WHEEL_BUTTONS","is_wheel_button","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.4 → keybinds-1.3.5}/keybinds/_backend.py

@@ -15,6 +15,8 @@ from ._constants import (
     WM_RBUTTONDOWN, WM_RBUTTONUP,
     WM_MBUTTONDOWN, WM_MBUTTONUP,
     WM_XBUTTONDOWN, WM_XBUTTONUP,
+    MOUSE_BUTTON_ACTIONS,
+    MOUSE_WHEEL_ACTIONS,
 )
 from .types import MouseButton
 from ._state import InputState
@@ -291,14 +293,22 @@ class _GlobalBackend:
         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,
-        ):
+
+        # Wheel is a pulse, not a pressed button. Dispatch without touching
+        # pressed_mouse so hold/is_pressed for real buttons stay correct.
+        if act in MOUSE_WHEEL_ACTIONS:
+            state = self.current_state_snapshot()
+            flags = winput.WP_CONTINUE
+            for h in self._alive_hooks():
+                try:
+                    flags |= h._handle_mouse_event(event, state)
+                except Exception:
+                    print_exc()
+            return flags
+
+        # Hard filter: only handle button up/down (move is noise).
+        if act not in MOUSE_BUTTON_ACTIONS:
             return winput.WP_CONTINUE
 
         injected = bool(getattr(event, "injected", False))

{keybinds-1.3.4 → keybinds-1.3.5}/keybinds/_constants.py

@@ -40,6 +40,15 @@ WM_SYSKEYUP = winput.WM_SYSKEYUP
 WM_MOUSEMOVE = getattr(winput, "WM_MOUSEMOVE", 0x0200)
 WM_MOUSEWHEEL = getattr(winput, "WM_MOUSEWHEEL", 0x020A)
 WM_MOUSEHWHEEL = getattr(winput, "WM_MOUSEHWHEEL", 0x020E)
+WHEEL_DELTA = getattr(winput, "WHEEL_DELTA", 120)
+
+MOUSE_BUTTON_ACTIONS = frozenset({
+    WM_LBUTTONDOWN, WM_LBUTTONUP,
+    WM_RBUTTONDOWN, WM_RBUTTONUP,
+    WM_MBUTTONDOWN, WM_MBUTTONUP,
+    WM_XBUTTONDOWN, WM_XBUTTONUP,
+})
+MOUSE_WHEEL_ACTIONS = frozenset({WM_MOUSEWHEEL, WM_MOUSEHWHEEL})
 
 KEYEVENTF_KEYUP = getattr(winput, "KEYEVENTF_KEYUP", 0x0002)
 KEYEVENTF_UNICODE = getattr(winput, "KEYEVENTF_UNICODE", 0x0004)

{keybinds-1.3.4 → keybinds-1.3.5}/keybinds/_mouse.py

@@ -6,12 +6,22 @@ from typing import Callable, Optional, Union, Tuple
 
 from . import winput
 
-from .types import Callback, MouseBindConfig, MouseButton, SuppressPolicy, InjectedPolicy, Trigger
+from .types import (
+    Callback,
+    MouseBindConfig,
+    MouseButton,
+    SuppressPolicy,
+    InjectedPolicy,
+    Trigger,
+    is_wheel_button,
+)
 from ._constants import (
     WM_LBUTTONDOWN, WM_LBUTTONUP,
     WM_RBUTTONDOWN, WM_RBUTTONUP,
     WM_MBUTTONDOWN, WM_MBUTTONUP,
     WM_XBUTTONDOWN, WM_XBUTTONUP,
+    WM_MOUSEWHEEL, WM_MOUSEHWHEEL,
+    MOUSE_WHEEL_ACTIONS,
 )
 from .diagnostics import _DiagnosticsManager, _EventTrace
 from ._base_bind import BaseBind
@@ -22,7 +32,7 @@ def _normalize_mouse_button(btn: object) -> MouseButton:
     if isinstance(btn, MouseButton):
         return btn
     if isinstance(btn, str):
-        s = btn.strip().lower()
+        s = btn.strip().lower().replace("-", "_")
         aliases = {
             "left": MouseButton.LEFT,
             "lmb": MouseButton.LEFT,
@@ -34,6 +44,20 @@ def _normalize_mouse_button(btn: object) -> MouseButton:
             "mouse4": MouseButton.X1,
             "x2": MouseButton.X2,
             "mouse5": MouseButton.X2,
+            "wheelup": MouseButton.WHEEL_UP,
+            "wheel_up": MouseButton.WHEEL_UP,
+            "scrollup": MouseButton.WHEEL_UP,
+            "scroll_up": MouseButton.WHEEL_UP,
+            "wheeldown": MouseButton.WHEEL_DOWN,
+            "wheel_down": MouseButton.WHEEL_DOWN,
+            "scrolldown": MouseButton.WHEEL_DOWN,
+            "scroll_down": MouseButton.WHEEL_DOWN,
+            "wheelleft": MouseButton.WHEEL_LEFT,
+            "wheel_left": MouseButton.WHEEL_LEFT,
+            "hwheel_left": MouseButton.WHEEL_LEFT,
+            "wheelright": MouseButton.WHEEL_RIGHT,
+            "wheel_right": MouseButton.WHEEL_RIGHT,
+            "hwheel_right": MouseButton.WHEEL_RIGHT,
         }
         if s in aliases:
             return aliases[s]
@@ -53,6 +77,11 @@ class MouseBind(BaseBind[winput.MouseEvent]):
     ) -> None:
         super().__init__(callback, config=config or MouseBindConfig(), hwnd=hwnd, dispatch=dispatch, diagnostics=diagnostics)
         self.button = _normalize_mouse_button(button)
+        if is_wheel_button(self.button) and self.config.trigger != Trigger.ON_PRESS:
+            raise ValueError(
+                f"mouse wheel bind {self.button.name.lower()!r} only supports "
+                f"Trigger.ON_PRESS, got {self.config.trigger!r}"
+            )
         self._set_diagnostics_identity(self.button.name.lower(), "mouse")
 
         self._down_ms: Optional[int] = None
@@ -60,6 +89,7 @@ class MouseBind(BaseBind[winput.MouseEvent]):
         self._tap_count: int = 0
         self._tap_last_ms: int = 0
         self._armed: bool = False
+        self._wheel_acc: int = 0
 
     def _checks_ok(self, event: winput.MouseEvent, state: InputState, trace: Optional[_EventTrace] = None) -> bool:
         return super()._checks_ok(event, state, trace=trace)
@@ -86,6 +116,34 @@ class MouseBind(BaseBind[winput.MouseEvent]):
             return which == 2
         return True
 
+    def _wheel_contribution(self, event: winput.MouseEvent) -> Optional[int]:
+        """Return signed units toward this bind, 0 on same-axis reversal, None if unrelated."""
+        act = event.action
+        if act not in MOUSE_WHEEL_ACTIONS:
+            return None
+        try:
+            delta = int(getattr(event, "additional_data", 0) or 0)
+        except Exception:
+            delta = 0
+        if delta == 0:
+            return None
+
+        if act == WM_MOUSEWHEEL:
+            if self.button == MouseButton.WHEEL_UP:
+                return delta if delta > 0 else 0
+            if self.button == MouseButton.WHEEL_DOWN:
+                return -delta if delta < 0 else 0
+            return None
+
+        if act == WM_MOUSEHWHEEL:
+            if self.button == MouseButton.WHEEL_RIGHT:
+                return delta if delta > 0 else 0
+            if self.button == MouseButton.WHEEL_LEFT:
+                return -delta if delta < 0 else 0
+            return None
+
+        return None
+
     def reset(self) -> None:
         self._down_ms = None
         self._press_suppress_up = False
@@ -93,6 +151,60 @@ class MouseBind(BaseBind[winput.MouseEvent]):
         self._tap_last_ms = 0
         self._hold_token += 1
         self._armed = False
+        self._wheel_acc = 0
+
+    def _handle_wheel(self, event: winput.MouseEvent, now_ms: int, trace: _EventTrace) -> int:
+        contrib = self._wheel_contribution(event)
+        if contrib is None:
+            return winput.WP_CONTINUE
+
+        if contrib == 0:
+            if self._wheel_acc:
+                trace.note("decision", "wheel_accumulator_reset", previous_acc=self._wheel_acc)
+            self._wheel_acc = 0
+            return winput.WP_CONTINUE
+
+        self._wheel_acc += contrib
+        quantum = int(self.config.wheel_delta)  # type: ignore
+        # too lazy to fix this typing issue now
+
+        fired = 0
+        flags = winput.WP_CONTINUE
+        sup = self.config.suppress
+        trig_name = self.config.trigger.name.lower()
+
+        trace.note(
+            "decision",
+            "wheel_tick",
+            button=self.button.name.lower(),
+            delta=contrib,
+            accumulated=self._wheel_acc,
+            quantum=quantum,
+        )
+
+        while self._wheel_acc >= quantum:
+            if not self.can_fire_now(now_ms, trace=trace):
+                break
+            self._wheel_acc -= quantum
+            self._fires += 1
+            self._last_fire_ms = now_ms
+            self._fire(trace.fire(trigger=trig_name))
+            fired += 1
+
+        if fired:
+            trace.note("decision", "wheel_notches_fired", notches=fired, remainder=self._wheel_acc)
+
+        if sup == SuppressPolicy.ALWAYS:
+            flags |= winput.WP_DONT_PASS_INPUT_ON
+            trace.suppress("suppressed_always")
+        elif fired and sup == SuppressPolicy.WHEN_MATCHED:
+            flags |= winput.WP_DONT_PASS_INPUT_ON
+            trace.suppress("suppressed_when_matched", trigger=trig_name)
+        elif fired and sup in (SuppressPolicy.WHILE_ACTIVE, SuppressPolicy.WHILE_EVALUATING):
+            flags |= winput.WP_DONT_PASS_INPUT_ON
+            trace.suppress("suppressed_while_active" if sup == SuppressPolicy.WHILE_ACTIVE else "suppressed_while_evaluating")
+
+        return flags
 
     def _get_pressed_for_policy(self, state: InputState, *, inj: bool) -> set[MouseButton]:
         pol = self.config.injected
@@ -132,7 +244,7 @@ class MouseBind(BaseBind[winput.MouseEvent]):
         return [self.button] if self.is_pressed() else []
 
     def handle(self, event: winput.MouseEvent, state: InputState) -> int:
-        # Mouse move/wheel is extremely frequent; this is called only after Hook filtered.
+        # Move is filtered in the backend. Wheel and button events reach here.
         with self._lock:
             trace = self._trace(event)
             now_ms = int(event.time)
@@ -153,6 +265,9 @@ class MouseBind(BaseBind[winput.MouseEvent]):
                 trace.skip("injected_only_but_physical")
                 return winput.WP_CONTINUE
 
+            if is_wheel_button(self.button):
+                return self._handle_wheel(event, now_ms, trace)
+
             down_act, up_act = self._actions_for_button()
             is_down = event.action == down_act
             is_up = event.action == up_act

{keybinds-1.3.4 → keybinds-1.3.5}/keybinds/types.py

@@ -203,6 +203,22 @@ class MouseButton(Enum):
     MIDDLE = auto()
     X1 = auto()
     X2 = auto()
+    WHEEL_UP = auto()
+    WHEEL_DOWN = auto()
+    WHEEL_LEFT = auto()
+    WHEEL_RIGHT = auto()
+
+
+WHEEL_BUTTONS = frozenset({
+    MouseButton.WHEEL_UP,
+    MouseButton.WHEEL_DOWN,
+    MouseButton.WHEEL_LEFT,
+    MouseButton.WHEEL_RIGHT,
+})
+
+
+def is_wheel_button(button: MouseButton) -> bool:
+    return button in WHEEL_BUTTONS
 
 
 @dataclass(frozen=True)
@@ -216,9 +232,15 @@ class MouseBindConfig:
     timing: Timing = field(default_factory=Timing)
     constraints: Constraints = field(default_factory=Constraints)
     checks: Checks = field(default_factory=Checks)
+    # Units accumulated before one wheel callback. Win32 notch is 120.
+    wheel_delta: int = 120
 
     def __post_init__(self):
         object.__setattr__(self, "checks", Checks.coerce(self.checks))
+        delta = int(self.wheel_delta)
+        if delta < 1:
+            raise ValueError("wheel_delta must be >= 1")
+        object.__setattr__(self, "wheel_delta", delta)
 
     def soft_merge(self, patch: MouseBindConfig) -> MouseBindConfig:
         """Apply only non-default fields from `patch` (patch semantics)."""
@@ -328,6 +350,9 @@ def _merge_soft(lhs: TBind, rhs: TBind) -> TBind:
     if rhs.focus != default_bind.focus:
         out = replace(out, focus=rhs.focus)
 
+    if isinstance(out, MouseBindConfig) and rhs.wheel_delta != default_bind.wheel_delta:
+        out = replace(out, wheel_delta=rhs.wheel_delta)
+
     out = replace(out, timing=_merge_dc_soft(out.timing, rhs.timing, _DEFAULT_TIMING))
     out = replace(out, constraints=_merge_dc_soft(out.constraints, rhs.constraints, _DEFAULT_CONSTRAINTS))
     out = replace(out, checks=_merge_dc_soft(out.checks, rhs.checks, _DEFAULT_CHECKS))

{keybinds-1.3.4 → keybinds-1.3.5}/keybinds/winput/winput.py

@@ -352,7 +352,9 @@ def _LowLevelMouseProc(nCode : int, wParam : int, lParam : int, cbfunc : Callabl
         extra_data = GET_HWORD(ms.mouseData)
         
     elif wParam == WM_MOUSEWHEEL or wParam == WM_MOUSEHWHEEL: # used scrollwheel
-        extra_data = GET_HWORD(ms.mouseData) // WHEEL_DELTA
+        # Raw signed HIWORD. WHEEL_DELTA (120) is the notch quantum at the bind layer;
+        # dividing here would drop high-res / touchpad packets smaller than 120.
+        extra_data = GET_HWORD(ms.mouseData)
 
     result = cbfunc(MouseEvent(
         (ms.pt.x, ms.pt.y),

{keybinds-1.3.4 → keybinds-1.3.5}/keybinds.egg-info/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: keybinds
-Version: 1.3.4
+Version: 1.3.5
 Summary: Flexible global keyboard & mouse hotkeys for Windows
 Author: echolane
 License: MIT License
@@ -55,14 +55,14 @@ 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-maintenance-yellow)
+![Status](https://img.shields.io/badge/status-active-success)
 ![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.
 
 It supports:
 - global keyboard binds: single keys, chords (`ctrl+e`), and sequences (`g,k,i`)
-- global mouse binds: `left`, `right`, `middle`, `x1`, `x2`
+- global mouse binds: `left`, `right`, `middle`, `x1`, `x2`, `wheel_up`, `wheel_down`
 - rich triggers: press, release, click, hold, repeat, double tap, and sequence
 - suppression and injected-input policies
 - sync and async callbacks
@@ -108,7 +108,7 @@ Stable decorator helpers:
 
 ```python
 import keybinds
-from keybinds.decorators import bind_key, bind_mouse
+from keybinds import bind_key, bind_mouse
 
 @bind_key("ctrl+e")
 def inventory():
@@ -127,7 +127,7 @@ Decorators use the default hook automatically.
 
 ```python
 import keybinds
-from keybinds.decorators import bind_logical, bind_text, bind_abbreviation
+from keybinds import bind_logical, bind_text, bind_abbreviation
 
 # Experimental API: may change in future releases.
 
@@ -227,7 +227,7 @@ hook.bind("ctrl+e", lambda: print("Pressed"))
 ### Release
 
 ```python
-from keybinds.types import BindConfig, Trigger
+from keybinds import BindConfig, Trigger
 
 hook.bind(
     "ctrl+t",
@@ -239,7 +239,7 @@ hook.bind(
 ### Hold
 
 ```python
-from keybinds.types import BindConfig, Trigger, Timing
+from keybinds import BindConfig, Trigger, Timing
 
 hook.bind(
     "h",
@@ -254,7 +254,7 @@ hook.bind(
 ### Repeat (auto-fire while held)
 
 ```python
-from keybinds.types import BindConfig, Trigger, Timing
+from keybinds import BindConfig, Trigger, Timing
 
 hook.bind(
     "space",
@@ -269,7 +269,7 @@ hook.bind(
 ### Double tap
 
 ```python
-from keybinds.types import BindConfig, Trigger
+from keybinds import BindConfig, Trigger
 
 hook.bind(
     "g",
@@ -281,7 +281,7 @@ hook.bind(
 ### Sequence
 
 ```python
-from keybinds.types import BindConfig, Trigger
+from keybinds import BindConfig, Trigger
 
 hook.bind(
     "g,k,i",
@@ -295,7 +295,7 @@ hook.bind(
 ## Mouse Basics
 
 ```python
-from keybinds.types import MouseBindConfig, Trigger
+from keybinds import MouseBindConfig, Trigger
 
 hook.bind_mouse(
     "middle",
@@ -312,12 +312,28 @@ Mouse buttons:
 - `x1`
 - `x2`
 
+Mouse wheel (only `Trigger.ON_PRESS`):
+
+- `wheel_up` / `wheel_down`
+- `wheel_left` / `wheel_right` — horizontal (many mice never emit these)
+
+Wheel units accumulate until `MouseBindConfig.wheel_delta` (default `120`, the Win32 notch). Smaller wheel steps add up until they reach `wheel_delta`. Scrolling the other way clears the leftover amount.
+
+```python
+hook.bind_mouse("wheel_up", lambda: print("scroll up"))
+hook.bind_mouse(
+    "wheel_down",
+    lambda: print("scroll down"),
+    config=MouseBindConfig(wheel_delta=40),
+)
+```
+
 ---
 
 ## Suppression (block input from apps)
 
 ```python
-from keybinds.types import BindConfig, SuppressPolicy
+from keybinds import BindConfig, SuppressPolicy
 
 hook.bind(
     "ctrl+r",
@@ -341,7 +357,7 @@ Policies:
 Control how injected input (macros, `SendInput`, automation tools) is handled:
 
 ```python
-from keybinds.types import BindConfig, InjectedPolicy
+from keybinds import BindConfig, InjectedPolicy
 
 hook.bind(
     "f1",
@@ -361,7 +377,7 @@ Policies:
 ## Strict Chords
 
 ```python
-from keybinds.types import BindConfig, Constraints, ChordPolicy
+from keybinds import BindConfig, Constraints, ChordPolicy
 
 hook.bind(
     "ctrl+shift+u",
@@ -397,8 +413,7 @@ Callbacks may be `async def`. If a callback returns an awaitable, **keybinds** s
 
 ```python
 import asyncio
-from keybinds import Hook
-from keybinds.decorators import bind_key
+from keybinds import Hook, bind_key
 
 hook = Hook()
 

{keybinds-1.3.4 → keybinds-1.3.5}/keybinds.egg-info/SOURCES.txt

@@ -45,6 +45,7 @@ tests/test_bind_wait_and_is_pressed.py
 tests/test_decorators_and_simple.py
 tests/test_diagnostics.py
 tests/test_logical_parsing.py
+tests/test_mouse_wheel.py
 tests/test_parsing.py
 tests/test_runtime_bindings.py
 tests/test_runtime_edge_cases.py

{keybinds-1.3.4 → keybinds-1.3.5}/pyproject.toml

@@ -4,7 +4,7 @@ build-backend = "setuptools.build_meta"
 
 [project]
 name = "keybinds"
-version = "1.3.4"
+version = "1.3.5"
 description = "Flexible global keyboard & mouse hotkeys for Windows"
 readme = "README.md"
 requires-python = ">=3.7"

keybinds-1.3.5/tests/test_mouse_wheel.py

@@ -0,0 +1,177 @@
+from __future__ import annotations
+
+import pytest
+
+
+def test_normalize_mouse_button_accepts_wheel_aliases(runtime_env):
+    normalize = runtime_env._mouse._normalize_mouse_button
+    MouseButton = runtime_env.types.MouseButton
+
+    assert normalize("wheel_up") is MouseButton.WHEEL_UP
+    assert normalize("scrollup") is MouseButton.WHEEL_UP
+    assert normalize("wheel-down") is MouseButton.WHEEL_DOWN
+    assert normalize("hwheel_left") is MouseButton.WHEEL_LEFT
+    assert normalize("hwheel_right") is MouseButton.WHEEL_RIGHT
+    assert normalize(MouseButton.WHEEL_UP) is MouseButton.WHEEL_UP
+
+    with pytest.raises(ValueError):
+        normalize("wheel")
+    with pytest.raises(ValueError):
+        normalize("tilt_left")
+
+
+def test_wheel_bind_rejects_non_press_triggers(runtime_env):
+    MouseBindConfig = runtime_env.types.MouseBindConfig
+    Trigger = runtime_env.types.Trigger
+    hook = runtime_env.make_hook()
+
+    with pytest.raises(ValueError, match="ON_PRESS"):
+        hook.bind_mouse(
+            "wheel_up",
+            lambda: None,
+            config=MouseBindConfig(trigger=Trigger.ON_HOLD),
+        )
+
+
+def test_wheel_delta_rejects_non_positive(runtime_env):
+    MouseBindConfig = runtime_env.types.MouseBindConfig
+    with pytest.raises(ValueError, match="wheel_delta"):
+        MouseBindConfig(wheel_delta=0)
+
+
+def test_vertical_wheel_accumulates_to_configured_delta(runtime_env):
+    hook = runtime_env.make_hook()
+    driver = runtime_env.HookDriver(runtime_env, hook)
+    hits = []
+
+    bind = hook.bind_mouse("wheel_up", lambda: hits.append("up"))
+    hook.bind_mouse("wheel_down", lambda: hits.append("down"))
+
+    assert bind.config.wheel_delta == 120
+    assert driver.wheel(60) == runtime_env.winput.WP_CONTINUE
+    assert hits == []
+    assert bind._wheel_acc == 60
+
+    assert driver.wheel(60) == runtime_env.winput.WP_CONTINUE
+    assert hits == ["up"]
+    assert bind._wheel_acc == 0
+
+
+def test_custom_wheel_delta_changes_quantum(runtime_env):
+    MouseBindConfig = runtime_env.types.MouseBindConfig
+    hook = runtime_env.make_hook()
+    driver = runtime_env.HookDriver(runtime_env, hook)
+    hits = []
+
+    hook.bind_mouse(
+        "wheel_up",
+        lambda: hits.append("up"),
+        config=MouseBindConfig(wheel_delta=40),
+    )
+
+    driver.wheel(40)
+    driver.wheel(80)
+    assert hits == ["up", "up", "up"]
+
+
+def test_wheel_delta_soft_merge_overrides_default(runtime_env):
+    MouseBindConfig = runtime_env.types.MouseBindConfig
+    SuppressPolicy = runtime_env.types.SuppressPolicy
+
+    merged = MouseBindConfig(suppress=SuppressPolicy.WHEN_MATCHED).soft_merge(
+        MouseBindConfig(wheel_delta=30)
+    )
+    assert merged.wheel_delta == 30
+    assert merged.suppress is SuppressPolicy.WHEN_MATCHED
+
+
+def test_vertical_wheel_fires_once_per_notch_including_multiples(runtime_env):
+    hook = runtime_env.make_hook()
+    driver = runtime_env.HookDriver(runtime_env, hook)
+    hits = []
+
+    hook.bind_mouse("wheel_down", lambda: hits.append("down"))
+
+    driver.wheel(-240)
+    assert hits == ["down", "down"]
+
+
+def test_opposite_vertical_direction_resets_remainder(runtime_env):
+    hook = runtime_env.make_hook()
+    driver = runtime_env.HookDriver(runtime_env, hook)
+    hits = []
+
+    up = hook.bind_mouse("wheel_up", lambda: hits.append("up"))
+
+    driver.wheel(60)
+    assert up._wheel_acc == 60
+    driver.wheel(-30)
+    assert up._wheel_acc == 0
+    driver.wheel(60)
+    assert hits == []
+
+
+def test_horizontal_wheel_is_independent_axis(runtime_env):
+    hook = runtime_env.make_hook()
+    driver = runtime_env.HookDriver(runtime_env, hook)
+    hits = []
+
+    hook.bind_mouse("wheel_left", lambda: hits.append("left"))
+    hook.bind_mouse("wheel_right", lambda: hits.append("right"))
+    hook.bind_mouse("wheel_up", lambda: hits.append("up"))
+
+    driver.wheel(-120, horizontal=True)
+    driver.wheel(120, horizontal=True)
+    driver.wheel(120)
+
+    assert hits == ["left", "right", "up"]
+
+
+def test_wheel_when_matched_suppresses_only_after_a_notch(runtime_env):
+    MouseBindConfig = runtime_env.types.MouseBindConfig
+    SuppressPolicy = runtime_env.types.SuppressPolicy
+    hook = runtime_env.make_hook()
+    driver = runtime_env.HookDriver(runtime_env, hook)
+    hits = []
+
+    hook.bind_mouse(
+        "wheel_up",
+        lambda: hits.append("up"),
+        config=MouseBindConfig(suppress=SuppressPolicy.WHEN_MATCHED),
+    )
+
+    flags_partial = driver.wheel(40)
+    flags_full = driver.wheel(80)
+
+    assert flags_partial == runtime_env.winput.WP_CONTINUE
+    assert flags_full & runtime_env.winput.WP_DONT_PASS_INPUT_ON
+    assert hits == ["up"]
+
+
+def test_wheel_is_never_pressed(runtime_env):
+    hook = runtime_env.make_hook()
+    driver = runtime_env.HookDriver(runtime_env, hook)
+    runtime_env.backend_singleton.current_state_snapshot = driver._state
+    bind = hook.bind_mouse("wheel_up", lambda: None)
+
+    driver.wheel(120)
+    assert bind.is_pressed() is False
+    assert bind.pressed_keys() == []
+
+
+def test_wheel_respects_injected_ignore(runtime_env):
+    MouseBindConfig = runtime_env.types.MouseBindConfig
+    InjectedPolicy = runtime_env.types.InjectedPolicy
+    hook = runtime_env.make_hook()
+    driver = runtime_env.HookDriver(runtime_env, hook)
+    hits = []
+
+    hook.bind_mouse(
+        "wheel_up",
+        lambda: hits.append("up"),
+        config=MouseBindConfig(injected=InjectedPolicy.IGNORE),
+    )
+
+    driver.wheel(120, injected=True)
+    driver.wheel(120, injected=False)
+    assert hits == ["up"]