# Snapshots and the event log

Screen snapshots with refs and the connection's event log, for tools that drive a device over
several processes. Guide: [Held connections and screen snapshots](../../sdk/python.md#held-connections-and-screen-snapshots).

## <kbd>class</kbd> `ScreenSnapshot`
The visible screen as ref-addressed nodes (``Device.screen_snapshot()``). ``removed`` lists the previous snapshot's nodes that are gone; their refs no longer resolve. ``snapshot_id`` increases per attached device. 

### <kbd>method</kbd> `ScreenSnapshot.__init__`

```python
__init__(
    snapshot_id: 'int',
    nodes: 'tuple[ScreenNode, ...]',
    removed: 'tuple[ScreenNode, ...]',
    rotation: 'int'
) → None
```

---

### <kbd>method</kbd> `ScreenSnapshot.node`

```python
node(ref: 'str') → ScreenNode | None
```

The node with ``ref`` (with or without the leading ``@``), or None. 

## <kbd>class</kbd> `ScreenNode`
One visible node of a ``ScreenSnapshot``, in dump (pre-order) order. 

``ref`` (``e<N>``) stays the same across snapshots while the node is unchanged and is never reused for another node. ``selector`` is one the daemon found to match only this node in the dump (None when there is none); ``by_index`` marks one that ends in an index pick, which is right for this dump but fragile if the screen reorders. ``window_package`` is the package of the window the node is in. ``interactive``: clickable, long-clickable, checkable, scrollable or editable. 

### <kbd>method</kbd> `ScreenNode.__init__`

```python
__init__(
    ref: 'str',
    depth: 'int',
    window_package: 'str',
    class_name: 'str | None',
    resource_name: 'str | None',
    text: 'str | None',
    content_description: 'str | None',
    hint: 'str | None',
    bounds: 'Bounds',
    flags: 'frozenset[NodeFlag]',
    password: 'bool',
    interactive: 'bool',
    selector: 'Selector | None',
    by_index: 'bool',
    change: 'NodeChange',
    candidates: 'tuple[SelectorCandidate, ...]' = (),
    showing_hint: 'bool' = False,
    content_invalid: 'bool' = False,
    error: 'str | None' = None
) → None
```

## <kbd>class</kbd> `NodeChange`
A ``ScreenNode`` against the previous snapshot of the same attached device. ``NONE``: there was no previous snapshot. 

## <kbd>class</kbd> `NodeFlag`
A boolean property of a node; ``ScreenNode.flags`` holds the ones that are true. 

## <kbd>class</kbd> `SelectorCandidate`
One selector that matched only its ``ScreenNode`` in the dump, and how it does so. 

### <kbd>method</kbd> `SelectorCandidate.__init__`

```python
__init__(selector: 'Selector', kind: 'SelectorKind') → None
```

## <kbd>class</kbd> `SelectorKind`
How a ``SelectorCandidate`` singles out its node. ``PLAIN``: one property (resource id, text, description or hint); ``COMBINED``: two of the node's own properties; ``ANCESTOR``: a property plus an ancestor it sits under; ``BY_INDEX``: an index pick, right for this dump but fragile if the screen reorders. ``UNKNOWN``: a kind this client does not know. 

## <kbd>class</kbd> `EventLog`
``TapConnection.event_log()``: the kept events, oldest first, and how many older ones the server evicted (it keeps each connection's last 2000). 

### <kbd>method</kbd> `EventLog.__init__`

```python
__init__(events: 'tuple[LoggedEvent, ...]', dropped: 'int') → None
```

## <kbd>class</kbd> `LoggedEvent`
One device call from a connection's event log (``TapConnection.event_log()``). 

The call and its outcome are the server API's own messages in proto3 JSON form with the ``.proto`` field names, so any language's protobuf library can parse them: ``command`` is a ``tap.v1.Command`` (for Execute) and ``app`` a ``tap.v1.AppCall`` (for an app lifecycle call); exactly one is set. ``error`` is the ``tap.v1.Error`` the driver returned and ``failure`` the ``tap.v1.Failure`` of a call that failed as an RPC; both are None when the call succeeded. ``at`` is when the call started (Unix seconds); ``duration`` is in seconds. 

### <kbd>method</kbd> `LoggedEvent.__init__`

```python
__init__(
    seq: 'int',
    at: 'float',
    duration: 'float',
    serial: 'str',
    command: 'dict | None',
    app: 'dict | None',
    error: 'dict | None',
    failure: 'dict | None'
) → None
```

---

#### <kbd>property</kbd> LoggedEvent.ok

---

### <kbd>method</kbd> `LoggedEvent.to_dict`

```python
to_dict() → dict
```

A JSON-ready dict: the fields above with ``at`` as an ISO 8601 UTC timestamp and ``duration_ms``; None fields are left out.