android-device-control 0.1.0__py3-none-any.whl

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
@@ -0,0 +1,568 @@
1
+ #!/usr/bin/env python3
2
+ """Small fail-closed ADB controller for an explicitly selected Android device.
3
+
4
+ Authentication-screen detection uses English accessibility labels and password
5
+ field metadata. It is a conservative guard, not a complete OTP detector: an
6
+ unlabeled or non-English recovery screen can go undetected, so callers must
7
+ still inspect the live UI and handle sensitive screens manually.
8
+ """
9
+ from __future__ import annotations
10
+
11
+ import argparse
12
+ import hashlib
13
+ import ipaddress
14
+ import json
15
+ import os
16
+ from pathlib import Path
17
+ import shlex
18
+ import re
19
+ import subprocess
20
+ import sys
21
+ import time
22
+ from urllib.parse import urlsplit
23
+ import xml.etree.ElementTree as ET
24
+
25
+ KEYS = {"back": 4, "home": 3, "enter": 66, "tab": 61,
26
+ "delete": 67, "escape": 111, "up": 19, "down": 20,
27
+ "left": 21, "right": 22}
28
+ EDIT_CLASS = "android.widget.EditText"
29
+ MAX_SETTLE_SECONDS = 10.0
30
+ SETTLE_INTERVAL_SECONDS = 0.35
31
+ MIN_SWIPE_MS = 100
32
+ MAX_SWIPE_MS = 1500
33
+ SENSITIVE_SCREEN = re.compile(
34
+ r"\b(?:password|passcode|one[ -]?time(?: password)?|"
35
+ r"verification(?: code)?|security code|authentication|authenticator|otp|2fa|"
36
+ r"two[ -]?factor|account recovery|recover account|forgot password|reset password|"
37
+ r"enter code|confirm your identity|identity check)\b", re.IGNORECASE)
38
+ SENSITIVE_AUTH_HEADING = re.compile(r"^\s*(?:sign[ -]?in|log[ -]?in)\b", re.IGNORECASE)
39
+ SAFE_FIELD_LABEL = re.compile(
40
+ r"\b(?:name|first name|last name|full name|display name|page name|username|"
41
+ r"user name|handle|email|email address|bio|description|website|search|title)\b",
42
+ re.IGNORECASE)
43
+ PACKAGE_NAME = re.compile(r"[A-Za-z][A-Za-z0-9_]*(?:\.[A-Za-z][A-Za-z0-9_]*)+")
44
+
45
+
46
+ class PhoneError(RuntimeError):
47
+ pass
48
+
49
+
50
+ def run(args: list[str], *, timeout: int = 15) -> bytes:
51
+ try:
52
+ result = subprocess.run(args, capture_output=True, timeout=timeout)
53
+ except (OSError, subprocess.TimeoutExpired) as exc:
54
+ raise PhoneError(f"command failed: {type(exc).__name__}") from exc
55
+ if result.returncode:
56
+ # Never relay stdout/stderr from the device: applications can include secrets.
57
+ raise PhoneError(f"ADB command failed (exit {result.returncode})")
58
+ return result.stdout
59
+
60
+
61
+ def adb(device: str, *args: str, timeout: int = 15) -> bytes:
62
+ if not device or not re.fullmatch(r"[A-Za-z0-9._:-]+", device):
63
+ raise PhoneError("provide an explicit valid device serial")
64
+ return run(["adb", "-s", device, *args], timeout=timeout)
65
+
66
+
67
+ def devices() -> str:
68
+ data = run(["adb", "devices", "-l"]).decode("utf-8", "replace")
69
+ return "\n".join(data.splitlines()[:])
70
+
71
+
72
+ def foreground_component(output: str) -> str:
73
+ """Extract only the focused package/component from a window-manager dump."""
74
+ match = re.search(
75
+ r"^\s*mCurrentFocus=Window\{[^}\r\n]*?\bu\d+\s+"
76
+ r"([A-Za-z][A-Za-z0-9_]*(?:\.[A-Za-z0-9_]+)+)/"
77
+ r"([A-Za-z.][A-Za-z0-9_$.]*)\s*\}",
78
+ output,
79
+ re.MULTILINE,
80
+ )
81
+ if match:
82
+ return f"{match.group(1)}/{match.group(2)}"
83
+ raise PhoneError("foreground package/component unavailable from Android window manager")
84
+
85
+
86
+ def foreground(device: str) -> str:
87
+ output = adb(device, "shell", "dumpsys", "window").decode("utf-8", "replace")
88
+ return foreground_component(output)
89
+
90
+
91
+ def validate_target_package(package: str) -> None:
92
+ if not PACKAGE_NAME.fullmatch(package):
93
+ raise PhoneError("package must be an explicit Android package name")
94
+
95
+
96
+ def validate_public_url(url: str) -> None:
97
+ # Keep the URL out of diagnostics and support only ordinary, non-secret URLs.
98
+ try:
99
+ parsed = urlsplit(url)
100
+ hostname = parsed.hostname
101
+ _ = parsed.port # Reject malformed ports.
102
+ except ValueError as exc:
103
+ raise PhoneError("URL is malformed; provide a non-secret HTTPS or loopback HTTP URL") from exc
104
+ if (parsed.scheme not in ("https", "http") or not hostname
105
+ or parsed.username is not None or parsed.password is not None
106
+ or any(ord(char) < 0x20 or ord(char) == 0x7f for char in url)):
107
+ raise PhoneError("URL must be a non-secret HTTPS URL or loopback HTTP URL without credentials")
108
+ if parsed.scheme == "http":
109
+ normalized_host = hostname.rstrip(".").lower()
110
+ try:
111
+ is_loopback = ipaddress.ip_address(normalized_host).is_loopback
112
+ except ValueError:
113
+ is_loopback = normalized_host == "localhost"
114
+ if not is_loopback:
115
+ raise PhoneError("HTTP is allowed only for a loopback URL")
116
+
117
+
118
+ def open_target(device: str, package: str, url: str | None = None) -> str:
119
+ validate_target_package(package)
120
+ if url is not None:
121
+ validate_public_url(url)
122
+
123
+ # Refuse to issue navigation from a visible login, recovery, OTP, or
124
+ # authenticator screen. This checks accessibility metadata only.
125
+ stable_tree(device)
126
+ if url is None:
127
+ launcher = ("-a", "android.intent.action.MAIN", "-c", "android.intent.category.LAUNCHER")
128
+ result = adb(device, "shell", "cmd", "package", "resolve-activity", "--brief", *launcher, "-p", package)
129
+ component = re.search(rf"^{re.escape(package)}/[A-Za-z.][A-Za-z0-9_$.]*\r?$",
130
+ result.decode("utf-8", "replace"), re.MULTILINE)
131
+ if not component:
132
+ raise PhoneError("no launcher activity found for the requested package")
133
+ adb(device, "shell", "am", "start", "-W", *launcher,
134
+ "-n", shlex.quote(component[0].strip()), timeout=30)
135
+ else:
136
+ adb(device, "shell", "am", "start", "-W", "-a", "android.intent.action.VIEW",
137
+ "-d", shlex.quote(url), "-p", package, timeout=30)
138
+
139
+ focused = foreground(device)
140
+ focused_package = focused.split("/", 1)[0]
141
+ if focused_package != package:
142
+ raise PhoneError("navigation did not reach the requested foreground package")
143
+ return f"foreground {focused}"
144
+
145
+
146
+ def fetch_tree(device: str) -> tuple[ET.Element, bytes]:
147
+ # exec-out captures XML from /dev/tty without leaving screen data on device.
148
+ raw = adb(device, "exec-out", "uiautomator", "dump", "/dev/tty", timeout=20)
149
+ start = raw.find(b"<?xml")
150
+ end_marker = raw.find(b"</hierarchy>", start)
151
+ if start < 0 or end_marker < 0:
152
+ raise PhoneError("fresh UI hierarchy unavailable; no action taken")
153
+ xml = raw[start:end_marker + len(b"</hierarchy>")]
154
+ try:
155
+ return ET.fromstring(xml), xml
156
+ except ET.ParseError as exc:
157
+ raise PhoneError("UI hierarchy was malformed; no action taken") from exc
158
+
159
+
160
+ def has_password(root: ET.Element) -> bool:
161
+ return any(node.get("password", "false").lower() == "true" for node in root.iter())
162
+
163
+
164
+ def sensitive_screen(root: ET.Element) -> bool:
165
+ if has_password(root):
166
+ return True
167
+ # Sync is an entry in Firefox settings, separate from the account form.
168
+ sync_titles = {child for node in root.iter()
169
+ if any(child.get("resource-id") == "android:id/summary"
170
+ and child.get("text") == "Synchronise tabs, bookmarks, passwords and more."
171
+ for child in node)
172
+ for child in node if child.get("package") == "org.mozilla.firefox"
173
+ and child.get("resource-id") == "android:id/title"}
174
+ # Match only accessibility labels and hints; never put entered field values
175
+ # in diagnostics. A conservative false positive is safer than exposing an
176
+ # authentication, recovery, or one-time-code screen.
177
+ labels = [value for node in root.iter()
178
+ for key in ("text", "content-desc", "hint")
179
+ if (value := node.get(key, ""))
180
+ if not (key == "text" and node in sync_titles and value == "Sign in")
181
+ # Firefox's menu advertises Sync before any login UI is open.
182
+ if not (key == "content-desc" and node.get("package") == "org.mozilla.firefox"
183
+ and value == "Sign in Synchronise passwords, bookmarks and more")]
184
+ return any(SENSITIVE_SCREEN.search(label) or SENSITIVE_AUTH_HEADING.match(label)
185
+ for label in labels)
186
+
187
+
188
+ def guard_screen(root: ET.Element) -> None:
189
+ if sensitive_screen(root):
190
+ raise PhoneError("sensitive authentication or recovery screen; snapshot/action blocked")
191
+
192
+
193
+ def build_refs(root: ET.Element) -> tuple[list[str], dict[str, dict[str, object]]]:
194
+ lines: list[str] = []
195
+ refs: dict[str, dict[str, object]] = {}
196
+
197
+ def visit(node: ET.Element, depth: int = 0) -> None:
198
+ attrs = node.attrib
199
+ bounds = attrs.get("bounds", "")
200
+ if bounds and bounds != "[0,0][0,0]":
201
+ text = attrs.get("text", "")
202
+ desc = attrs.get("content-desc", "")
203
+ cls = attrs.get("class", "").rsplit(".", 1)[-1]
204
+ click = attrs.get("clickable") == "true"
205
+ edit = attrs.get("class") == EDIT_CLASS
206
+ # Edit fields may expose OTPs or other private input as node text.
207
+ label = (desc or attrs.get("hint", "")) if edit else (text or desc)
208
+ if click or edit or label:
209
+ ref = str(len(refs) + 1)
210
+ nums = [int(n) for n in re.findall(r"-?\d+", bounds)]
211
+ if len(nums) != 4:
212
+ raise PhoneError("invalid accessibility bounds")
213
+ x, y = (nums[0] + nums[2]) // 2, (nums[1] + nums[3]) // 2
214
+ safe_label = "[hidden sensitive field]" if attrs.get("password") == "true" else label
215
+ flags = []
216
+ if click:
217
+ flags.append("click")
218
+ if edit:
219
+ flags.append("edit")
220
+ if attrs.get("focused") == "true":
221
+ flags.append("focused")
222
+ if attrs.get("enabled") == "false":
223
+ flags.append("disabled")
224
+ label_part = f" {json.dumps(safe_label, ensure_ascii=False)}" if safe_label else ""
225
+ lines.append(f"[{ref}] {cls}{label_part} {{{','.join(flags)}}} ({x},{y})")
226
+ refs[ref] = {"x": x, "y": y, "click": click, "edit": edit,
227
+ "enabled": attrs.get("enabled") != "false",
228
+ "focused": attrs.get("focused") == "true"}
229
+ for child in node:
230
+ visit(child, depth + 1)
231
+
232
+ visit(root)
233
+ return lines, refs
234
+
235
+
236
+ def state_path(device: str) -> Path:
237
+ base = Path(os.environ.get("ANDROID_CONTROL_STATE", Path.home() / ".cache" / "android-control"))
238
+ return base / (hashlib.sha256(device.encode()).hexdigest()[:20] + ".json")
239
+
240
+
241
+ def save_state(path: Path, digest: str, refs: dict[str, dict[str, object]]) -> None:
242
+ path.parent.mkdir(parents=True, exist_ok=True)
243
+ payload = json.dumps({"sha256": digest, "refs": refs}, separators=(",", ":"))
244
+ # Direct write avoids creating and then deleting temporary files. A partial
245
+ # write fails schema validation on the next action, which stops safely.
246
+ with path.open("w", encoding="utf-8") as stream:
247
+ os.chmod(path, 0o600)
248
+ stream.write(payload)
249
+
250
+
251
+ def load_state(path: Path) -> dict[str, object]:
252
+ try:
253
+ data = json.loads(path.read_text(encoding="utf-8"))
254
+ if (not isinstance(data, dict)
255
+ or set(data) != {"sha256", "refs"}
256
+ or not isinstance(data["sha256"], str)
257
+ or not re.fullmatch(r"[0-9a-f]{64}", data["sha256"])
258
+ or not isinstance(data["refs"], dict)):
259
+ raise ValueError("schema")
260
+ for ref, target in data["refs"].items():
261
+ if (not isinstance(ref, str) or not ref.isdigit()
262
+ or not isinstance(target, dict)
263
+ or set(target) != {"x", "y", "click", "edit", "enabled", "focused"}
264
+ or type(target["x"]) is not int
265
+ or type(target["y"]) is not int
266
+ or any(type(target[key]) is not bool
267
+ for key in ("click", "edit", "enabled", "focused"))):
268
+ raise ValueError("target schema")
269
+ return data
270
+ except (OSError, TypeError, ValueError, json.JSONDecodeError) as exc:
271
+ raise PhoneError("no usable snapshot state; run snapshot first") from exc
272
+
273
+
274
+ def stable_tree(device: str, settle: float = 0.0) -> tuple[ET.Element, bytes]:
275
+ if not 0 <= settle <= MAX_SETTLE_SECONDS:
276
+ raise PhoneError(f"settle must be between 0 and {MAX_SETTLE_SECONDS:g} seconds")
277
+ root, xml = fetch_tree(device)
278
+ guard_screen(root)
279
+ if settle == 0:
280
+ return root, xml
281
+ deadline = time.monotonic() + settle
282
+ prior = hashlib.sha256(xml).digest()
283
+ while time.monotonic() < deadline:
284
+ time.sleep(min(SETTLE_INTERVAL_SECONDS, max(0, deadline - time.monotonic())))
285
+ root, xml = fetch_tree(device)
286
+ guard_screen(root)
287
+ current = hashlib.sha256(xml).digest()
288
+ if current == prior:
289
+ return root, xml
290
+ prior = current
291
+ raise PhoneError("UI did not settle before timeout; no snapshot state saved")
292
+
293
+
294
+ def snapshot(device: str, settle: float = 0.0) -> str:
295
+ root, xml = stable_tree(device, settle)
296
+ lines, refs = build_refs(root)
297
+ digest = hashlib.sha256(xml).hexdigest()
298
+ save_state(state_path(device), digest, refs)
299
+ return "\n".join([f"# device={device} refs={len(refs)} sha256={digest[:12]}", *lines])
300
+
301
+
302
+ def screen_size(device: str) -> tuple[int, int]:
303
+ output = adb(device, "shell", "wm", "size").decode("ascii", "replace")
304
+ sizes = re.findall(r"(\d+)x(\d+)", output)
305
+ if not sizes:
306
+ raise PhoneError("could not read screen dimensions")
307
+ width, height = map(int, sizes[-1])
308
+ if width <= 0 or height <= 0:
309
+ raise PhoneError("invalid screen dimensions")
310
+ return width, height
311
+
312
+
313
+ def checked_screen(device: str) -> tuple[ET.Element, bytes, int, int]:
314
+ root, xml = fetch_tree(device)
315
+ guard_screen(root)
316
+ width, height = screen_size(device)
317
+ return root, xml, width, height
318
+
319
+
320
+ def checked_gesture(device: str, action: list[str]) -> None:
321
+ root, xml, _, _ = checked_screen(device)
322
+ # Recheck immediately before input; refuse if the visible screen changed.
323
+ again, again_xml = fetch_tree(device)
324
+ guard_screen(again)
325
+ if hashlib.sha256(xml).digest() != hashlib.sha256(again_xml).digest():
326
+ raise PhoneError("screen changed before gesture; no action taken")
327
+ adb(device, *action)
328
+
329
+
330
+ def scroll(device: str, direction: str) -> str:
331
+ vectors = {
332
+ "down": (0.50, 0.72, 0.50, 0.30),
333
+ "up": (0.50, 0.30, 0.50, 0.72),
334
+ "left": (0.80, 0.50, 0.20, 0.50),
335
+ "right": (0.20, 0.50, 0.80, 0.50),
336
+ }
337
+ if direction not in vectors:
338
+ raise PhoneError("direction must be up, down, left, or right")
339
+ _, _, width, height = checked_screen(device)
340
+ points = vectors[direction]
341
+ x1, y1 = round(points[0] * width), round(points[1] * height)
342
+ x2, y2 = round(points[2] * width), round(points[3] * height)
343
+ checked_gesture(device, ["shell", "input", "swipe", str(x1), str(y1), str(x2), str(y2), "300"])
344
+ return f"scrolled {direction}"
345
+
346
+
347
+ def swipe(device: str, coords: list[int], duration_ms: int = 300) -> str:
348
+ if len(coords) != 4 or any(type(value) is not int for value in coords):
349
+ raise PhoneError("swipe requires four integer screen coordinates")
350
+ if not MIN_SWIPE_MS <= duration_ms <= MAX_SWIPE_MS:
351
+ raise PhoneError(f"swipe duration must be {MIN_SWIPE_MS}–{MAX_SWIPE_MS} ms")
352
+ _, _, width, height = checked_screen(device)
353
+ x1, y1, x2, y2 = coords
354
+ if not all(0 <= x <= width and 0 <= y <= height for x, y in ((x1, y1), (x2, y2))):
355
+ raise PhoneError("swipe coordinates fall outside the current screen")
356
+ checked_gesture(device, ["shell", "input", "swipe", *(str(value) for value in coords), str(duration_ms)])
357
+ return "swiped"
358
+
359
+
360
+ def tap_label(device: str, label: str) -> str:
361
+ if not label or label.strip() != label:
362
+ raise PhoneError("provide a non-empty exact accessibility label")
363
+ root, xml = fetch_tree(device)
364
+ guard_screen(root)
365
+ parents = {child: parent for parent in root.iter() for child in parent}
366
+ targets: dict[int, tuple[int, int]] = {}
367
+ width, height = screen_size(device)
368
+ for node in root.iter():
369
+ if label not in (node.get("text", ""), node.get("content-desc", "")):
370
+ continue
371
+ target = node
372
+ while target is not None and target.get("clickable") != "true":
373
+ target = parents.get(target)
374
+ if target is None or target.get("enabled") == "false":
375
+ continue
376
+ bounds = target.get("bounds", "")
377
+ nums = [int(value) for value in re.findall(r"-?\d+", bounds)]
378
+ if len(nums) != 4:
379
+ continue
380
+ left, top, right, bottom = nums
381
+ if (left < 0 or top < 0 or right > width or bottom > height
382
+ or left >= right or top >= bottom):
383
+ continue
384
+ x, y = (left + right) // 2, (top + bottom) // 2
385
+ targets[id(target)] = (x, y)
386
+ if len(targets) != 1:
387
+ raise PhoneError(f"expected one enabled clickable match for label; found {len(targets)}")
388
+ (x, y), = targets.values()
389
+ again, again_xml = fetch_tree(device)
390
+ guard_screen(again)
391
+ if hashlib.sha256(xml).digest() != hashlib.sha256(again_xml).digest():
392
+ raise PhoneError("screen changed before tap; no action taken")
393
+ adb(device, "shell", "input", "tap", str(x), str(y))
394
+ return f"tapped exact label {json.dumps(label, ensure_ascii=False)}"
395
+
396
+
397
+ def screenshot(device: str, output: str) -> str:
398
+ if not output:
399
+ raise PhoneError("choose a new screenshot path explicitly")
400
+ root, before_xml = fetch_tree(device)
401
+ guard_screen(root)
402
+ path = Path(output).expanduser()
403
+ if path.exists():
404
+ raise PhoneError("screenshot path already exists; refusing to overwrite")
405
+ if not path.parent.is_dir():
406
+ raise PhoneError("screenshot parent directory must already exist")
407
+ image = adb(device, "exec-out", "screencap", "-p", timeout=20)
408
+ if not image.startswith(b"\x89PNG\r\n\x1a\n"):
409
+ raise PhoneError("device did not return a PNG screenshot")
410
+ # Accessibility read and framebuffer capture are separate operations. A
411
+ # matching post-capture tree catches navigation/race changes, but cannot
412
+ # prove that the image contains no sensitive pixels unsupported by labels.
413
+ after, after_xml = fetch_tree(device)
414
+ guard_screen(after)
415
+ if hashlib.sha256(after_xml).digest() != hashlib.sha256(before_xml).digest():
416
+ raise PhoneError("screen changed during screenshot; image was not saved")
417
+ try:
418
+ fd = os.open(path, os.O_WRONLY | os.O_CREAT | os.O_EXCL, 0o600)
419
+ except FileExistsError as exc:
420
+ raise PhoneError("screenshot path already exists; refusing to overwrite") from exc
421
+ with os.fdopen(fd, "wb") as stream:
422
+ stream.write(image)
423
+ return str(path.resolve())
424
+
425
+
426
+ def checked_target(device: str, ref: str) -> dict[str, object]:
427
+ path = state_path(device)
428
+ old = load_state(path)
429
+ root, xml = fetch_tree(device)
430
+ guard_screen(root)
431
+ if hashlib.sha256(xml).hexdigest() != old["sha256"]:
432
+ raise PhoneError("screen changed since snapshot; no action taken; snapshot again")
433
+ target = old["refs"].get(ref)
434
+ if not target:
435
+ raise PhoneError(f"unknown ref {ref}; no action taken")
436
+ if not target["enabled"]:
437
+ raise PhoneError("target is disabled; no action taken")
438
+ _, current_refs = build_refs(root)
439
+ current = current_refs.get(ref)
440
+ keys = ("x", "y", "click", "edit", "enabled", "focused")
441
+ if not current or any(current.get(key) != target.get(key) for key in keys):
442
+ raise PhoneError("target no longer matches the fresh UI tree; no action taken")
443
+ return target
444
+
445
+
446
+ def tap(device: str, ref: str) -> str:
447
+ target = checked_target(device, ref)
448
+ if not target["click"]:
449
+ raise PhoneError("target is not an accessible clickable control")
450
+ adb(device, "shell", "input", "tap", str(target["x"]), str(target["y"]))
451
+ return f"tapped ref {ref}"
452
+
453
+
454
+ def key(device: str, key_name: str) -> str:
455
+ code = KEYS.get(key_name.lower())
456
+ if code is None:
457
+ raise PhoneError(f"key must be one of: {', '.join(KEYS)}")
458
+ root, _ = fetch_tree(device)
459
+ guard_screen(root)
460
+ adb(device, "shell", "input", "keyevent", str(code))
461
+ return f"key {key_name.lower()}"
462
+
463
+
464
+ def focused_safe_field(root: ET.Element, placeholder: str | None = None) -> ET.Element:
465
+ guard_screen(root)
466
+ focused = [n for n in root.iter() if n.get("class") == EDIT_CLASS and n.get("focused") == "true"]
467
+ if len(focused) != 1:
468
+ raise PhoneError("exactly one focused editable field is required")
469
+ node = focused[0]
470
+ if node.get("enabled") == "false":
471
+ raise PhoneError("focused field is disabled")
472
+ value = node.get("text", "")
473
+ is_exact_placeholder = (placeholder is not None and placeholder != ""
474
+ and value == placeholder and node.get("hint", "") == placeholder)
475
+ if value and not is_exact_placeholder:
476
+ raise PhoneError("focused field is not empty; refusing to append or replace")
477
+ field_label = " ".join((node.get("hint", ""), node.get("content-desc", "")))
478
+ if not SAFE_FIELD_LABEL.search(field_label):
479
+ raise PhoneError("focused field lacks a recognized non-sensitive label; refusing text entry")
480
+ return node
481
+
482
+
483
+ def type_text(device: str, text: str, placeholder: str | None = None) -> str:
484
+ if not text or not text.isascii() or any(c in "\r\n\t" for c in text):
485
+ raise PhoneError("type accepts non-empty, single-line ASCII text only")
486
+ root, original_xml = fetch_tree(device)
487
+ focused_safe_field(root, placeholder)
488
+ # The focused field or screen may have changed while this request was
489
+ # prepared. Require an identical fresh hierarchy immediately before input.
490
+ before_send, before_send_xml = fetch_tree(device)
491
+ focused_safe_field(before_send, placeholder)
492
+ if hashlib.sha256(original_xml).digest() != hashlib.sha256(before_send_xml).digest():
493
+ raise PhoneError("screen or focused field changed before text entry; no text sent")
494
+ escaped = shlex.quote(text.replace(" ", "%s"))
495
+ adb(device, "shell", "input", "text", escaped)
496
+ after, _ = fetch_tree(device)
497
+ guard_screen(after)
498
+ matches = [n for n in after.iter() if n.get("class") == EDIT_CLASS and n.get("focused") == "true"]
499
+ if (len(matches) != 1 or matches[0].get("enabled") == "false"
500
+ or not SAFE_FIELD_LABEL.search(" ".join((matches[0].get("hint", ""),
501
+ matches[0].get("content-desc", ""))))
502
+ or matches[0].get("text", "") != text):
503
+ raise PhoneError("typed value did not verify in the focused field")
504
+ return f"typed and verified {len(text)} characters"
505
+
506
+
507
+ def main(argv: list[str] | None = None) -> int:
508
+ parser = argparse.ArgumentParser(description=__doc__)
509
+ subs = parser.add_subparsers(dest="command", required=True)
510
+ subs.add_parser("devices")
511
+ for name in ("snapshot", "tap", "tap-label", "key", "type", "scroll", "swipe", "screenshot",
512
+ "foreground", "open"):
513
+ sub = subs.add_parser(name)
514
+ sub.add_argument("--device", required=True, help="explicit adb serial")
515
+ if name == "open":
516
+ sub.add_argument("package", help="explicit Android package name")
517
+ sub.add_argument("--url", help="non-secret HTTPS URL, or HTTP on loopback only")
518
+ elif name == "snapshot":
519
+ sub.add_argument("--settle", type=float, default=0.0,
520
+ help=f"wait for a stable tree, at most {MAX_SETTLE_SECONDS:g} seconds")
521
+ elif name == "tap":
522
+ sub.add_argument("ref")
523
+ elif name == "tap-label":
524
+ sub.add_argument("label")
525
+ elif name == "key":
526
+ sub.add_argument("key")
527
+ elif name == "type":
528
+ sub.add_argument("--placeholder", help="exact accessibility text and hint treated as an empty field")
529
+ sub.add_argument("text")
530
+ elif name == "scroll":
531
+ sub.add_argument("direction", choices=("up", "down", "left", "right"))
532
+ elif name == "swipe":
533
+ sub.add_argument("coords", nargs=4, type=int, metavar=("X1", "Y1", "X2", "Y2"))
534
+ sub.add_argument("--ms", type=int, default=300)
535
+ elif name == "screenshot":
536
+ sub.add_argument("output", help="new PNG path; existing files are never overwritten")
537
+ args = parser.parse_args(argv)
538
+ try:
539
+ if args.command == "devices":
540
+ print(devices())
541
+ elif args.command == "snapshot":
542
+ print(snapshot(args.device, args.settle))
543
+ elif args.command == "tap":
544
+ print(tap(args.device, args.ref))
545
+ elif args.command == "tap-label":
546
+ print(tap_label(args.device, args.label))
547
+ elif args.command == "key":
548
+ print(key(args.device, args.key))
549
+ elif args.command == "type":
550
+ print(type_text(args.device, args.text, args.placeholder))
551
+ elif args.command == "scroll":
552
+ print(scroll(args.device, args.direction))
553
+ elif args.command == "swipe":
554
+ print(swipe(args.device, args.coords, args.ms))
555
+ elif args.command == "screenshot":
556
+ print(screenshot(args.device, args.output))
557
+ elif args.command == "foreground":
558
+ print(foreground(args.device))
559
+ elif args.command == "open":
560
+ print(open_target(args.device, args.package, args.url))
561
+ return 0
562
+ except PhoneError as exc:
563
+ print(str(exc), file=sys.stderr)
564
+ return 2
565
+
566
+
567
+ if __name__ == "__main__":
568
+ raise SystemExit(main())