Frame models

The wire format of AT Protocol XRPC subscriptions: each frame is two concatenated DAG-CBOR items, a header and a body. Frame.from_bytes decodes one into a MessageFrame or an ErrorFrame, depending on the op field of its header.

A message frame carries header.t, its type such as #commit, and an undecoded body. That type is what the per-lexicon parsers (parse_subscribe_repos_message and friends) dispatch on, and what you filter on to avoid parsing messages you do not want.

Note

These are re-exported as atproto.firehose_models, which is the import you will see in the examples and in most existing code.

Wire format of AT Protocol XRPC subscriptions: DAG-CBOR framed messages.

class atproto_subscription.frames.ErrorFrame(header: ErrorFrameHeader, body: ErrorFrameBody)

Bases: Frame

Subscription error frame.

header: ErrorFrameHeader

Header.

body: ErrorFrameBody

Body.

class atproto_subscription.frames.ErrorFrameBody(error: str, message: str | None = None)

Bases: object

Body of error frame.

error: str

Code of the error.

message: str | None = None

Description of the error.

class atproto_subscription.frames.ErrorFrameHeader(op: FrameType = FrameType.ERROR)

Bases: object

Header of the error frame.

op: FrameType = -1

Operation. For Error header is FrameType.ERROR always.

class atproto_subscription.frames.Frame(header: MessageFrameHeader | ErrorFrameHeader, body: ErrorFrameBody | dict)

Bases: object

Base subscription frame.

header: MessageFrameHeader | ErrorFrameHeader

Header.

body: ErrorFrameBody | dict

Body

property operation: FrameType

FrameType: Frame operation (frame type).

property is_message: bool

bool: Is frame the MessageFrame.

property is_error: bool

bool: Is frame the ErrorFrame.

static from_bytes(data: bytes | bytearray) → MessageFrame | ErrorFrame

Decode frame from bytes of stream of bytes.

Parameters:

data – Bytes or stream of bytes of frame.

Returns:

MessageFrame or ErrorFrame

Raises:

atproto.exceptions.SubscriptionError – Invalid data frame.

atproto_subscription.frames.FrameHeader

Base frame header.

alias of MessageFrameHeader | ErrorFrameHeader

class atproto_subscription.frames.FrameType(*values)

Bases: Enum

Type of frame.

MESSAGE = 1

ERROR = -1

classmethod has_value(value: int) → bool

class atproto_subscription.frames.MessageFrame(header: MessageFrameHeader, body: dict)

Bases: Frame

Subscription message frame.

header: MessageFrameHeader

Header.

body: dict

Body.

property type: str

str: Type of body.

class atproto_subscription.frames.MessageFrameHeader(op: FrameType = FrameType.MESSAGE, t: str | None = None)

Bases: object

Header of the message frame.

op: FrameType = 1

Operation. For Message header is FrameType.MESSAGE always.

t: str | None = None

Type of body content.

atproto_subscription.frames.parse_frame(header: MessageFrameHeader | ErrorFrameHeader, raw_body: dict) → ErrorFrame | MessageFrame

atproto_subscription.frames.parse_frame_header(raw_header: dict) → MessageFrameHeader | ErrorFrameHeader