tapherd 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.
tapherd/__init__.py ADDED
@@ -0,0 +1 @@
1
+ """Local Android device tools for TapHerd."""
@@ -0,0 +1 @@
1
+ """Android input and file actions."""
@@ -0,0 +1,393 @@
1
+ """Run Android input, app launch, and transfer operations on an active device."""
2
+
3
+ import base64
4
+ import mimetypes
5
+ import re
6
+ from contextlib import suppress
7
+ from dataclasses import dataclass
8
+ from enum import StrEnum
9
+ from pathlib import Path
10
+ from uuid import uuid4
11
+
12
+ from tapherd.devices.adb import DeviceConnection
13
+ from tapherd.errors import TapHerdError
14
+ from tapherd.ui.screen import read_screen
15
+
16
+ _ADB_KEYBOARD_PACKAGE = "com.android.adbkeyboard"
17
+ _ADB_KEYBOARD_INPUT_METHODS = {
18
+ f"{_ADB_KEYBOARD_PACKAGE}/.AdbIME",
19
+ f"{_ADB_KEYBOARD_PACKAGE}/{_ADB_KEYBOARD_PACKAGE}.AdbIME",
20
+ }
21
+ _MEDIA_DIRECTORY = "/sdcard/DCIM/TapHerd"
22
+ _POSTING_ALLOW = (
23
+ "android.permission.READ_MEDIA_IMAGES",
24
+ "android.permission.READ_MEDIA_VIDEO",
25
+ "android.permission.READ_EXTERNAL_STORAGE",
26
+ )
27
+ _SELECTED_MEDIA_ONLY = "android.permission.READ_MEDIA_VISUAL_USER_SELECTED"
28
+ _POSTING_DENY = ("android.permission.CAMERA", "android.permission.RECORD_AUDIO")
29
+ _TYPE_CHUNK = 50
30
+ _MEDIA_NAME = re.compile(r"[A-Za-z0-9_-]+-[0-9a-f]{32}\.[a-z0-9]{1,5}")
31
+ _PACKAGE = re.compile(r"[A-Za-z][A-Za-z0-9_]*(?:\.[A-Za-z][A-Za-z0-9_]*)+")
32
+ _COMPONENT = re.compile(r"[A-Za-z][\w.]*/[\w.$]+")
33
+
34
+
35
+ class Key(StrEnum):
36
+ BACK = "back"
37
+ HOME = "home"
38
+ ENTER = "enter"
39
+ RECENTS = "recents"
40
+ DELETE = "delete"
41
+
42
+
43
+ _KEYCODES = {
44
+ Key.BACK: "KEYCODE_BACK",
45
+ Key.HOME: "KEYCODE_HOME",
46
+ Key.ENTER: "KEYCODE_ENTER",
47
+ Key.RECENTS: "KEYCODE_APP_SWITCH",
48
+ Key.DELETE: "KEYCODE_DEL",
49
+ }
50
+
51
+
52
+ class Direction(StrEnum):
53
+ UP = "up"
54
+ DOWN = "down"
55
+ LEFT = "left"
56
+ RIGHT = "right"
57
+
58
+
59
+ @dataclass(frozen=True, slots=True)
60
+ class TapSelector:
61
+ text: str | None = None
62
+ resource_id: str | None = None
63
+ content_desc: str | None = None
64
+
65
+ def coordinates(self, device: DeviceConnection) -> tuple[int, int]:
66
+ fields = [
67
+ (name, value)
68
+ for name, value in (
69
+ ("text", self.text),
70
+ ("resource_id", self.resource_id),
71
+ ("content_desc", self.content_desc),
72
+ )
73
+ if value is not None
74
+ ]
75
+ if len(fields) != 1 or fields[0][1] == "":
76
+ raise TapHerdError("Choose one non-empty selector field for the tap.")
77
+ field, value = fields[0]
78
+ matches = {
79
+ element.center
80
+ for element in read_screen(device, limit=None)
81
+ if getattr(element, field) == value
82
+ }
83
+ if len(matches) != 1:
84
+ cause = "found no match" if not matches else "matched several locations"
85
+ raise TapHerdError(
86
+ f"The {field} selector {cause}. Run `tapherd inspect` or "
87
+ "`tapherd screenshot`, then choose a unique selector or use coordinates."
88
+ )
89
+ return matches.pop()
90
+
91
+
92
+ @dataclass(frozen=True, slots=True)
93
+ class AndroidActions:
94
+ device: DeviceConnection
95
+
96
+ def tap(
97
+ self,
98
+ x: int | None = None,
99
+ y: int | None = None,
100
+ *,
101
+ selector: TapSelector | None = None,
102
+ ) -> None:
103
+ if selector is not None and x is None and y is None:
104
+ x, y = selector.coordinates(self.device)
105
+ elif selector is not None or x is None or y is None:
106
+ raise TapHerdError("Provide both x and y coordinates or one tap selector.")
107
+ if min(x, y) < 0:
108
+ raise TapHerdError(
109
+ "Choose non-negative tap coordinates from the device screen."
110
+ )
111
+ self.device.shell("input", "tap", str(x), str(y))
112
+
113
+ def swipe(
114
+ self,
115
+ coordinates: tuple[int | None, int | None, int | None, int | None]
116
+ | None = None,
117
+ *,
118
+ direction: Direction | None = None,
119
+ duration_ms: int = 300,
120
+ ) -> None:
121
+ if coordinates and coordinates != (None, None, None, None):
122
+ x1, y1, x2, y2 = coordinates
123
+ if (
124
+ x1 is None
125
+ or y1 is None
126
+ or x2 is None
127
+ or y2 is None
128
+ or direction is not None
129
+ ):
130
+ raise TapHerdError(
131
+ "Provide all four swipe coordinates or a swipe direction."
132
+ )
133
+ points = (x1, y1, x2, y2)
134
+ elif direction is not None:
135
+ width, height = self.device.screen_size()
136
+ mid_x, mid_y = width // 2, height // 2
137
+ start_x, end_x = width // 5, width * 4 // 5
138
+ start_y, end_y = height // 5, height * 4 // 5
139
+ points = {
140
+ Direction.UP: (mid_x, end_y, mid_x, start_y),
141
+ Direction.DOWN: (mid_x, start_y, mid_x, end_y),
142
+ Direction.LEFT: (end_x, mid_y, start_x, mid_y),
143
+ Direction.RIGHT: (start_x, mid_y, end_x, mid_y),
144
+ }[direction]
145
+ else:
146
+ raise TapHerdError(
147
+ "Provide all four swipe coordinates or a swipe direction."
148
+ )
149
+ if min(points) < 0 or duration_ms < 1:
150
+ raise TapHerdError(
151
+ "Use non-negative coordinates and a positive swipe duration."
152
+ )
153
+ self.device.shell(
154
+ "input",
155
+ "swipe",
156
+ *map(str, points),
157
+ str(duration_ms),
158
+ timeout=15 + duration_ms / 1_000,
159
+ )
160
+
161
+ def type_text(self, text: str) -> None:
162
+ if not text:
163
+ return
164
+ ime = self.device.shell(
165
+ "settings", "--user", "current", "get", "secure", "default_input_method"
166
+ )
167
+ if ime in _ADB_KEYBOARD_INPUT_METHODS:
168
+ payload = base64.b64encode(text.encode("utf-8")).decode("ascii")
169
+ self.device.shell(
170
+ "am",
171
+ "broadcast",
172
+ "--user",
173
+ "current",
174
+ "-a",
175
+ "ADB_INPUT_B64",
176
+ "-p",
177
+ _ADB_KEYBOARD_PACKAGE,
178
+ "--es",
179
+ "msg",
180
+ payload,
181
+ )
182
+ return
183
+ if not (text.isascii() and text.isprintable()):
184
+ raise TapHerdError(
185
+ "Type single-line plain ASCII, or install and select ADBKeyboard to type "
186
+ "emoji, other Unicode, or several lines. See docs/TROUBLESHOOTING.md."
187
+ )
188
+ # Android treats %s as a space. Put a literal percent and s in separate commands.
189
+ # Long text is sent in short pieces because `input text` can drop the end.
190
+ for part in text.replace("%s", "%\0s").split("\0"):
191
+ for start in range(0, len(part), _TYPE_CHUNK):
192
+ chunk = part[start : start + _TYPE_CHUNK]
193
+ self.device.shell("input", "text", chunk.replace(" ", "%s"))
194
+
195
+ def press_key(self, key: Key) -> None:
196
+ self.device.shell("input", "keyevent", _KEYCODES[key])
197
+
198
+ def open_app(self, package: str) -> None:
199
+ if not _PACKAGE.fullmatch(package):
200
+ raise TapHerdError(
201
+ "Enter an Android package name such as com.android.settings."
202
+ )
203
+ try:
204
+ # Apps such as TikTok and Instagram declare several launcher entries,
205
+ # so a package-only launch can't resolve. Start the exact launcher
206
+ # activity when Android can name it.
207
+ component = self._launcher_activity(package)
208
+ target = ("-n", component) if component else ("-p", package)
209
+ output = self.device.shell(
210
+ "am",
211
+ "start",
212
+ "-W",
213
+ "-a",
214
+ "android.intent.action.MAIN",
215
+ "-c",
216
+ "android.intent.category.LAUNCHER",
217
+ *target,
218
+ timeout=25,
219
+ )
220
+ if "Status: ok" not in output:
221
+ raise TapHerdError("Android did not confirm that the app opened.")
222
+ except TapHerdError as error:
223
+ raise TapHerdError(
224
+ f"Could not open {package} on {self.device.serial}. "
225
+ "Check that the app is installed and has a launcher, then try again."
226
+ ) from error
227
+
228
+ def _launcher_activity(self, package: str) -> str | None:
229
+ """Return the activity Android's launcher would open, such as pkg/.Main."""
230
+ try:
231
+ output = self.device.shell(
232
+ "cmd",
233
+ "package",
234
+ "resolve-activity",
235
+ "--brief",
236
+ "-a",
237
+ "android.intent.action.MAIN",
238
+ "-c",
239
+ "android.intent.category.LAUNCHER",
240
+ package,
241
+ )
242
+ except TapHerdError:
243
+ return None
244
+ lines = [line.strip() for line in output.splitlines() if line.strip()]
245
+ component = lines[-1] if lines else ""
246
+ if _COMPONENT.fullmatch(component) and component.startswith(f"{package}/"):
247
+ return component
248
+ return None
249
+
250
+ def install_apk(self, path: Path) -> None:
251
+ if not path.is_file() or path.suffix.lower() != ".apk":
252
+ raise TapHerdError("Choose an existing local .apk file to install.")
253
+ remote = f"/data/local/tmp/tapherd-{uuid4().hex}.apk"
254
+ try:
255
+ self.device.push_file(path, remote)
256
+ if (
257
+ self.device.shell("pm", "install", "-r", remote, timeout=120)
258
+ != "Success"
259
+ ):
260
+ raise TapHerdError("Android did not confirm the APK installation.")
261
+ except TapHerdError as error:
262
+ raise TapHerdError(
263
+ f"Could not install {path.name} on {self.device.serial}. "
264
+ "Check that the APK is signed and compatible, then check for prompts on the device."
265
+ ) from error
266
+ finally:
267
+ with suppress(TapHerdError):
268
+ self.device.shell("rm", "-f", remote)
269
+
270
+ def push_media(self, path: Path) -> str:
271
+ kind, _ = mimetypes.guess_type(path.name)
272
+ if not path.is_file() or not kind or not kind.startswith(("image/", "video/")):
273
+ raise TapHerdError("Choose an existing local image or video to push.")
274
+
275
+ token = uuid4().hex
276
+ name = re.sub(r"[^A-Za-z0-9_-]+", "-", path.stem).strip("-_")[:64] or "media"
277
+ destination = f"{_MEDIA_DIRECTORY}/{name}-{token}{path.suffix.lower()}"
278
+ temporary = f"{_MEDIA_DIRECTORY}/.tapherd-{token}.part"
279
+ self.device.shell("mkdir", "-p", _MEDIA_DIRECTORY)
280
+ try:
281
+ self.device.push_file(path, temporary)
282
+ self.device.shell("mv", temporary, destination)
283
+ except TapHerdError:
284
+ with suppress(TapHerdError):
285
+ self.device.shell("rm", "-f", temporary)
286
+ raise
287
+
288
+ # MediaStore can synchronously index the file on current Android versions.
289
+ with suppress(TapHerdError):
290
+ result = self.device.shell(
291
+ "content",
292
+ "call",
293
+ "--uri",
294
+ "content://media",
295
+ "--method",
296
+ "scan_file",
297
+ "--arg",
298
+ destination,
299
+ timeout=30,
300
+ )
301
+ if "content://media/" in result:
302
+ return destination
303
+
304
+ try:
305
+ result = self.device.shell(
306
+ "am",
307
+ "broadcast",
308
+ "-a",
309
+ "android.intent.action.MEDIA_SCANNER_SCAN_FILE",
310
+ "-d",
311
+ f"file://{destination}",
312
+ )
313
+ if "Broadcast completed:" not in result:
314
+ raise TapHerdError("Android did not accept the media scan broadcast.")
315
+ except TapHerdError as error:
316
+ raise TapHerdError(
317
+ f"Copied media to {destination} but could not request a scan. "
318
+ "Find that file in Android's Files app before retrying."
319
+ ) from error
320
+ return destination
321
+
322
+ def prepare_app(self, package: str) -> dict[str, list[str]]:
323
+ """Get a posting app ready for uploads without permission prompts.
324
+
325
+ Gives the app access to all photos and videos (not just selected ones)
326
+ and turns off its camera and microphone so Android stops asking. Android
327
+ closes the app if it is running when a permission is turned off.
328
+ """
329
+ if not _PACKAGE.fullmatch(package):
330
+ raise TapHerdError(
331
+ "Enter an Android package name such as com.google.android.youtube."
332
+ )
333
+ result: dict[str, list[str]] = {"allowed": [], "denied": [], "skipped": []}
334
+ for permission in _POSTING_ALLOW:
335
+ try:
336
+ self.device.shell("pm", "grant", package, permission)
337
+ result["allowed"].append(permission)
338
+ except TapHerdError:
339
+ # The app doesn't request this permission on this Android version.
340
+ result["skipped"].append(permission)
341
+ with suppress(TapHerdError):
342
+ self.device.shell("pm", "revoke", package, _SELECTED_MEDIA_ONLY)
343
+ for permission in _POSTING_DENY:
344
+ try:
345
+ self.device.shell("pm", "revoke", package, permission)
346
+ self.device.shell(
347
+ "pm",
348
+ "set-permission-flags",
349
+ package,
350
+ permission,
351
+ "user-set",
352
+ "user-fixed",
353
+ )
354
+ result["denied"].append(permission)
355
+ except TapHerdError:
356
+ result["skipped"].append(permission)
357
+ if not result["allowed"]:
358
+ raise TapHerdError(
359
+ f"{package} on {self.device.serial} did not accept photo and video "
360
+ "access. Check that the app is installed, then try again."
361
+ )
362
+ return result
363
+
364
+ def remove_media(self, device_path: str) -> None:
365
+ """Delete a file that push_media copied, and drop it from the gallery."""
366
+ name = device_path.removeprefix(f"{_MEDIA_DIRECTORY}/")
367
+ if (
368
+ name == device_path
369
+ or not _MEDIA_NAME.fullmatch(name)
370
+ or name.startswith(".")
371
+ ):
372
+ raise TapHerdError(
373
+ f"Only files that push_media copied into {_MEDIA_DIRECTORY} can be "
374
+ "removed. Pass the device_path that push_media returned."
375
+ )
376
+ self.device.shell("rm", "-f", device_path)
377
+ # Ask MediaStore to rescan the now-missing path so the gallery forgets it.
378
+ with suppress(TapHerdError):
379
+ self.device.shell(
380
+ "content",
381
+ "call",
382
+ "--uri",
383
+ "content://media",
384
+ "--method",
385
+ "scan_file",
386
+ "--arg",
387
+ device_path,
388
+ timeout=30,
389
+ )
390
+ if self.device.shell("ls", _MEDIA_DIRECTORY).split().count(name):
391
+ raise TapHerdError(
392
+ f"Android still lists {device_path}. Check the device's Files app."
393
+ )