tractor/docs/api/msg.rst

Typed messaging: tractor.msg

All inter-actor communication rides a small, strictly-typed msgpack wire protocol built from msgspec.Struct types — the "SC-shuttle" protocol that powers contexts, streams, RPC and cancellation. You normally never touch these msg types directly (the ~tractor.Context API speaks them for you) but you do use this subpackage to define payload type contracts: per endpoint via @tractor.context(pld_spec=...) or per channel via custom codecs.

Violations of an active msg-spec surface as ~tractor.MsgTypeError (see /api/errors); the full typed-payload workflow is shown in examples/typed_payloads.py.

tractor.msg

The protocol message set

PayloadMsg Aid SpawnSpec Start StartAck Started Yield Stop Return CancelAck Error

Aid (identity handshake) and SpawnSpec (parent -> child init) run at connection setup; Start/StartAck initiate an RPC task; Started/Yield/Stop/Return are the ~tractor.Context dialog phases; CancelAck and Error close the loop on cancellation and (boxed) failure. Msg is a legacy alias of PayloadMsg. The union of all of the above is exported as MsgType (also __msg_spec__).

tractor.msg.types

tractor.msg

Codec construction and override

mk_codec

MsgCodec

mk_dec

MsgDec

apply_codec

current_codec

Note

apply_codec swaps the codec via a contextvars.ContextVar — the override only applies to the current task (and tasks it starts), not sibling tasks already running in the actor. Payload-decoding is layered: the outer codec leaves .pld fields as msgspec.Raw and each context's payload-receiver decodes them against its spec (the "cheap-or-nasty" validation pattern).

Namespace pointers

NamespacePath

The 'module.path:obj_name' str-subtype used to address every RPC target function over the wire (same format as pkgutil.resolve_name).

Pretty structs

Struct

A msgspec.Struct subtype with a multi-line pretty __repr__ — handy as a base for your own IPC payload types so crash logs stay readable.

/api/context for where pld_spec typing plugs into the @context decorator, /api/errors for ~tractor.MsgTypeError semantics, and /guide/msging for the guided typed-messaging tour.