Data & serialization

The wire records A11 moves — chunks, fragments, node references, and wire messages — and the registry that turns Python objects into chunks and back.

Chunk

a11.data.types.Chunk

Chunk(metadata: Any | None = None, ref: str = '', data: Any = b'')

A unit of node data with optional metadata and ref.

Create a chunk from optional metadata, a ref, and payload data.

approx_bytes property

approx_bytes: int

Approximate in-memory size of the chunk in bytes.

data property writable

data: bytes

Raw payload bytes of the chunk.

metadata property writable

metadata: Any

Optional metadata describing the chunk.

ref property writable

ref: str

Reference identifying the chunk's stored payload.

from_msgpack staticmethod

from_msgpack(data: Any) -> Chunk

Deserialize a value from MessagePack bytes.

model_construct classmethod

model_construct(**values: Any)

Construct a native value from trusted field values.

Native records retain C++ invariants. This validates input rather than creating an invalid object.

debug_string

debug_string() -> str

Return a human-readable debug string.

get_mimetype

get_mimetype() -> str

Return the chunk's MIME type, or empty if it has no metadata.

is_empty

is_empty() -> bool

Return whether the chunk has no payload data.

is_null

is_null() -> bool

Return whether the chunk is null (no metadata and no data).

to_msgpack

to_msgpack() -> bytes

Serialize the value to MessagePack bytes.

validate

validate() -> None

Raise if the value fails structural validation.

a11.data.types.ChunkMetadata

ChunkMetadata(mimetype: str, timestamp: Any | None = None, attributes: Any = {})

Metadata describing a chunk of node data.

Create chunk metadata from a MIME type, timestamp, and attributes.

approx_bytes property

approx_bytes: int

Approximate in-memory size of the metadata in bytes.

attributes property writable

attributes: _ByteMapView

Byte-string attribute map attached to the chunk.

mimetype property writable

mimetype: str

MIME type describing the chunk payload.

timestamp property writable

timestamp: Any

Optional timestamp associated with the chunk.

from_msgpack staticmethod

from_msgpack(data: Any) -> ChunkMetadata

Deserialize a value from MessagePack bytes.

model_construct classmethod

model_construct(**values: Any)

Construct a native value from trusted field values.

Native records retain C++ invariants. This validates input rather than creating an invalid object.

debug_string

debug_string() -> str

Return a human-readable debug string.

get_attribute

get_attribute(key: str) -> bytes

Return the attribute bytes for a key, raising if it is absent.

set_attribute

set_attribute(key: str, bytes: Any) -> None

Set the attribute bytes for a key.

to_msgpack

to_msgpack() -> bytes

Serialize the value to MessagePack bytes.

validate

validate() -> None

Raise if the value fails structural validation.

Fragments & references

a11.data.types.NodeFragment

NodeFragment(data: Any, id: str = '', seq: Any | None = None, continued: bool = False)

A fragment of a logical node carrying a Chunk or NodeRef.

Create a node fragment from Chunk/NodeRef data and framing fields.

approx_bytes property

approx_bytes: int

Approximate in-memory size of the fragment in bytes.

continued property writable

continued: bool

Whether more fragments follow for this node.

data property writable

data: Any

Payload of the fragment as either a Chunk or a NodeRef.

id property writable

id: str

Identifier of the logical node this fragment belongs to.

seq property writable

seq: int | None

Optional sequence number of the fragment.

from_msgpack staticmethod

from_msgpack(data: Any) -> NodeFragment

Deserialize a value from MessagePack bytes.

model_construct classmethod

model_construct(**values: Any)

Construct a native value from trusted field values.

Native records retain C++ invariants. This validates input rather than creating an invalid object.

debug_string

debug_string() -> str

Return a human-readable debug string.

get_chunk

get_chunk() -> Chunk

Return the fragment's Chunk, raising if it holds a NodeRef.

get_node_ref

get_node_ref() -> NodeRef

Return the fragment's NodeRef, raising if it holds a Chunk.

to_msgpack

to_msgpack() -> bytes

Serialize the value to MessagePack bytes.

validate

validate() -> None

Raise if the value fails structural validation.

a11.data.types.NodeRef

NodeRef(id: str, offset: Any = 0, length: Any | None = None)

Reference to a byte range of another logical node.

Create a node reference from an id, byte offset, and length.

approx_bytes property

approx_bytes: int

Approximate in-memory size of the ref in bytes.

id property writable

id: str

Identifier of the referenced node.

length property writable

length: int | None

Optional byte length of the referenced range.

offset property writable

offset: int

Byte offset into the referenced node.

from_msgpack staticmethod

from_msgpack(data: Any) -> NodeRef

Deserialize a value from MessagePack bytes.

model_construct classmethod

model_construct(**values: Any)

Construct a native value from trusted field values.

Native records retain C++ invariants. This validates input rather than creating an invalid object.

debug_string

debug_string() -> str

Return a human-readable debug string.

to_msgpack

to_msgpack() -> bytes

Serialize the value to MessagePack bytes.

validate

validate() -> None

Raise if the value fails structural validation.

Messages

a11.data.types.Port

Port(name: str = '', id: str = '')

A named input or output port of an action.

Create a port from a name and node id.

approx_bytes property

approx_bytes: int

Approximate in-memory size of the port in bytes.

id property writable

id: str

Identifier of the node bound to the port.

name property writable

name: str

Name of the port.

from_msgpack staticmethod

from_msgpack(data: Any) -> Port

Deserialize a value from MessagePack bytes.

model_construct classmethod

model_construct(**values: Any)

Construct a native value from trusted field values.

Native records retain C++ invariants. This validates input rather than creating an invalid object.

debug_string

debug_string() -> str

Return a human-readable debug string.

to_msgpack

to_msgpack() -> bytes

Serialize the value to MessagePack bytes.

validate

validate() -> None

Raise if the value fails structural validation.

a11.data.types.ActionMessage

ActionMessage(id: str = '', name: str = '', inputs: Any = [], outputs: Any = [], headers: Any = {})

A message invoking a named action with input and output ports.

Create an action message from id, name, ports, and headers.

approx_bytes property

approx_bytes: int

Approximate in-memory size of the message in bytes.

headers property writable

headers: _ByteMapView

Byte-string header map attached to the action.

id property writable

id: str

Identifier of the action invocation.

inputs property writable

inputs: _PortVectorView

Input ports of the action.

name property writable

name: str

Name of the action being invoked.

outputs property writable

outputs: _PortVectorView

Output ports of the action.

from_msgpack staticmethod

from_msgpack(data: Any) -> ActionMessage

Deserialize a value from MessagePack bytes.

model_construct classmethod

model_construct(**values: Any)

Construct a native value from trusted field values.

Native records retain C++ invariants. This validates input rather than creating an invalid object.

debug_string

debug_string() -> str

Return a human-readable debug string.

to_msgpack

to_msgpack() -> bytes

Serialize the value to MessagePack bytes.

validate

validate() -> None

Raise if the value fails structural validation.

a11.data.types.WireMessage

WireMessage(node_fragments: Any = [], actions: Any = [], headers: Any = {})

A wire-format message bundling node fragments and actions.

Create a wire message from node fragments, actions, and headers.

actions property writable

actions: _ActionMessageVectorView

Action messages carried by the message.

approx_bytes property

approx_bytes: int

Approximate in-memory size of the message in bytes.

headers property writable

headers: _ByteMapView

Byte-string header map attached to the message.

node_fragments property writable

node_fragments: _NodeFragmentVectorView

Node fragments carried by the message.

from_json staticmethod

from_json(value: str) -> WireMessage

Deserialize a message from its JSON wire encoding.

from_msgpack staticmethod

from_msgpack(data: Any) -> WireMessage

Deserialize a value from MessagePack bytes.

model_construct classmethod

model_construct(**values: Any)

Construct a native value from trusted field values.

Native records retain C++ invariants. This validates input rather than creating an invalid object.

debug_string

debug_string() -> str

Return a human-readable debug string.

to_json

to_json() -> str

Serialize the message to its JSON wire encoding.

to_msgpack

to_msgpack() -> bytes

Serialize the value to MessagePack bytes.

validate

validate() -> None

Raise if the value fails structural validation.

Serialization

a11.data.serialization.SerializationRegistry

SerializationRegistry(*, register_defaults: bool = False)

A registry of serializers and deserializers indexed by type and MIME.

New registries are empty. Pass register_defaults=True or call register_defaults to install the built-in JSON and MessagePack codecs. The process-wide registry returned by get_global_serialization_registry already contains them.

set_type_tag

set_type_tag(obj_type: type, tag: str) -> None

Pin the wire tag used to identify obj_type in serialized data.

Overrides the default fully-qualified name. Use this to keep a short, stable tag for a type (for example to preserve an existing wire format) or to give two like-named types deterministic, distinct identifiers.

register_serializer

register_serializer(obj_type: type, mimetype: str, serializer: SerializerFn) -> None

Register serializer(obj) for a type and exact media type.

register_deserializer

register_deserializer(obj_type: type, mimetype: str, deserializer: DeserializerFn, *, receives_chunk: bool | None = None) -> None

Register a data deserializer for a type and exact media type.

A deserializer may accept either data or data, obj_type. A callback whose first argument is named chunk (or is annotated as a Chunk) receives the complete chunk instead of chunk.data. receives_chunk can be used to select that behavior explicitly.

register

register(obj_type: type, mimetype: str, serializer: SerializerFn, deserializer: DeserializerFn, *, receives_chunk: bool | None = None) -> None

Atomically register a serializer/deserializer pair.

register_defaults

register_defaults() -> None

Install the standard JSON and MessagePack registrations.

to_chunk

to_chunk(obj: Any, mimetype: str = '') -> Chunk

Serialize obj into a chunk.

If mimetype is empty, the closest registered Python type wins and registration order chooses its preferred representation. An explicit MIME value can be exact or contain * wildcards. Returned chunks always have an exact MIME type and a stable Python type identifier.

from_chunk

from_chunk(chunk: Chunk, mimetype_patterns: str | Sequence[str] = '', obj_type: type | None = None) -> Any

Deserialize chunk using the first matching MIME selector.

Selectors are matched in order against the chunk's MIME type and may contain wildcards. If the chunk has no MIME metadata, a supplied exact selector acts as the representation. A requested obj_type uses an exact registration first and then registrations for its superclasses.