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 +1 -0
- tapherd/actions/__init__.py +1 -0
- tapherd/actions/android.py +393 -0
- tapherd/cli.py +491 -0
- tapherd/config.py +62 -0
- tapherd/devices/__init__.py +1 -0
- tapherd/devices/action_log.py +74 -0
- tapherd/devices/adb.py +229 -0
- tapherd/devices/registry.py +292 -0
- tapherd/devices/state.py +198 -0
- tapherd/errors.py +5 -0
- tapherd/mcp_config.py +99 -0
- tapherd/mcp_server.py +317 -0
- tapherd/recipes/__init__.py +1 -0
- tapherd/recipes/bundled/youtube_shorts_post.yaml +140 -0
- tapherd/recipes/catalog.py +65 -0
- tapherd/recipes/runner.py +332 -0
- tapherd/recipes/schema.py +275 -0
- tapherd/tease.py +31 -0
- tapherd/ui/__init__.py +1 -0
- tapherd/ui/screen.py +108 -0
- tapherd-0.1.0.data/data/share/tapherd/site/assets/demo-poster.jpg +0 -0
- tapherd-0.1.0.data/data/share/tapherd/site/assets/og-image.jpg +0 -0
- tapherd-0.1.0.data/data/share/tapherd/site/index.html +492 -0
- tapherd-0.1.0.data/data/share/tapherd/site/privacy.html +64 -0
- tapherd-0.1.0.dist-info/METADATA +147 -0
- tapherd-0.1.0.dist-info/RECORD +31 -0
- tapherd-0.1.0.dist-info/WHEEL +5 -0
- tapherd-0.1.0.dist-info/entry_points.txt +2 -0
- tapherd-0.1.0.dist-info/licenses/LICENSE +21 -0
- tapherd-0.1.0.dist-info/top_level.txt +1 -0
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
|
+
)
|