turboadb 0.1.0__py3-none-any.whl

turboadb/README.md

@@ -0,0 +1,453 @@
+# TurboADB
+
+**An Android ADB + scrcpy device toolkit for automotive/embedded Android
+(Android Automotive OS / IVI head units) and general Android work.**
+
+TurboADB wraps Google's `adb` and `scrcpy` behind one robust, structured layer
+you can drive three ways from a single `pip install turboadb`:
+
+1. **Python API** — `import turboadb` for scripts and test frameworks.
+2. **CLI** — `turboadb …`, fully argument-driven (argparse).
+3. **Desktop GUI** — `turboadb-gui`, a full PyQt5 app shipped as a prebuilt
+   Windows `.exe` (PyQt5 baked in) so it runs even where PyQt5 has no wheel
+   (e.g. Windows ARM64) — **no PyQt5 install required**.
+
+Every action returns a structured result (`CommandResult` / `TransferResult` /
+`StreamResult`), with a **safe mode** that returns an `OperationResult` instead
+of raising, and a typed exception hierarchy (`ADBError` base). All blocking work
+can run on background threads, so it never blocks or crashes the caller.
+
+---
+
+## Table of contents
+
+- [Install](#install)
+- [The GUI](#the-gui)
+- [Quick start (API)](#quick-start-api)
+- [Connecting — USB vs network (Wi-Fi / Ethernet)](#connecting--usb-vs-network-wifi--ethernet)
+- [Running shell commands](#running-shell-commands)
+- [Live logcat (continuous logs)](#live-logcat-continuous-logs)
+- [File transfer (push / pull)](#file-transfer-push--pull)
+- [App management](#app-management)
+- [Media — screenshot & screen record](#media--screenshot--screen-record)
+- [Port forwarding (forward / reverse)](#port-forwarding-forward--reverse)
+- [scrcpy mirroring (the visual session)](#scrcpy-mirroring-the-visual-session)
+- [Automotive (Android Automotive OS / IVI)](#automotive-android-automotive-os--ivi)
+- [Result objects & error handling](#result-objects--error-handling)
+- [CLI reference](#cli-reference)
+- [API map](#api-map)
+- [Building the GUI exe & releasing](#building-the-gui-exe--releasing)
+- [License](#license)
+
+---
+
+## Install
+
+```bash
+pip install turboadb
+```
+
+That gives you the Python API, the `turboadb` CLI, and `turboadb-gui` (which
+launches the bundled Windows exe; on other platforms install the GUI extra:
+`pip install "turboadb[gui]"`).
+
+TurboADB needs Google's **platform-tools (`adb`)** and, for mirroring,
+**`scrcpy`**. It auto-detects them on your `PATH`, in the Android SDK, or in
+common install locations. If they're missing it tells you exactly how to install
+them — or set explicit paths:
+
+```bash
+turboadb doctor          # shows where adb / scrcpy were found (or how to get them)
+```
+
+- `adb`: <https://developer.android.com/tools/releases/platform-tools>
+- `scrcpy`: <https://github.com/Genymobile/scrcpy>
+  (Windows: `winget install scrcpy` · macOS: `brew install scrcpy` · Linux: `apt install scrcpy`)
+
+Override detection any time with `ADBConfig(adb_path=..., scrcpy_path=...)`,
+the `TURBOADB_ADB` / `TURBOADB_SCRCPY` environment variables, or the GUI's
+Settings dialog.
+
+---
+
+## The GUI
+
+```bash
+turboadb-gui            # or: python -m turboadb.gui   (from source)
+turboadb-shortcut       # make a Desktop shortcut (Windows)
+```
+
+A tabbed, multi-device workspace:
+
+- **Tabbed multi-device sessions** — each device opens its own tab; tabs are
+  closable, movable, and there's a **`+`** new-tab button. A **Split/tile** view
+  shows several devices at once.
+- **Sidebar device manager** — saved targets **plus a LIVE `adb devices`** list
+  that auto-refreshes; a **Quick connect** filter box; right-click context menu
+  (New / Open / Edit / Duplicate / Delete). Double-click a live device to open it.
+- **Ribbon toolbar** with colorful buttons: Device, Shell, Logcat, Files, Apps,
+  Scrcpy (mirror), Screenshot, Split, Settings, Help, Exit.
+- **Per-device panels:** an interactive **Shell** terminal; a live **Logcat**
+  viewer (regex filter, level filter, pause/clear/save); a **Files** browser
+  (adb push/pull with file *and* folder pickers for both directions, progress
+  bar); an **Apps** manager (install via file dialog incl. split APKs, list,
+  uninstall, clear, start, stop); and a one-click **Mirror (scrcpy)** button.
+- A dark, color-coded **log dock** at the bottom.
+- **Settings** (persisted to `~/.turboadb/settings.json`, applied live):
+  dark/light theme, terminal font + size, default scrcpy options, adb/scrcpy
+  paths, logcat format. Defaults to a clean **black** dark theme; the light
+  theme isn't glaring.
+- **Crash-proof:** a startup-failure native popup + crash log, a global
+  exception hook that logs and shows a non-fatal popup, and clean thread
+  shutdown when a tab closes.
+
+The window/app icon is an automotive **speedometer** fused with the **Android
+robot** and a terminal prompt.
+
+---
+
+## Quick start (API)
+
+```python
+from turboadb import ADBHandler, ADBConfig
+
+# USB: the only attached device (or pass serial="..." to pick one)
+with ADBHandler() as dev:
+    print(dev.device_info().value if False else dev.shell("getprop ro.build.version.release").text)
+    dev.push("app.apk", "/data/local/tmp/app.apk")
+    dev.install("app.apk", grant_perms=True)
+
+    # live logs, with a regex match + tee to a file
+    dev.logcat(tag="ActivityManager", match=r"ANR|FATAL",
+               on_line=print, save_to="boot.log", stop_on_match=True)
+
+    dev.screenshot("shot.png")
+    dev.mirror(max_size=1280)            # launch scrcpy
+```
+
+The raw adb path is always available at `dev.adb_path`, and any adb command is a
+call away: `dev.adb("shell", "wm", "size")`.
+
+---
+
+## Connecting — USB vs network (Wi-Fi / Ethernet)
+
+**USB (local):**
+
+```python
+from turboadb import ADBHandler, ADBConfig, list_devices
+
+for d in list_devices():
+    print(d)                              # serial, state, model…
+
+with ADBHandler(ADBConfig(serial="emulator-5554")) as dev:
+    ...
+```
+
+**Network (remote head unit / IVI on the bench LAN):**
+
+```python
+# Enable TCP mode once while on USB, then connect wirelessly:
+with ADBHandler() as usb:
+    usb.tcpip(5555)
+
+with ADBHandler(ADBConfig(host="192.168.1.50", port=5555)) as hu:
+    print(hu.shell("getprop ro.build.characteristics").text)
+```
+
+**Android 11+ wireless pairing:**
+
+```python
+dev = ADBHandler(ADBConfig(host="192.168.1.50", port=5555))
+dev.pair("192.168.1.50", 37123, "482913")    # host:pairing_port + code
+dev.connect()
+```
+
+`connect()` auto-runs `adb connect host:port` for network targets, waits for the
+device, and verifies it's `device` (not `unauthorized`/`offline`) with a clear,
+actionable error if not.
+
+---
+
+## Running shell commands
+
+```python
+res = dev.shell("pm list packages -3")
+print(res.ok, res.exit_code, res.duration)
+for line in res.lines:
+    print(line)
+
+dev.shell("settings put global development_settings_enabled 1", check=True)
+dev.shell("svc power stayon true", su=True)      # wrap in su -c for rooted devices
+
+# an interactive shell session (used by the GUI terminal, usable in scripts)
+sh = dev.open_shell()
+sh.send_line("top -n 1")
+import time; time.sleep(1)
+print(sh.read().decode(errors="replace"))
+sh.close()
+```
+
+---
+
+## Live logcat (continuous logs)
+
+Stream logcat **live, line by line**, cleanly formatted, with regex matching,
+match callbacks, stop-on-match, and tee-to-file — plus tag/priority filters and
+buffer selection.
+
+```python
+# tag + minimum priority, collect ANR/FATAL, save everything, stop on first hit
+res = dev.logcat(tag="ActivityManager", priority="I",
+                 match=r"ANR|FATAL", on_match=lambda l: print("HIT:", l),
+                 save_to="session.log", stop_on_match=True,
+                 buffers=["main", "system", "crash"], clear_first=True)
+print(res.lines, "lines,", len(res.matches), "matches")
+
+# arbitrary streaming command + a stop event from another thread
+import threading
+stop = threading.Event()
+dev.logcat(on_line=print, stop_event=stop)       # stop.set() to end
+
+dev.logcat_clear()                                # adb logcat -c
+```
+
+`fmt=` sets the `-v` format (default `threadtime`); `dump=True` does `-d`
+(dump current buffer and exit); `filterspecs=[...]` passes explicit `TAG:LEVEL`
+specs. Lines are ANSI/control-char cleaned by default (`clean=True`).
+
+---
+
+## File transfer (push / pull)
+
+Files **and** folders, with a live percent callback (the GUI shows a progress
+bar):
+
+```python
+dev.push("local_dir/", "/sdcard/local_dir", on_progress=lambda p: print(p, "%"))
+dev.pull("/sdcard/Download", "out/", on_progress=print)
+
+tr = dev.push("big.bin", "/data/local/tmp/big.bin")
+print(tr.human_size, tr.human_speed, tr.duration)   # 12.0MB 48.0MB/s 0.25
+```
+
+---
+
+## App management
+
+```python
+dev.install("app.apk", replace=True, grant_perms=True)        # adb install -r -g
+dev.install_multiple(["base.apk", "split_config.en.apk"])     # split APKs
+dev.uninstall("com.example.app", keep_data=False)
+
+dev.list_packages(third_party=True)              # -> ["com.foo", ...]
+dev.clear_app("com.example.app")                 # pm clear
+dev.start_app("com.example.app")                 # launcher intent
+dev.start_activity("com.example.app/.MainActivity")
+dev.stop_app("com.example.app")                  # am force-stop
+dev.grant("com.example.app", "android.permission.CAMERA")
+dev.revoke("com.example.app", "android.permission.CAMERA")
+print(dev.current_activity())                    # foreground component
+```
+
+---
+
+## Media — screenshot & screen record
+
+```python
+dev.screenshot("shot.png")                       # exec-out screencap -p
+png_bytes = dev.screenshot()                     # raw PNG bytes if no path
+
+# record on-device, then pull it (stop early with a stop_event)
+dev.screen_record("clip.mp4", time_limit=20, size="1280x720", bit_rate="8M")
+```
+
+---
+
+## Port forwarding (forward / reverse)
+
+Stoppable handles (`adb forward` / `adb reverse`):
+
+```python
+fwd = dev.forward("tcp:9222", "localabstract:chrome_devtools_remote")
+# ... use 127.0.0.1:9222 on the host ...
+fwd.close()                                       # adb forward --remove
+
+with dev.reverse("tcp:8000", "tcp:8000"):         # device reaches your PC:8000
+    ...
+print(dev.list_forwards())
+```
+
+---
+
+## scrcpy mirroring (the visual session)
+
+Launch real-time screen mirroring + control — the visual analog of opening a
+remote desktop for a host:
+
+```python
+from turboadb import ScrcpyOptions
+
+sess = dev.mirror(max_size=1280, bit_rate="8M", stay_awake=True)
+# ... a scrcpy window is now mirroring & controlling the device ...
+sess.stop()
+
+# full control via ScrcpyOptions (crop is great for IVI displays):
+opts = ScrcpyOptions(crop="1920x1080:0:0", display_id=0,
+                     record="drive.mp4", turn_screen_off=True)
+dev.mirror(opts)
+```
+
+---
+
+## Automotive (Android Automotive OS / IVI)
+
+```python
+with ADBHandler(ADBConfig(host="192.168.1.50")) as hu:
+    info = hu.device_info()
+    print(info["manufacturer"], info["model"], "Android", info["android_version"])
+    if hu.is_automotive():
+        print("This is an Android Automotive OS head unit.")
+    # multi-display head units: mirror a specific display
+    hu.mirror(display_id=1, crop="1280x720:0:0")
+```
+
+`device_info()` includes an `automotive` flag (from the automotive hardware
+feature / build characteristics), so you can branch IVI-specific flows.
+
+---
+
+## Result objects & error handling
+
+Every operation returns a structured result:
+
+| Result          | Key fields / props                                              |
+|-----------------|----------------------------------------------------------------|
+| `CommandResult` | `.ok`, `.exit_code`, `.stdout`, `.stderr`, `.duration`, `.text`, `.lines` |
+| `TransferResult`| `.size_bytes`, `.duration`, `.files`, `.human_size`, `.human_speed` |
+| `StreamResult`  | `.lines`, `.matches`, `.matched`, `.saved_to`                  |
+| `OperationResult`| `.success`/`bool`, `.value`, `.error`, `.unwrap()` (safe mode) |
+
+**Raise mode (default)** — great for test automation:
+
+```python
+try:
+    dev.shell("false", check=True)
+except ADBError as exc:
+    print("failed:", exc)
+```
+
+**Safe mode** — great for GUIs (never throws):
+
+```python
+dev = ADBHandler(cfg, safe=True)
+res = dev.install("app.apk")
+if res:                      # OperationResult is falsy on failure
+    print("ok:", res.value)
+else:
+    print("error:", res.error)
+```
+
+Exception hierarchy (catch `ADBError` for everything):
+`ADBNotFoundError`, `ADBConnectionError`, `ADBTimeoutError`,
+`ADBNotConnectedError`, `ADBCommandError`, `ADBTransferError`,
+`ADBInstallError`, `ScrcpyError`.
+
+---
+
+## CLI reference
+
+```
+turboadb doctor                      # is adb / scrcpy installed?
+turboadb devices                     # list attached/known devices
+turboadb info        [-s S]          # device identity / build / automotive flag
+turboadb shell       [-s S] -- CMD…  # one-shot adb shell (use --su to wrap in su -c)
+turboadb logcat      [-s S] [--tag T --priority I --match RE --save F --stop-on-match --clear --dump]
+turboadb logcat-clear[-s S]
+turboadb push        [-s S] LOCAL REMOTE
+turboadb pull        [-s S] REMOTE LOCAL
+turboadb install     [-s S] APK [APK…] [--grant --downgrade --no-replace]
+turboadb uninstall   [-s S] PKG [--keep-data]
+turboadb packages    [-s S] [--third-party --system] [FILTER]
+turboadb clear       [-s S] PKG
+turboadb start|stop  [-s S] PKG
+turboadb screenshot  [-s S] PATH
+turboadb record      [-s S] PATH [--time-limit 30 --size 1280x720 --bit-rate 8M]
+turboadb forward     [-s S] LOCAL REMOTE      # stays until Ctrl+C
+turboadb reverse     [-s S] REMOTE LOCAL
+turboadb scrcpy      [-s S] [--max-size 1280 --bit-rate 8M --record F --turn-screen-off --no-control --wait]
+turboadb connect     HOST:PORT
+turboadb disconnect  [HOST:PORT]
+turboadb tcpip       [-s S] [PORT]
+turboadb pair        HOST:PAIRPORT CODE
+turboadb reboot      [-s S] [recovery|bootloader|sideload]
+turboadb root        [-s S]
+turboadb gui                          # launch the desktop GUI
+```
+
+`-s` accepts a USB serial **or** a `host:port` network target. Add `--json` to
+most commands for machine-readable output. Examples:
+
+```bash
+turboadb -s 192.168.1.50:5555 shell -- dumpsys power | findstr mWakefulness
+turboadb logcat --tag ActivityManager --priority I --match "ANR|FATAL" --save boot.log
+turboadb install base.apk split_config.en.apk --grant
+turboadb screenshot dash.png
+turboadb scrcpy --max-size 1280 --bit-rate 8M
+```
+
+Other console scripts: `turboadb-gui`, `turboadb-docs`, `turboadb-shortcut`.
+
+---
+
+## API map
+
+```
+turboadb
+├── ADBHandler(config=ADBConfig|None, *, serial=, safe=, quiet=, log_callback=)
+│   ├── connect() / disconnect() / is_connected / get_state() / wait_for_device()
+│   ├── tcpip(port) / connect_tcp(host, port) / pair(host, port, code)
+│   ├── reboot(mode) / root() / unroot() / remount()
+│   ├── getprop(name?) / device_info() / is_automotive()
+│   ├── shell(cmd, su=, check=) / shell_many() / open_shell() -> ShellSession
+│   ├── iter_lines(args) / stream(args, …) / logcat(…) / logcat_clear()
+│   ├── push(local, remote, on_progress=) / pull(remote, local, on_progress=)
+│   ├── install() / install_multiple() / uninstall() / list_packages()
+│   ├── clear_app() / start_app() / start_activity() / stop_app()
+│   ├── grant() / revoke() / current_activity()
+│   ├── screenshot(path?) / screen_record(path, …)
+│   ├── forward(local, remote) / reverse(remote, local) -> ForwardHandle
+│   ├── list_forwards() / remove_all_forwards()
+│   ├── mirror(options?|**opts) -> ScrcpySession
+│   └── adb(*args)  ·  adb_path  ·  serial
+├── ADBConfig / ScrcpyOptions
+├── Device / list_devices() / first_online()
+├── launch_scrcpy() / ScrcpySession
+├── find_adb() / find_scrcpy() / adb_available() / scrcpy_available() / diagnose()
+├── CommandResult / TransferResult / StreamResult / OperationResult / strip_ansi
+└── ADBError + ADBNotFoundError / ADBConnectionError / ADBTimeoutError /
+    ADBNotConnectedError / ADBCommandError / ADBTransferError /
+    ADBInstallError / ScrcpyError
+```
+
+---
+
+## Building the GUI exe & releasing
+
+```bash
+python scripts/make_icon.py        # (re)generate the icon
+python scripts/build_exe.py        # -> dist/turboadb-gui.exe (PyQt5 baked in)
+# copy the exe into turboadb/bin/ so the wheel ships it, then:
+python scripts/release.py patch    # bump -> test -> build -> twine check -> upload
+```
+
+`turboadb-gui` runs the bundled exe when present and falls back to running from
+source (`turboadb[gui]`) otherwise. The release helper reads the PyPI token from
+`TWINE_PASSWORD` (never hard-coded) and supports `--wheel-only` if a flaky
+network makes the sdist+wheel upload hang.
+
+---
+
+## License
+
+MIT — see [LICENSE](LICENSE).

turboadb/__init__.py

@@ -0,0 +1,65 @@
+"""
+TurboADB
+========
+
+An Android **ADB + scrcpy** device toolkit for automotive/embedded Android
+(Android Automotive OS / IVI head units) and general Android work. Wraps Google's
+``adb`` and ``scrcpy`` behind one robust, structured API — usable as a Python
+library, a CLI (``turboadb``), or a full PyQt5 desktop GUI (``turboadb-gui``).
+
+Quick start
+-----------
+    from turboadb import ADBHandler, ADBConfig
+
+    # USB (only device) — or serial="..." to pick one of several
+    with ADBHandler() as dev:
+        print(dev.shell("getprop ro.build.version.release").text)
+        dev.push("app.apk", "/data/local/tmp/app.apk")
+        dev.install("app.apk", grant_perms=True)
+        dev.logcat(tag="ActivityManager", match=r"ANR|FATAL", on_line=print)
+
+    # Network / Wi-Fi head unit
+    with ADBHandler(ADBConfig(host="192.168.1.50", port=5555)) as hu:
+        hu.mirror(max_size=1280)          # launch scrcpy
+
+Every action returns a structured result (``CommandResult`` / ``TransferResult``
+/ ``StreamResult``). Pass ``safe=True`` to get an ``OperationResult`` instead of
+exceptions (ideal for GUIs). The raw adb path is always at ``dev.adb_path``.
+"""
+
+from __future__ import annotations
+
+__version__ = "0.1.0"
+
+from .config import ADBConfig, ScrcpyOptions
+from .core import ADBHandler, ADBDevice, ShellSession, ForwardHandle
+from .devices import Device, list_devices, first_online
+from .scrcpy import launch_scrcpy, ScrcpySession
+from .tools import (find_adb, find_scrcpy, adb_available, scrcpy_available,
+                    adb_version, diagnose, ADB_DOWNLOAD, SCRCPY_DOWNLOAD)
+from .results import (CommandResult, TransferResult, StreamResult,
+                      OperationResult, strip_ansi)
+from .exceptions import (
+    ADBError,
+    ADBNotFoundError,
+    ADBConnectionError,
+    ADBTimeoutError,
+    ADBNotConnectedError,
+    ADBCommandError,
+    ADBTransferError,
+    ADBInstallError,
+    ScrcpyError,
+)
+
+__all__ = [
+    "ADBHandler", "ADBDevice", "ADBConfig", "ScrcpyOptions", "ShellSession",
+    "ForwardHandle", "Device", "list_devices", "first_online",
+    "launch_scrcpy", "ScrcpySession",
+    "find_adb", "find_scrcpy", "adb_available", "scrcpy_available",
+    "adb_version", "diagnose", "ADB_DOWNLOAD", "SCRCPY_DOWNLOAD",
+    "CommandResult", "TransferResult", "StreamResult", "OperationResult",
+    "strip_ansi",
+    "ADBError", "ADBNotFoundError", "ADBConnectionError", "ADBTimeoutError",
+    "ADBNotConnectedError", "ADBCommandError", "ADBTransferError",
+    "ADBInstallError", "ScrcpyError", "__version__",
+]

turboadb/__main__.py

@@ -0,0 +1,6 @@
+"""Enable ``python -m turboadb`` to run the CLI."""
+
+from .cli import main
+
+if __name__ == "__main__":
+    raise SystemExit(main())