roboto.uri

The roboto:// URI scheme, a host-independent reference to one platform entity.

roboto://<type>/<id> names an entity without naming a web address. Platform event payloads, AI chat answers, and notifications all identify entities this way; opening one in the Roboto web app lands on that entity’s page. A URI may carry a ?t= epoch nanosecond timestamp, which asks a time-aware page to open at that instant, and a ?v= version, which names one version of a versioned entity such as a file.

Module Contents

roboto.uri.ROBOTO_URI_IN_TEXT_PATTERN

Finds where a roboto:// URI starts and ends inside prose, for callers rewriting URIs into links. Deliberately looser than RobotoUri.parse(): it matches text this module refuses to parse, because a finder that skipped a malformed URI would leave it in the rendered output as raw text.

roboto.uri.ROBOTO_URI_SCHEME = 'roboto'

class roboto.uri.RobotoUri

A parsed roboto://<type>/<id> reference, optionally carrying a timestamp and a version.

str() renders it back to URI text in normalized form: the type is lowercased, empty path segments are dropped, and only the t and v query parameters survive, in that order, so str(RobotoUri.parse(text)) equals text only when text is already normalized.

Raises:

ValueError – id is empty, timestamp_ns is negative, or version is below 1.

id: str

classmethod parse(text)

Read roboto://<type>/<id>, with optional t=<epoch_ns> and v=<version> parameters, into its parts.

Query parameters other than t and v are ignored and the entity type is matched case-insensitively, so a URI written by any Roboto surface parses here.

Parameters:

text (str) – The URI to read. Anything else raises rather than returning None, so a caller sifting arbitrary prose should locate candidates with ROBOTO_URI_IN_TEXT_PATTERN first.

Raises:

ValueError – text is not a roboto:// URI, names a type outside RobotoUriType, carries no entity id or more than one path segment, carries a t that is not a whole number of nanoseconds, or carries a v that is not a whole number.

Return type:

RobotoUri

timestamp_ns: int | None = None

The instant this URI points at, in nanoseconds since the Unix epoch, written as the URI’s ?t= parameter. None when the URI names an entity and no instant. Only pages showing data over time act on it; the rest ignore it.

type: RobotoUriType

version: int | None = None

The version of the entity this URI points at, written as the URI’s ?v= parameter. None when the URI names the entity without pinning a version. A file link carries one, so it keeps resolving to the version it was made against.

class roboto.uri.RobotoUriType

Bases: roboto.compat.StrEnum

The entity kinds a roboto:// URI may name.

A roboto:// URI whose type is absent from this enum names no entity. The web app relies on that to reserve type names for links addressing its own controls rather than an entity, so an unrecognized type is ordinary input, not corruption.

Collection = 'collection'

Dataset = 'dataset'

Device = 'device'

Event = 'event'

File = 'file'

Invocation = 'invocation'

Layout = 'layout'

MessagePath = 'msgpath'

Org = 'org'

Session = 'session'

Topic = 'topic'

Trigger = 'trigger'

Workspace = 'workspace'

roboto.uri.TIMESTAMP_QUERY_PARAM = 't'

Query parameter naming the instant a URI points at, in epoch nanoseconds.

roboto.uri.VERSION_QUERY_PARAM = 'v'

Query parameter naming one version of the entity a URI points at.