client.phones.create() starts a session on one of your organization’s phones. Its connect() returns a Phone.
import halyard

client = halyard.Client()
session = client.phones.create()
try:
    phone = session.connect()
    print(phone.handshake().device.model)
finally:
    session.stop()

client.phones

MethodDoes
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.
A 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.
Phone.connect(control_url=None, *, socket_path=None, timeout=60.0,
              default_ocr_engine=None, default_model=None, default_strategy=None)
ParameterTypeDefaultDescription
control_urlstr | NoneNoneThe session’s control URL, from client.phones.create().
socket_pathstr | Nonethe sandbox’s socketPath 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.
timeoutfloat60.0Seconds to wait for a reply when a call names no timeout.
default_ocr_enginestr | None"free"OCR tier for every locator and observe() that doesn’t set its own: "free" or "premium".
default_modelstr | Nonethe server defaultModel for the vision resolver and natural-language queries.
default_strategy"auto" | "vision" | "accessibility" | Nonethe server default ("auto")Strategy for every locator that doesn’t set its own. See Strategies.
A locator’s own 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.
Phone(transport, *, default_ocr_engine=None, default_model=None, default_strategy=None,
      accessibility_at_allocation=None)
ParameterTypeDefaultDescription
transportTransportrequiredWhat carries the calls.
accessibility_at_allocationbool | NoneNoneWhether 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.
ClassWhat 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.
TransportThe protocol any transport satisfies: call(method, params=None, *, timeout=None) and close(). The browser driver’s WebSocket transport satisfies it too.
from halyard.phone import SandboxTransport

phone = Phone(SandboxTransport("/path/to/socket"))
A call that gets no reply within its timeout raises 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.
hello = phone.handshake()
if hello.has_domain("Accessibility"):
    phone.accessibility.enable()
Returns 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.