roboto.domain.sessions.session#

Module Contents#

class roboto.domain.sessions.session.Session(record, roboto_client=None)#

An operational time window of a Device.

A Session is a drone flight, a vehicle drive, a robot arm test run — some contiguous activity in the real world. It groups the recordings, logs, and other data produced during that window. Because a Session is bounded by the activity rather than by the recordings, it can span many files or cover just a slice of one. Files participate as contributions, each optionally narrowed to a sub-window of the file.

The Session’s aggregate bounds — min_timestamp_ns and max_timestamp_ns, in Unix-epoch nanoseconds — are recomputed by Roboto across all file contributions on every add or remove, and the returned instance reflects the updated bounds.

A Session can reference one or many devices: a single drone for a solo mission, or all of the drones in a formation flight. Use attach_to_device() and detach_from_device() to change which devices it references.

How to create a Session:

Session.create() accepts zero, one, or many devices.
create_session() is a shortcut for the common single-device case.
create_session() creates a Session for an existing Dataset, inferring the devices involved and pre-populating files from the Dataset.

Once created, include files with add_file() or add_files().

Examples

Create a Session for a drone flight, include a recording, and list its topics:

>>> from roboto.domain.sessions import Session
>>> session = Session.create(name="flight-2026-04-23-001", device_ids=["dv_abc"])
>>> session = session.add_file("fl_0123456789abcdef")
>>> for topic in session.list_topics():
...     print(topic.name)

Parameters:

record (roboto.domain.sessions.record.SessionRecord)
roboto_client (Optional[roboto.http.RobotoClient])

add_file(file, range_min_timestamp_ns=None, range_max_timestamp_ns=None)#

Include a single file in this Session as a contribution.

Thin convenience over add_files() for the common one-file case.

Parameters:

file (Union[roboto.domain.files.File, str]) – A File or a raw file id.
range_min_timestamp_ns (Optional[int]) – Optional lower bound (Unix-epoch nanoseconds) of this file’s contribution to the Session. Must be paired with range_max_timestamp_ns; leaving both None contributes the whole file’s time window.
range_max_timestamp_ns (Optional[int]) – Optional upper bound paired with range_min_timestamp_ns.

Returns:

This Session, with recomputed aggregate bounds (min_timestamp_ns / max_timestamp_ns).

Return type:

Session

Examples

Include a whole file:

>>> session.add_file("fl_0123456789abcdef")

Include only a sub-window of a file:

>>> session.add_file(
...     "fl_0123456789abcdef",
...     range_min_timestamp_ns=1_700_000_000_000_000_000,
...     range_max_timestamp_ns=1_700_000_060_000_000_000,
... )

add_files(files)#

Include the given files in this Session as contributions.

Each file may carry optional range_min_timestamp_ns / range_max_timestamp_ns bounds (Unix-epoch nanoseconds) narrowing its contribution to a sub-window of the file’s data. The service recomputes the Session’s aggregate bounds across all contributions, and the Session instance reflects the new min_timestamp_ns / max_timestamp_ns on return.

Parameters:: files (collections.abc.Sequence[roboto.domain.sessions.operations.SessionFile]) – Files to contribute to the Session.
Returns:: This Session, with recomputed aggregate bounds (min_timestamp_ns / max_timestamp_ns).
Return type:: Session

Examples

>>> from roboto.domain.sessions import SessionFile
>>> session.add_files(
...     [
...         SessionFile(file_id="fl_aaa"),
...         SessionFile(
...             file_id="fl_bbb",
...             range_min_timestamp_ns=1_700_000_000_000_000_000,
...             range_max_timestamp_ns=1_700_000_060_000_000_000,
...         ),
...     ]
... )

attach_to_device(device_id)#

Attach a Device to this Session as a subject.

A Session may have many device subjects — for example, a formation flight where multiple drones operate within a single activity window.

Parameters:: device_id (str) – ID of the Device to add as a subject of this Session.
Return type:: None

Examples

>>> session.attach_to_device("dv_wingman")
>>> list(session.list_devices())
['dv_lead', 'dv_wingman']

classmethod create(name=None, device_ids=(), caller_org_id=None, roboto_client=None)#

Create a new Session, optionally associating it with one or more devices.

Prefer create_session() for the common single-device case. To add devices to an existing Session later, see attach_to_device().

Parameters:

name (Optional[str]) – Optional short name for the Session (max 120 characters).
device_ids (collections.abc.Sequence[str]) – Devices to associate with the Session at creation. Empty (the default) creates a Session with no associated devices.
caller_org_id (Optional[str]) – Caller’s org scope. Required when the caller belongs to multiple orgs.
roboto_client (Optional[roboto.http.RobotoClient]) – Optional RobotoClient; defaults to the ambient one.

Returns:

The created Session.

Return type:

Session

Examples

>>> from roboto.domain.sessions import Session
>>> session = Session.create(name="flight-2026-04-23-001", device_ids=["dv_a", "dv_b"])

property created: datetime.datetime | None#

UTC timestamp when this Session was created.

Return type:: Optional[datetime.datetime]

property created_by: str#

Identifier of the user or service which created this Session.

Return type:: str

delete()#

Delete this Session. Its file contributions and device attachments are removed alongside it.

Return type:: None

detach_from_device(device_id)#

Remove a Device from this Session’s subjects.

Parameters:: device_id (str) – ID of the Device to remove as a subject of this Session.
Return type:: None

classmethod for_dataset(dataset_id, owner_org_id=None, roboto_client=None)#

Iterate Sessions whose composition includes any file in the given dataset.

Parameters:

dataset_id (str) – Dataset whose sessions to list.
owner_org_id (Optional[str]) – Org that owns the dataset. Required when the caller belongs to multiple orgs.
roboto_client (Optional[roboto.http.RobotoClient]) – Optional RobotoClient; defaults to the ambient one.

Yields:

Sessions, one at a time, following pagination automatically.

Return type:

collections.abc.Generator[Session, None, None]

Examples

>>> from roboto.domain.sessions import Session
>>> for session in Session.for_dataset("ds_abc"):
...     print(session.session_id, session.name)

classmethod for_org(org_id=None, roboto_client=None)#

Iterate all Sessions visible to the caller’s org.

Parameters:

org_id (Optional[str]) – Caller’s org scope. Required when the caller belongs to multiple orgs.
roboto_client (Optional[roboto.http.RobotoClient]) – Optional RobotoClient; defaults to the ambient one.

Yields:

Sessions, one at a time, following pagination automatically.

Return type:

collections.abc.Generator[Session, None, None]

classmethod from_id(session_id, owner_org_id=None, roboto_client=None)#

Load a Session by ID.

Parameters:

session_id (str) – Session primary key.
owner_org_id (Optional[str]) – Caller’s org scope. Required when the caller belongs to multiple orgs.
roboto_client (Optional[roboto.http.RobotoClient]) – Optional RobotoClient; defaults to the ambient one.

Returns:

The Session.

Return type:

Session

list_devices()#

Iterate the device IDs attached as subjects of this Session, paginated.

Return type:: collections.abc.Generator[str, None, None]

list_files()#

Iterate this Session’s file contributions, following pagination automatically.

Yields:: SessionFile entries, each carrying its optional range_min_timestamp_ns / range_max_timestamp_ns sub-window bounds.
Return type:: collections.abc.Generator[roboto.domain.sessions.operations.SessionFile, None, None]

list_topics()#

Iterate topic identities reachable from this Session, following pagination.

Results are range-filtered: a topic identity is yielded only when the Session’s time window overlaps at least one of the topic’s timeline extents (TimelineExtentRecord). Results are deduplicated across files and partitions, ordered by name with topic_id as a deterministic tiebreaker.

Yields:: roboto.domain.topics.TopicIdentityRecord entries.
Return type:: collections.abc.Generator[roboto.domain.topics.record.TopicIdentityRecord, None, None]

Examples

>>> for topic in session.list_topics():
...     print(topic.topic_id, topic.name)

property max_timestamp_ns: int | None#

Upper aggregate bound across this Session’s recording data contributions, in Unix-epoch nanoseconds.

None when the Session has no contributions.

Return type:: Optional[int]

property min_timestamp_ns: int | None#

Lower aggregate bound across this Session’s recording data contributions, in Unix-epoch nanoseconds.

None when the Session has no contributions.

Return type:: Optional[int]

property modified: datetime.datetime | None#

UTC timestamp when this Session was last modified.

Return type:: Optional[datetime.datetime]

property modified_by: str#

Identifier of the user or service which last modified this Session.

Return type:: str

property name: str | None#

Optional short name of this Session.

Return type:: Optional[str]

property org_id: str#

Identifier of the organization that owns this Session.

Return type:: str

property record: roboto.domain.sessions.record.SessionRecord#

Underlying data record for this Session.

Return type:: roboto.domain.sessions.record.SessionRecord

remove_file(file)#

Remove a single file’s contributions from this Session.

Thin convenience over remove_files() for the common one-file case.

Parameters:: file (Union[roboto.domain.files.File, str]) – A File or a raw file id.
Returns:: This Session, with recomputed aggregate bounds (min_timestamp_ns / max_timestamp_ns).
Return type:: Session

remove_files(file_ids)#

Remove the given files’ contributions from this Session.

The service recomputes the Session’s aggregate bounds across the remaining contributions, and the Session instance reflects the new min_timestamp_ns / max_timestamp_ns on return.

Parameters:: file_ids (collections.abc.Sequence[str]) – File IDs whose contributions should be removed.
Returns:: This Session, with recomputed aggregate bounds (min_timestamp_ns / max_timestamp_ns).
Return type:: Session

property session_id: str#

Globally unique identifier assigned to this Session on creation.

Return type:: str

update(name=NotSet)#

Update mutable Session fields.

Parameters:: name (Optional[Union[str, roboto.sentinels.NotSetType]]) – New name for the Session. Set to None to clear the name. Leave at the default to leave the name unchanged.
Returns:: This Session, refreshed from the server response.
Return type:: Session