perf/docs: optimise simple input performance

README.md

@@ -135,11 +135,11 @@ class Bot:
     def __init__(self):
 
         self.left_click_event = mouse.create_event(
-            MouseCodes.MOUSEEVENTF_LEFTDOWN | MouseCodes.MOUSEEVENTF_LEFTUP, 100, 100
+            MouseCodes.MOUSE_LEFT_CLICK, 100, 100
         )
 
         self.right_click_event = mouse.create_event(
-            MouseCodes.MOUSEEVENTF_RIGHTDOWN | MouseCodes.MOUSEEVENTF_RIGHTUP, 100, 100
+            MouseCodes.MOUSE_RIGHT_CLICK, 100, 100
         )
 
 

keywin/mouse/__init__.py

@@ -1,7 +1,7 @@
 from __future__ import annotations
 
 from keywin.mouse.codes import MouseCodes
-from keywin.send_input import send_mouse_event
+from keywin.send_input import send_mouse_event, send_mouse_flag
 
 
 def create_event(flags: int, x: int = 0, y: int = 0, mouse_data: int = 0) -> tuple[int, int, int, int]:
@@ -51,7 +51,7 @@ def left_click() -> bool:
      --------
      success (bool) : the success of the event
     """
-    return send_events((0, 0, 0, MouseCodes.MOUSE_LEFT_CLICK))
+    return send_mouse_flag(MouseCodes.MOUSE_LEFT_CLICK)
 
 
 def right_click() -> bool:
@@ -64,7 +64,7 @@ def right_click() -> bool:
      --------
      success (bool) : the success of the event
     """
-    return send_events((0, 0, 0, MouseCodes.MOUSE_RIGHT_CLICK))
+    return send_mouse_flag(MouseCodes.MOUSE_RIGHT_CLICK)
 
 
 def middle_click() -> bool:
@@ -77,7 +77,7 @@ def middle_click() -> bool:
      --------
      success (bool) : the success of the event
     """
-    return send_events((0, 0, 0, MouseCodes.MOUSE_MIDDLE_CLICK))
+    return send_mouse_flag(MouseCodes.MOUSE_MIDDLE_CLICK)
 
 
 def xbutton1_click() -> bool:
@@ -116,7 +116,7 @@ def left_press() -> bool:
     --------
     success (bool) : the success of the event
     """
-    return send_events((0, 0, 0, MouseCodes.MOUSEEVENTF_LEFTDOWN))
+    return send_mouse_flag(MouseCodes.MOUSEEVENTF_LEFTDOWN)
 
 
 def left_release() -> bool:
@@ -129,7 +129,7 @@ def left_release() -> bool:
     --------
     success (bool) : the success of the event
     """
-    return send_events((0, 0, 0, MouseCodes.MOUSEEVENTF_LEFTUP))
+    return send_mouse_flag(MouseCodes.MOUSEEVENTF_LEFTUP)
 
 
 def right_press() -> bool:
@@ -142,7 +142,7 @@ def right_press() -> bool:
     --------
     success (bool) : the success of the event
     """
-    return send_events((0, 0, 0, MouseCodes.MOUSEEVENTF_RIGHTDOWN))
+    return send_mouse_flag(MouseCodes.MOUSEEVENTF_RIGHTDOWN)
 
 
 def right_release() -> bool:
@@ -155,7 +155,7 @@ def right_release() -> bool:
     --------
     success (bool) : the success of the event
     """
-    return send_events((0, 0, 0, MouseCodes.MOUSEEVENTF_RIGHTUP))
+    return send_mouse_flag(MouseCodes.MOUSEEVENTF_RIGHTUP)
 
 
 def middle_press() -> bool:
@@ -168,7 +168,7 @@ def middle_press() -> bool:
     --------
     success (bool) : the success of the event
     """
-    return send_events((0, 0, 0, MouseCodes.MOUSEEVENTF_MIDDLEDOWN))
+    return send_mouse_flag(MouseCodes.MOUSEEVENTF_MIDDLEDOWN)
 
 
 def middle_release() -> bool:
@@ -181,7 +181,7 @@ def middle_release() -> bool:
     --------
     success (bool) : the success of the event
     """
-    return send_events((0, 0, 0, MouseCodes.MOUSEEVENTF_MIDDLEUP))
+    return send_mouse_flag(MouseCodes.MOUSEEVENTF_MIDDLEUP)
 
 
 def xbutton1_press() -> bool:

keywin/mouse/codes/__init__.py

@@ -1,4 +1,7 @@
-class MouseCodes:
+from typing import Protocol
+
+
+class MouseCodes(Protocol):
     """
     Summary
     -------

keywin/send_input/__init__.pyi

@@ -16,6 +16,18 @@ def send_mouse_event(inputs: Iterable[tuple[int, int, int, int]]) -> bool:
     """
     ...
 
+def send_mouse_flag(flags: int) -> bool:
+    """
+    Summary
+    -------
+    a low-level wrapper to directly send a mouse flag to the Windows API SendInput function
+
+    Parameters
+    ----------
+    flags (int) : valid mouse flag(s)
+    """
+    ...
+
 def press_keyboard(keys: Iterable[int]) -> bool:
     """
     Summary

keywin/send_input/send_input.c

@@ -86,7 +86,7 @@ static PyObject* send_mouse_event(PyObject* self, PyObject* args) {
         const LONG x           = PyLong_AsLongAndOverflow(PyTuple_GetItem(mouse_event, 0), &x_overflow);
         const LONG y           = PyLong_AsLongAndOverflow(PyTuple_GetItem(mouse_event, 1), &y_overflow);
         const DWORD mouse_data = PyLong_AsLongAndOverflow(PyTuple_GetItem(mouse_event, 2), &mouse_data_overflow);
-        const DWORD flags       = PyLong_AsUnsignedLong(PyTuple_GetItem(mouse_event, 3));
+        const DWORD flags      = PyLong_AsUnsignedLong(PyTuple_GetItem(mouse_event, 3));
 
         if (x_overflow || y_overflow || mouse_data_overflow) {
             return dispose_and_fail(inputs);
@@ -108,9 +108,32 @@ static PyObject* send_mouse_event(PyObject* self, PyObject* args) {
     Py_RETURN_TRUE;
 }
 
+static PyObject* send_mouse_flag(PyObject* self, PyObject* args) {
+    int flags;
+
+    if (!PyArg_ParseTuple(args, "i", &flags)) {
+        Py_RETURN_FALSE;
+    }
+
+    INPUT inputs[1];
+    inputs[0].type         = INPUT_MOUSE;
+    inputs[0].mi.dx        = 0;
+    inputs[0].mi.dy        = 0;
+    inputs[0].mi.mouseData = 0;
+    inputs[0].mi.dwFlags   = flags;
+    inputs[0].mi.time      = 0;
+
+    if (SendInput(1, inputs, sizeof(INPUT)) != 1) {
+        Py_RETURN_FALSE;
+    }
+
+    Py_RETURN_TRUE;
+}
+
 static PyMethodDef send_input_methods[] = {
     {"press_keyboard", press_keyboard, METH_VARARGS, "Press and release keyboard keys"},
     {"send_mouse_event", send_mouse_event, METH_VARARGS, "Send mouse events"},
+    {"send_mouse_flag", send_mouse_flag, METH_VARARGS, "Send mouse flags"},
     {NULL, NULL, 0, NULL}
 };