client.phones.create() starts a session on one of your organization’s
phones. Its connect() returns a Phone.
client.phones
| Method | Does |
|---|---|
create(*, phone_id=None, idle_timeout_seconds=None, name=None) | Start a session on any idle phone, or on phone_id. Raises ConflictError when none is free. Returns a PhoneSession. |
get(session_id) | One session. |
list(*, limit=50) | Your organization’s phone sessions, newest first. |
stop(phone_id) | End the session on that phone and release it. |
PhoneSession has id, phone_id, status, control_url, connect(),
refresh() and stop().
Phone.connect()
With control_url, open that session’s control connection and handshake. With
no arguments, connect to the sandbox’s phone over its local socket, lazily: the
socket opens on the first call.
| Parameter | Type | Default | Description |
|---|---|---|---|
control_url | str | None | None | The session’s control URL, from client.phones.create(). |
socket_path | str | None | the sandbox’s socket | Path of the sandbox’s local socket, when connecting inside a sandbox. Read from SANDBOX_SDK_SOCKET_PATH when omitted; the sandbox sets it for you. |
timeout | float | 60.0 | Seconds to wait for a reply when a call names no timeout. |
default_ocr_engine | str | None | "free" | OCR tier for every locator and observe() that doesn’t set its own: "free" or "premium". |
default_model | str | None | the server default | Model for the vision resolver and natural-language queries. |
default_strategy | "auto" | "vision" | "accessibility" | None | the server default ("auto") | Strategy for every locator that doesn’t set its own. See Strategies. |
strategy, model and ocr_engine always win over these.
Returns Phone.
Raises NotConnectedError when the connection can’t be opened: at once
with control_url, or on first use inside a sandbox.
MobileDriver is another name for Phone, kept for older code:
from halyard import MobileDriver.
Phone()
Wrap any transport. Phone.connect() is this with a SandboxTransport.
| Parameter | Type | Default | Description |
|---|---|---|---|
transport | Transport | required | What carries the calls. |
accessibility_at_allocation | bool | None | None | Whether the tree was on when the phone was allocated, when you know. Read back as phone.accessibility.enabled_at_allocation. |
Transports
Every phone call is one DCP round trip through a transport.| Class | What it is |
|---|---|
SandboxTransport(socket_path=None) | The sandbox’s local socket: DCP frames, one JSON object per line. Opens on the first call and reopens after a failure. close() is safe to repeat; the next call reconnects. |
Transport | The protocol any transport satisfies: call(method, params=None, *, timeout=None) and close(). The browser driver’s WebSocket transport satisfies it too. |
TimeoutError (kind
Timeout); a socket failure raises NotConnectedError. Either way the
connection closes and the next call reconnects.
phone.handshake()
Perform Protocol.handshake: the protocol version, what the phone is, and the
exact methods it serves. Gate optional behaviour on capabilities rather than
assuming the whole surface.
HandshakeResult:
protocol_version, device (a DeviceInfo),
domains and capabilities, plus supports(method) and has_domain(domain).
A phone advertises Protocol, Device, Touch, Keyboard, Screen and
Locator, and Accessibility only while it has an accessibility tree to serve.
Raises whatever the call fails with, UnsupportedError included.
phone.close()
Release the transport. The next call reconnects. Phone is also a context
manager: with Phone.connect() as phone: ... closes it on exit.