A phone Locator describes a target and sends nothing until you act on it or query it. Each call resolves it against whatever is on screen at that moment, waits until it is actionable, and acts, all on the phone in one round trip.
row = phone.get_by_text("Battery").within(phone.get_by_role("list"))
result = row.tap()
print(result.resolved_by, result.bounds)
Build one from phone.locator(), get_by_text() or get_by_role(). Refining it returns a new locator; a locator never changes.
Timeouts are in milliseconds, as in the browser driver: 5,000 by default, at most 60,000. A value outside that range raises ValueError. Running out raises TimeoutError (kind ActionTimeout).

Strategies

strategy, model and ocr_engine are set when the locator is built, and fall back to the driver’s defaults. Actions and queries take only timeout.
StrategyHow it resolves
"auto"The default. Uses the accessibility tree when the phone has one, and vision otherwise.
"accessibility"The tree only. Raises UnsupportedError on a phone without one.
"vision"The screen only: OCR for text, a model for query. Skips the tree.
role, name, states and node_id always need the tree and raise UnsupportedError without one; they are never turned into a model prompt. query is the only selector a model reads. Strategy is the type Literal["auto", "vision", "accessibility"], importable from halyard.phone.

Refining

locator.nth() and locator.first()

The nth match in reading order, zero-based; first() is nth(0).
locator.nth(n)
locator.first()

locator.within()

Keep a match that is inside other. Calling it again scopes the new ancestor inside the earlier one.
locator.within(other)
Only other’s selector fields become the scope: the outer locator’s strategy, model and OCR engine govern the whole call. Raises ValueError when other sets any of them.

locator.has()

Keep a match that contains other. Same rules as within().
locator.has(other)

locator.filter()

Add a natural-language query on top of the locator’s fields. A second filter adds to the first query rather than replacing it.
phone.get_by_role("button").filter(query="the blue one at the bottom")
locator.filter(*, query)
Returns Locator from each of these.

Actions

Each resolves the locator, waits until the target is actionable, then acts.

locator.tap()

Tap the target’s centre.
locator.tap(*, timeout=None)
Returns LocatorResult.

locator.fill()

Resolve and wait as tap() does, focus the target, then type text.
locator.fill(text, *, timeout=None)
Returns LocatorResult.

locator.press()

Focus the target, then press a named key. See Key.
locator.press(key, *, timeout=None)
Returns LocatorResult.

locator.wait_for()

Block on the phone until the locator reaches state.
locator.wait_for(*, state="visible", timeout=None)
ParameterTypeDefaultDescription
stateWaitState"visible""visible", "hidden" or "enabled". "enabled" reads the accessibility tree.
timeoutfloat | None5000Milliseconds.
Returns LocatorResult, or None for state="hidden". WaitState is the type Literal["visible", "hidden", "enabled"].

Queries

locator.bounding_box()

Wait until the locator resolves, then report where the target is.
locator.bounding_box(*, timeout=None)
Returns LocatorResult; the box is its bounds.

locator.accessible_name() and locator.text()

Wait until the locator resolves through the accessibility tree, then return the target’s accessible name. text() is the same call.
locator.accessible_name(*, timeout=None)
locator.text(*, timeout=None)
Returns str. Needs the tree.

locator.count()

How many targets match the current screen, zero included. Never waits; timeout only bounds the call itself.
locator.count(*, timeout=None)
Returns int.

locator.selector

The DCP selector this locator sends. See Selectors. Returns dict.

LocatorResult

What every action and query returns. A frozen dataclass.
FieldTypeDescription
resolved_by"a11y" | "ocr" | "vlm" | NoneHow the target was found: the accessibility tree, OCR, or a vision model. None when nothing was resolved.
boundsBBox | NoneWhere the target was when the phone acted, in screen pixels.
took_msintTime on the phone, waiting included.
model_namestr | NoneThe model that resolved the target, set only when resolved_by is "vlm".
inputstr | NoneThe input backend that carried the action, when reported.