Repository navigation
Expand file tree
/
Copy pathclick_at.py
More file actions
330 lines (272 loc) · 12.1 KB
/
Copy pathclick_at.py
File metadata and controls
330 lines (272 loc) · 12.1 KB
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
188
189
190
191
192
193
194
195
196
197
198
199
200
201
202
203
204
205
206
207
208
209
210
211
212
213
214
215
216
217
218
219
220
221
222
223
224
225
226
227
228
229
230
231
232
233
234
235
236
237
238
239
240
241
242
243
244
245
246
247
248
249
250
251
252
253
254
255
256
257
258
259
260
261
262
263
264
265
266
267
268
269
270
271
272
273
274
275
276
277
278
279
280
281
282
283
284
285
286
287
288
289
290
291
292
293
294
295
296
297
298
299
300
301
302
303
304
305
306
307
308
309
310
311
312
313
314
315
316
317
318
319
320
321
322
323
324
325
326
327
328
329
330
#!/usr/bin/env python3
"""
click_at.py — Move the cursor and click at a given (x, y) screen coordinate.
Primary engine : Quartz CGEventPost (zero-overhead, Retina-correct)
Fallback engine: PyAutoGUI
Coordinate systems
------------------
The click APIs expect **logical points** (macOS UI coordinate space).
On a non-Retina display logical == physical. On a Retina (HiDPI) display
physical pixels are 2× (or more) the logical points.
Pass ``coords="logical"`` (default) when your coordinates are already in
logical points — e.g. they came from a CoreGraphics window enumeration or
an mss grab on a machine where mss reports logical dimensions.
Pass ``coords="physical"`` when your coordinates came from a screenshot
that was captured at the raw hardware pixel resolution (e.g. PIL/Pillow's
``ImageGrab.grab()`` or mss on a machine where mss reports physical pixels).
The script will divide by the detected scale factor automatically.
Permission (one-time setup)
---------------------------
macOS TCC requires the running app (Terminal, iTerm2, your IDE, etc.) to be
granted Accessibility permission before it can post synthetic mouse events.
The script checks this at startup. If permission is missing it prints clear
instructions and exits. Once the user grants it the permission persists
permanently — no further action needed.
System Settings → Privacy & Security → Accessibility
Add your terminal app → enable the toggle
CLI usage
---------
python click_at.py <x> <y>
python click_at.py <x> <y> --physical # coords are physical pixels
python click_at.py <x> <y> --no-move # click without moving cursor first
python click_at.py <x> <y> --delay 0.1 # down→up delay in seconds (default 0.05)
Import usage
------------
from click_at import Clicker, click_at
# Simple one-shot
click_at(640, 400)
click_at(1280, 800, coords="physical") # Retina physical pixels
# Reusable instance (detects scale once)
clicker = Clicker()
clicker.click(640, 400)
"""
from __future__ import annotations
import argparse
import sys
import time
from typing import Optional
# ---------------------------------------------------------------------------
# Scale detection
# ---------------------------------------------------------------------------
def _detect_scale() -> float:
"""
Detect the HiDPI backing scale factor for the main display.
Uses AppKit NSScreen directly — fast, no subprocess needed. Returns 1.0
if AppKit is unavailable (non-macOS or missing pyobjc).
"""
try:
import AppKit # part of pyobjc-framework-Cocoa
screen = AppKit.NSScreen.mainScreen()
if screen is not None:
return float(screen.backingScaleFactor())
except Exception:
pass
return 1.0
# ---------------------------------------------------------------------------
# Permission check
# ---------------------------------------------------------------------------
def check_accessibility_permission(prompt: bool = True) -> bool:
"""
Return True if the current process has Accessibility permission.
If ``prompt`` is True and permission is missing, macOS will automatically
open System Settings → Accessibility (one-time user action required).
"""
try:
import ApplicationServices # part of pyobjc-framework-ApplicationServices
opts = {"AXTrustedCheckOptionPrompt": prompt}
return bool(ApplicationServices.AXIsProcessTrustedWithOptions(opts))
except ImportError:
# pyobjc not available — fall through to PyAutoGUI which does its own check
return True
def _require_permission() -> None:
"""Exit with a clear message if Accessibility permission is not granted."""
if not check_accessibility_permission(prompt=True):
print(
"\n[click_at] ERROR: Accessibility permission not granted.\n"
"\n"
" macOS requires your terminal to be in the Accessibility list before\n"
" it can post synthetic mouse events.\n"
"\n"
" One-time setup (takes ~30 seconds, never needed again):\n"
" 1. macOS just opened System Settings → Accessibility (or do it manually).\n"
" 2. Click the lock icon (bottom-left) and enter your password.\n"
" 3. Find your terminal app (Terminal / iTerm2 / etc.) in the list.\n"
" 4. Enable the toggle next to it.\n"
" 5. Re-run this script.\n"
)
sys.exit(1)
# ---------------------------------------------------------------------------
# Primary engine: Quartz
# ---------------------------------------------------------------------------
def _click_quartz(x: float, y: float, move: bool, down_up_delay: float) -> None:
"""Post CGEvents directly to the HID event tap."""
from Quartz.CoreGraphics import (
CGEventCreateMouseEvent,
CGEventPost,
kCGEventMouseMoved,
kCGEventLeftMouseDown,
kCGEventLeftMouseUp,
kCGMouseButtonLeft,
kCGHIDEventTap,
)
point = (x, y)
if move:
ev_move = CGEventCreateMouseEvent(None, kCGEventMouseMoved, point, kCGMouseButtonLeft)
CGEventPost(kCGHIDEventTap, ev_move)
# brief settle time so the browser registers the hover before the click
time.sleep(0.02)
ev_down = CGEventCreateMouseEvent(None, kCGEventLeftMouseDown, point, kCGMouseButtonLeft)
ev_up = CGEventCreateMouseEvent(None, kCGEventLeftMouseUp, point, kCGMouseButtonLeft)
CGEventPost(kCGHIDEventTap, ev_down)
time.sleep(down_up_delay)
CGEventPost(kCGHIDEventTap, ev_up)
# ---------------------------------------------------------------------------
# Fallback engine: PyAutoGUI
# ---------------------------------------------------------------------------
def _click_pyautogui(x: float, y: float, move: bool) -> None:
"""PyAutoGUI fallback — slower but dependency-minimal."""
import pyautogui # type: ignore
pyautogui.FAILSAFE = False # don't abort if cursor reaches corner
pyautogui.PAUSE = 0 # remove default 0.1 s inter-action pause
if move:
pyautogui.moveTo(x, y, duration=0)
pyautogui.click(x, y)
# ---------------------------------------------------------------------------
# Clicker — importable class-based API
# ---------------------------------------------------------------------------
class Clicker:
"""
Importable class-based API for synthetic mouse clicks.
Detects the display scale factor once on instantiation so repeated calls
are fast. Thread-safe — each call is a self-contained sequence of events.
Example::
from click_at import Clicker
clicker = Clicker()
clicker.click(640, 400) # logical coords
clicker.click(1280, 800, coords="physical") # physical pixels
"""
def __init__(self, down_up_delay: float = 0.05) -> None:
"""
Args:
down_up_delay: Seconds between mouseDown and mouseUp events.
0.05 s is the sweet spot for browser reliability.
"""
self._scale = _detect_scale()
self._down_up_delay = down_up_delay
@property
def scale(self) -> float:
"""HiDPI backing scale factor (1.0 on non-Retina, 2.0 on Retina)."""
return self._scale
def check_permission(self, prompt: bool = False) -> bool:
"""
Return True if Accessibility permission is granted.
Pass ``prompt=True`` to have macOS open the settings pane automatically
if permission is missing.
"""
return check_accessibility_permission(prompt=prompt)
def click(
self,
x: int | float,
y: int | float,
coords: str = "logical",
move: bool = True,
) -> None:
"""
Move the cursor to (x, y) and perform a left click.
Args:
x, y: Screen coordinate to click.
coords: ``"logical"`` (default) — x/y are already in logical
points as expected by macOS click APIs. No conversion.
``"physical"`` — x/y are in raw hardware pixels (e.g.
from a Retina screenshot); automatically divided by the
detected scale factor.
move: If True (default), move the cursor to the target before
clicking. Set False to send a click event without moving
the visible cursor.
Raises:
RuntimeError: If permission is missing and the click cannot proceed.
Exception: Propagates Quartz or PyAutoGUI errors after fallback.
"""
lx, ly = self._to_logical(float(x), float(y), coords)
_require_permission()
try:
_click_quartz(lx, ly, move=move, down_up_delay=self._down_up_delay)
print(f"[click_at] Clicked ({lx:.0f}, {ly:.0f}) via Quartz")
except Exception as exc:
print(f"[click_at] Quartz failed ({exc}), falling back to PyAutoGUI")
_click_pyautogui(lx, ly, move=move)
print(f"[click_at] Clicked ({lx:.0f}, {ly:.0f}) via PyAutoGUI")
def _to_logical(self, x: float, y: float, coords: str) -> tuple[float, float]:
if coords == "physical" and self._scale != 1.0:
return x / self._scale, y / self._scale
return x, y
# ---------------------------------------------------------------------------
# Module-level convenience function
# ---------------------------------------------------------------------------
def click_at(
x: int | float,
y: int | float,
coords: str = "logical",
move: bool = True,
down_up_delay: float = 0.05,
) -> None:
"""
Convenience wrapper: click at (x, y) without instantiating a Clicker.
Detects scale on every call — use ``Clicker`` when clicking repeatedly.
"""
Clicker(down_up_delay=down_up_delay).click(x, y, coords=coords, move=move)
# ---------------------------------------------------------------------------
# CLI
# ---------------------------------------------------------------------------
def _parse_args() -> argparse.Namespace:
p = argparse.ArgumentParser(
description="Click at a given (x, y) screen coordinate.",
formatter_class=argparse.RawDescriptionHelpFormatter,
epilog=(
"Examples:\n"
" python click_at.py 640 400\n"
" python click_at.py 1280 800 --physical\n"
" python click_at.py 640 400 --no-move --delay 0.1\n"
),
)
p.add_argument("x", type=float, nargs="?", help="X coordinate to click")
p.add_argument("y", type=float, nargs="?", help="Y coordinate to click")
p.add_argument(
"--physical", action="store_true",
help="Treat x/y as physical pixels (Retina raw resolution); divides by scale factor",
)
p.add_argument(
"--no-move", action="store_true",
help="Send click without moving the visible cursor first",
)
p.add_argument(
"--delay", type=float, default=0.05, metavar="SECS",
help="Seconds between mouseDown and mouseUp (default: 0.05)",
)
p.add_argument(
"--check-permission", action="store_true",
help="Check Accessibility permission and exit (0=granted, 1=denied)",
)
return p.parse_args()
def main() -> None:
args = _parse_args()
if args.check_permission:
granted = check_accessibility_permission(prompt=True)
if granted:
print("[click_at] Accessibility permission: GRANTED")
sys.exit(0)
else:
print("[click_at] Accessibility permission: DENIED")
print(" Follow the instructions above, then re-run.")
sys.exit(1)
if args.x is None or args.y is None:
print("Usage: python click_at.py <x> <y> [options]")
print(" python click_at.py --check-permission")
sys.exit(1)
clicker = Clicker(down_up_delay=args.delay)
coords = "physical" if args.physical else "logical"
move = not args.no_move
print(f"[click_at] scale={clicker.scale:.1f} coords={coords} move={move}")
clicker.click(args.x, args.y, coords=coords, move=move)
if __name__ == "__main__":
main()