handsets 0.1.2__py3-none-any.whl

handsets/__init__.py

@@ -0,0 +1,48 @@
+"""Pythonic bindings for the Handsets Android control CLI.
+
+The CLI (`hs`) does the hard work: warm daemon, push-mirrored state,
+millisecond round-trips. This package wraps the CLI in a small,
+context-managed Session class so Python callers stop reimplementing the
+subprocess + JSON-parse + exit-code dance.
+
+    from handsets import Session
+    with Session() as d:
+        d.tap("Continue")
+        d.wait("Welcome", timeout="15s")
+
+Errors come back as typed exceptions; see ``handsets.errors``.
+"""
+
+from .errors import (
+    Ambiguous,
+    BadArg,
+    DaemonError,
+    DeviceGone,
+    ErrCode,
+    HandsetsError,
+    NotFound,
+    Precondition,
+    SecureWindow,
+    Timeout,
+    UnknownCmd,
+)
+from .session import Node, Session
+
+__all__ = [
+    "Session",
+    "Node",
+    # Exception hierarchy
+    "HandsetsError",
+    "NotFound",
+    "Timeout",
+    "Ambiguous",
+    "DaemonError",
+    "DeviceGone",
+    "Precondition",
+    "BadArg",
+    "SecureWindow",
+    "UnknownCmd",
+    "ErrCode",
+]
+
+__version__ = "0.1.2"

handsets/errors.py

@@ -0,0 +1,105 @@
+"""Exception types raised by :class:`handsets.Session`.
+
+The CLI's structured exit codes (2 NOT_FOUND, 3 TIMEOUT, 4 AMBIGUOUS) get
+broken-out subclasses since those three are the only ones scripts ever
+branch on in practice. The longer tail (DAEMON_ERROR, BAD_ARG,
+SECURE_WINDOW, ...) all collapse to exit 1 from the CLI but carry their
+full ``ErrCode`` in JSON-mode output, so we surface them as distinct
+exception types here too — anyone who *does* need to dispatch on them
+can catch the specific subclass.
+"""
+
+from __future__ import annotations
+
+from enum import Enum
+from typing import Optional
+
+
+class ErrCode(str, Enum):
+    """Structured error code as emitted by ``hs --json``."""
+
+    NOT_FOUND = "NOT_FOUND"
+    TIMEOUT = "TIMEOUT"
+    AMBIGUOUS = "AMBIGUOUS"
+    DAEMON_ERROR = "DAEMON_ERROR"
+    DEVICE_GONE = "DEVICE_GONE"
+    PRECONDITION = "PRECONDITION"
+    BAD_ARG = "BAD_ARG"
+    SECURE_WINDOW = "SECURE_WINDOW"
+    UNKNOWN_CMD = "UNKNOWN_CMD"
+    INTERNAL = "INTERNAL"
+
+
+class HandsetsError(Exception):
+    """Base class for all Handsets failures."""
+
+    code: ErrCode = ErrCode.INTERNAL
+
+    def __init__(self, detail: str = "", *, verb: Optional[str] = None) -> None:
+        self.detail = detail
+        self.verb = verb
+        msg = f"{self.code.value}: {detail}" if detail else self.code.value
+        if verb:
+            msg = f"{verb}: {msg}"
+        super().__init__(msg)
+
+
+class NotFound(HandsetsError):
+    code = ErrCode.NOT_FOUND
+
+
+class Timeout(HandsetsError):
+    code = ErrCode.TIMEOUT
+
+
+class Ambiguous(HandsetsError):
+    code = ErrCode.AMBIGUOUS
+
+
+class DaemonError(HandsetsError):
+    code = ErrCode.DAEMON_ERROR
+
+
+class DeviceGone(HandsetsError):
+    code = ErrCode.DEVICE_GONE
+
+
+class Precondition(HandsetsError):
+    code = ErrCode.PRECONDITION
+
+
+class BadArg(HandsetsError):
+    code = ErrCode.BAD_ARG
+
+
+class SecureWindow(HandsetsError):
+    code = ErrCode.SECURE_WINDOW
+
+
+class UnknownCmd(HandsetsError):
+    code = ErrCode.UNKNOWN_CMD
+
+
+_BY_CODE: dict[ErrCode, type[HandsetsError]] = {
+    ErrCode.NOT_FOUND: NotFound,
+    ErrCode.TIMEOUT: Timeout,
+    ErrCode.AMBIGUOUS: Ambiguous,
+    ErrCode.DAEMON_ERROR: DaemonError,
+    ErrCode.DEVICE_GONE: DeviceGone,
+    ErrCode.PRECONDITION: Precondition,
+    ErrCode.BAD_ARG: BadArg,
+    ErrCode.SECURE_WINDOW: SecureWindow,
+    ErrCode.UNKNOWN_CMD: UnknownCmd,
+    ErrCode.INTERNAL: HandsetsError,
+}
+
+
+def from_payload(verb: str, error: dict) -> HandsetsError:
+    """Construct the right subclass from a JSON ``{"code": ..., "detail": ...}``."""
+    raw = error.get("code", "INTERNAL")
+    try:
+        code = ErrCode(raw)
+    except ValueError:
+        code = ErrCode.INTERNAL
+    cls = _BY_CODE.get(code, HandsetsError)
+    return cls(error.get("detail", ""), verb=verb)

handsets/session.py

@@ -0,0 +1,329 @@
+"""Session — context-managed driver around the ``hs`` CLI.
+
+Each method shells out one ``hs --json`` invocation, parses the single
+JSON line that comes back, and either returns the ``result`` payload or
+raises a typed exception. The implementation is intentionally simple: the
+expensive bits (warm daemon, state mirror) live in the CLI, not here.
+
+Future work: keep an ``hs run -`` subprocess warm across calls and write
+verb lines to its stdin to amortise the ~5 ms per-process startup. The
+API surface won't change.
+"""
+
+from __future__ import annotations
+
+import json
+import shutil
+import subprocess
+from dataclasses import dataclass
+from typing import Iterable, List, Optional, Union
+
+from .errors import HandsetsError, from_payload
+
+Duration = Union[int, float, str]
+"""A wait budget. Integers/floats are milliseconds; strings accept the
+same ``250ms`` / ``5s`` suffixes the CLI's ``--timeout`` flag does."""
+
+
+@dataclass(frozen=True)
+class Node:
+    """One row from ``hs ui`` / ``hs find``."""
+
+    cls: str
+    id: str
+    text: str
+    desc: str
+    flags: str
+    x1: int = 0
+    y1: int = 0
+    x2: int = 0
+    y2: int = 0
+
+    @property
+    def coords(self) -> tuple[int, int]:
+        """Centre point in pixels."""
+        return ((self.x1 + self.x2) // 2, (self.y1 + self.y2) // 2)
+
+    @property
+    def clickable(self) -> bool:
+        return "c" in self.flags
+
+    @property
+    def visible(self) -> bool:
+        return "v" in self.flags
+
+
+def _fmt_duration(d: Duration) -> str:
+    """Normalise to the ``hs`` flag form (``250ms`` / ``5s`` / bare-ms-int)."""
+    if isinstance(d, str):
+        return d
+    return f"{int(d)}ms"
+
+
+class Session:
+    """A connected device. Use as a context manager.
+
+    >>> with Session() as d:
+    ...     d.tap("Continue")
+    ...     d.wait("Welcome", timeout="15s")
+    """
+
+    def __init__(
+        self,
+        serial: Optional[str] = None,
+        *,
+        binary: str = "hs",
+        auto_connect: bool = True,
+    ) -> None:
+        self.serial = serial
+        self.binary = binary
+        self._connected = False
+        self._auto_connect = auto_connect
+        if shutil.which(binary) is None:
+            raise FileNotFoundError(
+                f"`{binary}` not on $PATH — install handsets first "
+                "(see https://github.com/elliotgao2/handsets#install)"
+            )
+
+    # ─── context manager ──────────────────────────────────────────────
+
+    def __enter__(self) -> "Session":
+        if self._auto_connect:
+            self.connect()
+        return self
+
+    def __exit__(self, exc_type, exc, tb) -> None:
+        if self._connected:
+            try:
+                self.disconnect()
+            except HandsetsError:
+                # Best-effort teardown — don't mask the real exception.
+                pass
+
+    # ─── lifecycle ────────────────────────────────────────────────────
+
+    def connect(self) -> None:
+        """`hs use [serial]` — start the daemon and host-side state mirror."""
+        argv = ["use"]
+        if self.serial is not None:
+            argv += ["--device", self.serial]
+        self._call_text(argv)
+        self._connected = True
+
+    def disconnect(self, keep_jar: bool = False) -> None:
+        """`hs drop` — tear the daemon down."""
+        argv = ["drop"]
+        if self.serial is not None:
+            argv += ["--device", self.serial]
+        if keep_jar:
+            argv.append("--keep-jar")
+        self._call_text(argv)
+        self._connected = False
+
+    # ─── inspection ───────────────────────────────────────────────────
+
+    def ui(self) -> List[Node]:
+        """Return one :class:`Node` per actionable element on the active window."""
+        # `hs find '*'` returns every node; --json gives one structured line each.
+        return self.find("*")
+
+    def find(
+        self,
+        selector: str,
+        *,
+        visible: bool = False,
+        clickable: bool = False,
+        enabled: bool = False,
+        unique: bool = False,
+        nth: Optional[int] = None,
+        timeout: Optional[Duration] = None,
+    ) -> List[Node]:
+        argv = ["find", selector]
+        argv += self._action_flags(
+            visible=visible, clickable=clickable, enabled=enabled,
+            unique=unique, nth=nth, timeout=timeout,
+        )
+        rows = self._call_json_lines(argv)
+        return [self._node_from_payload(r["result"]) for r in rows if r.get("ok")]
+
+    def info(self) -> dict:
+        """Return the cached device snapshot as a dict."""
+        argv = ["show"]
+        if self.serial is not None:
+            argv = ["--device", self.serial] + argv
+        proc = subprocess.run(
+            [self.binary, *argv], capture_output=True, text=True, check=False,
+        )
+        # `hs show` (bare) is a text neofetch-style dump — surface as-is.
+        if proc.returncode != 0:
+            raise HandsetsError(proc.stderr.strip(), verb="show")
+        return {"raw": proc.stdout}
+
+    # ─── input ────────────────────────────────────────────────────────
+
+    def tap(
+        self,
+        target: Union[str, int],
+        y: Optional[int] = None,
+        *,
+        visible: bool = False,
+        clickable: bool = False,
+        enabled: bool = False,
+        unique: bool = False,
+        nth: Optional[int] = None,
+        timeout: Optional[Duration] = None,
+        retries: int = 0,
+        retry_delay: Optional[Duration] = None,
+    ) -> dict:
+        """Tap by text/selector (one arg) or coordinates (``tap(x, y)``)."""
+        if y is not None:
+            argv = ["tap", str(target), str(y)]
+        else:
+            argv = ["tap", str(target)]
+        argv += self._action_flags(
+            visible=visible, clickable=clickable, enabled=enabled,
+            unique=unique, nth=nth, timeout=timeout,
+            retries=retries, retry_delay=retry_delay,
+        )
+        return self._call_one_json(argv, verb="tap")
+
+    def type(
+        self,
+        selector_or_text: str,
+        text: Optional[str] = None,
+        *,
+        timeout: Optional[Duration] = None,
+    ) -> dict:
+        """``type(TEXT)`` types into the focused field; ``type(SELECTOR, TEXT)``
+        targets a specific node via ``ACTION_SET_TEXT`` (atomic, bypasses IME)."""
+        if text is None:
+            argv = ["type", selector_or_text]
+        else:
+            argv = ["type", selector_or_text, text]
+        argv += self._action_flags(timeout=timeout)
+        return self._call_one_json(argv, verb="type")
+
+    def submit(self, selector: Optional[str] = None) -> dict:
+        """Press the focused field's IME action key (Go / Search / Send / Done)."""
+        argv = ["submit"]
+        if selector is not None:
+            argv.append(selector)
+        return self._call_one_json(argv, verb="submit")
+
+    def paste(self, selector: Optional[str] = None) -> dict:
+        argv = ["paste"]
+        if selector is not None:
+            argv.append(selector)
+        return self._call_one_json(argv, verb="paste")
+
+    def go(self, key: str) -> dict:
+        """Key event by name (``back``, ``home``, ``recents``, ``enter``, …)."""
+        return self._call_one_json(["go", key], verb="go")
+
+    def swipe(self, direction_or_x1, *args, duration_ms: Optional[int] = None) -> dict:
+        argv = ["swipe", str(direction_or_x1), *[str(a) for a in args]]
+        if duration_ms is not None:
+            argv.append(str(duration_ms))
+        return self._call_one_json(argv, verb="swipe")
+
+    # ─── synchronisation ──────────────────────────────────────────────
+
+    def wait(
+        self,
+        spec: str,
+        *,
+        timeout: Optional[Duration] = None,
+        retries: int = 0,
+    ) -> dict:
+        argv = ["wait", spec]
+        argv += self._action_flags(timeout=timeout, retries=retries)
+        return self._call_one_json(argv, verb="wait")
+
+    # ─── internals ────────────────────────────────────────────────────
+
+    def _action_flags(
+        self,
+        *,
+        visible: bool = False,
+        clickable: bool = False,
+        enabled: bool = False,
+        unique: bool = False,
+        nth: Optional[int] = None,
+        timeout: Optional[Duration] = None,
+        retries: int = 0,
+        retry_delay: Optional[Duration] = None,
+    ) -> List[str]:
+        out: List[str] = []
+        if visible:   out.append("--visible")
+        if clickable: out.append("--clickable")
+        if enabled:   out.append("--enabled")
+        if unique:    out.append("--unique")
+        if nth is not None: out += ["--nth", str(nth)]
+        if timeout is not None: out += ["--timeout", _fmt_duration(timeout)]
+        if retries:   out += ["--retries", str(retries)]
+        if retry_delay is not None:
+            out += ["--retry-delay", _fmt_duration(retry_delay)]
+        return out
+
+    def _argv_prefix(self) -> List[str]:
+        argv: List[str] = [self.binary, "--json"]
+        if self.serial is not None:
+            argv += ["--device", self.serial]
+        return argv
+
+    def _call_text(self, argv: Iterable[str]) -> str:
+        proc = subprocess.run(
+            [self.binary, *argv], capture_output=True, text=True, check=False,
+        )
+        if proc.returncode != 0:
+            raise HandsetsError(
+                proc.stderr.strip() or proc.stdout.strip(),
+                verb=str(next(iter(argv), "?")),
+            )
+        return proc.stdout
+
+    def _call_one_json(self, argv: Iterable[str], *, verb: str) -> dict:
+        rows = self._call_json_lines(argv)
+        if not rows:
+            raise HandsetsError("no JSON line on stdout", verb=verb)
+        row = rows[-1]
+        if not row.get("ok"):
+            raise from_payload(verb, row.get("error", {}))
+        return row.get("result", {})
+
+    def _call_json_lines(self, argv: Iterable[str]) -> List[dict]:
+        proc = subprocess.run(
+            [*self._argv_prefix(), *argv],
+            capture_output=True, text=True, check=False,
+        )
+        rows: List[dict] = []
+        for line in proc.stdout.splitlines():
+            line = line.strip()
+            if not line:
+                continue
+            try:
+                rows.append(json.loads(line))
+            except json.JSONDecodeError:
+                # Non-JSON lines slip through for verbs that don't honour
+                # --json yet — ignore them; the exit code will decide.
+                continue
+        if proc.returncode != 0 and not rows:
+            raise HandsetsError(
+                proc.stderr.strip() or f"exit {proc.returncode}",
+                verb=str(next(iter(argv), "?")),
+            )
+        return rows
+
+    @staticmethod
+    def _node_from_payload(p: dict) -> Node:
+        return Node(
+            cls=p.get("class", ""),
+            id=p.get("id", ""),
+            text=p.get("text", ""),
+            desc=p.get("desc", ""),
+            flags=p.get("flags", ""),
+            x1=int(p.get("x1", 0) or 0),
+            y1=int(p.get("y1", 0) or 0),
+            x2=int(p.get("x2", 0) or 0),
+            y2=int(p.get("y2", 0) or 0),
+        )

handsets-0.1.2.dist-info/METADATA

@@ -0,0 +1,84 @@
+Metadata-Version: 2.4
+Name: handsets
+Version: 0.1.2
+Summary: Pythonic bindings for the Handsets Android control CLI
+Author: Handsets contributors
+License: MIT
+Project-URL: Homepage, https://github.com/elliotgao2/handsets
+Project-URL: Documentation, https://elliotgao2.github.io/handsets/
+Project-URL: Source, https://github.com/elliotgao2/handsets/tree/main/bindings/python
+Classifier: License :: OSI Approved :: MIT License
+Classifier: Programming Language :: Python :: 3
+Classifier: Topic :: Software Development :: Testing
+Classifier: Topic :: System :: Operating System Kernels :: Linux
+Classifier: Operating System :: MacOS
+Classifier: Operating System :: POSIX :: Linux
+Requires-Python: >=3.9
+Description-Content-Type: text/markdown
+
+# handsets — Python bindings
+
+A small, Pythonic wrapper around the [Handsets](https://github.com/elliotgao2/handsets)
+CLI (`hs`). Drives Android devices from Python without reimplementing the
+subprocess + JSON-parse + exit-code boilerplate every caller used to write
+by hand.
+
+## Install
+
+```bash
+pip install handsets
+```
+
+You also need the `hs` binary on `$PATH`. See the project
+[install instructions](https://github.com/elliotgao2/handsets#install).
+
+## Usage
+
+```python
+from handsets import Session
+
+with Session() as d:                   # `hs use` on enter, `hs drop` on exit
+    for node in d.ui():
+        print(node.cls, node.text, node.coords)
+
+    d.tap("Continue")                  # text lookup
+    d.tap(540, 860)                    # raw coords
+    d.type("EditText", "you@x.com")    # selector + text — atomic ACTION_SET_TEXT
+    d.submit()
+    d.wait("Welcome", timeout="15s")
+```
+
+Errors map to typed exceptions:
+
+```python
+from handsets import Session, NotFound, Timeout, Ambiguous
+
+try:
+    d.tap("Submit", unique=True, timeout="5s")
+except NotFound:
+    ...  # exit code 2 — selector matched nothing
+except Timeout:
+    ...  # exit code 3 — wait budget exhausted
+except Ambiguous:
+    ...  # exit code 4 — --unique saw multiple matches
+```
+
+Everything else (daemon errors, bad arguments, secure-window blocks)
+raises a generic `HandsetsError` whose `.code` attribute carries the
+structured `ErrCode` enum value from the CLI's JSON output.
+
+## Talking to a specific device
+
+```python
+Session(serial="PIXEL6_SERIAL")
+```
+
+Multiple sessions can run side-by-side; each one shells out independently.
+
+## Why a thin wrapper?
+
+The CLI already does the hard work: warm daemon, push-mirrored state,
+millisecond round-trips. The Python layer's job is to make that ergonomic
+— context managers, typed exceptions, no manual `subprocess.run`. Future
+versions may keep an `hs run` subprocess warm and stream commands over its
+stdin to amortise per-call process overhead.

handsets-0.1.2.dist-info/RECORD

@@ -0,0 +1,7 @@
+handsets/__init__.py,sha256=bpMnDlHGIMdttR6hTfOsLPttBYhkWlVan6lulBkKP2w,1017
+handsets/errors.py,sha256=INKACmQiTxPdXRlPGrGXoI6Z6ShGKE7dq628axC2eHc,2768
+handsets/session.py,sha256=PVlAlbYbzbQ0J0O-lDIKOYqhxFuDqNai5ZhphW93TQc,11651
+handsets-0.1.2.dist-info/METADATA,sha256=PqTTcmAq9W3N7kZkCQmxoA_0UQpjPje-o59qvUx_zmQ,2730
+handsets-0.1.2.dist-info/WHEEL,sha256=aeYiig01lYGDzBgS8HxWXOg3uV61G9ijOsup-k9o1sk,91
+handsets-0.1.2.dist-info/top_level.txt,sha256=WT96qUimGqGz2hcryXZseBQ9v5l2wm1uca20EIUKm7E,9
+handsets-0.1.2.dist-info/RECORD,,

handsets-0.1.2.dist-info/WHEEL

@@ -0,0 +1,5 @@
+Wheel-Version: 1.0
+Generator: setuptools (82.0.1)
+Root-Is-Purelib: true
+Tag: py3-none-any
+

handsets-0.1.2.dist-info/top_level.txt

@@ -0,0 +1 @@
+handsets