Serialization¶

`casty.TypeRegistry` ¶

Bidirectional mapping between fully-qualified type names and Python classes.

Supports both explicit registration and auto-resolution via importlib.

Examples:

>>> from dataclasses import dataclass
>>> @dataclass(frozen=True)
... class Ping:
...     value: int
>>> registry = TypeRegistry()
>>> registry.register(Ping)
>>> registry.resolve(registry.type_name(Ping)) is Ping
True

`init()` ¶

`register(cls)` ¶

Register a type for serialization.

Parameters:

Name	Type	Description	Default
`cls`	`type`	The class to register.	required

`register_all(*types)` ¶

Register multiple types at once.

Parameters:

Name	Type	Description	Default
`*types`	`type`	Classes to register.	`()`

Examples:

>>> registry = TypeRegistry()
>>> registry.register_all(int, str)
>>> registry.is_registered(int)
True

`resolve(name)` ¶

Resolve a fully-qualified type name to a Python class.

Falls back to auto-resolution via importlib if the name is not explicitly registered.

Parameters:

Name	Type	Description	Default
`name`	`str`	Fully-qualified type name (e.g. `mymod.MyClass`).	required

Returns:

Type	Description
`type`

Raises:

Type	Description
`KeyError`	If the type cannot be resolved.

`type_name(cls)` ¶

Return the fully-qualified name for a type, registering it if needed.

Parameters:

Name	Type	Description	Default
`cls`	`type`	The class to look up.	required

Returns:

Type	Description
`str`	Fully-qualified name (e.g. `mymod.MyClass`).

`is_registered(cls)` ¶

Return True if the type is already registered.

Parameters:

Name	Type	Description	Default
`cls`	`type`	The class to check.	required

Returns:

Type	Description
`bool`

Examples:

>>> registry = TypeRegistry()
>>> registry.is_registered(int)
False
>>> registry.register(int)
>>> registry.is_registered(int)
True

`casty.JsonSerializer` ¶

JSON-based serializer with recursive handling of Casty types.

Handles ActorRef, frozenset, Enum, dict, tuple, and frozen dataclasses registered in the TypeRegistry.

Parameters:

Name	Type	Description	Default
`registry`	`TypeRegistry`	Registry for resolving type names.	required

Examples:

>>> registry = TypeRegistry()
>>> ser = JsonSerializer(registry)
>>> ser.deserialize(ser.serialize({"key": "value"}))
{'key': 'value'}

`registry` `property` ¶

Return the underlying type registry.

`init(registry)` ¶

`serialize(obj)` ¶

Serialize an object to JSON bytes.

Parameters:

Name	Type	Description	Default
`obj`	`M`	Object to serialize.	required

Returns:

Type	Description
`bytes`	UTF-8 encoded JSON.

`deserialize(data, *, ref_factory=None)` ¶

Deserialize JSON bytes back to a Python object.

Parameters:

Name	Type	Description	Default
`data`	`bytes`	UTF-8 encoded JSON from `serialize`.	required
`ref_factory`	`Callable or None`	Factory for reconstructing `ActorRef` instances from addresses.	`None`

Returns:

Type	Description
`Any`

`to_dict(value)` ¶

`from_dict(value, *, ref_factory=None)` ¶

`casty.PickleSerializer` ¶

Pickle-based serializer using protocol 5.

Faster than JSON but not human-readable. Suitable for trusted environments where all nodes run the same code.

Examples:

>>> ser = PickleSerializer()
>>> ser.deserialize(ser.serialize({"key": "value"}))
{'key': 'value'}

`serialize(obj)` ¶

Serialize an object to pickle bytes (protocol 5).

Parameters:

Name	Type	Description	Default
`obj`	`M`	Object to serialize.	required

Returns:

Type	Description
`bytes`

`deserialize(data, *, ref_factory=None)` ¶

Deserialize pickle bytes back to a Python object.

Temporarily installs ref_factory as the module-level restore hook for the duration of pickle.loads(), then restores the previous value.

Parameters:

Name	Type	Description	Default
`data`	`bytes`	Bytes produced by `serialize`.	required
`ref_factory`	`Callable or None`	Factory for reconstructing `ActorRef` instances from addresses.	`None`

Returns:

Type	Description
`Any`

`casty.CompressedSerializer` ¶

Composable wrapper that adds compression to any Serializer.

Applies compression on serialize() and decompression on deserialize(), delegating the actual serialization to the wrapped inner serializer.

Parameters:

Name	Type	Description	Default
`inner`	`Serializer`	The underlying serializer to wrap.	required
`config`	`CompressionConfig`	Compression algorithm and level settings.	required

Examples:

>>> from casty.config import CompressionConfig
>>> ser = CompressedSerializer(PickleSerializer(), CompressionConfig(level=9))
>>> ser.deserialize(ser.serialize({"key": "value"}))
{'key': 'value'}

`init(inner, config)` ¶

`serialize(obj)` ¶

Serialize and compress an object to bytes.

Parameters:

Name	Type	Description	Default
`obj`	`M`	Object to serialize.	required

Returns:

Type	Description
`bytes`	Compressed serialized bytes.

`deserialize(data, *, ref_factory=None)` ¶

Decompress and deserialize bytes back to an object.

Parameters:

Name	Type	Description	Default
`data`	`bytes`	Compressed bytes from `serialize`.	required
`ref_factory`	`Callable or None`	Factory for reconstructing `ActorRef` instances.	`None`

Returns:

Type	Description
`Any`

`casty.Serializer` ¶

Bases: Protocol

Protocol for message serialization and deserialization.

Implementations must handle ActorRef round-tripping via the ref_factory keyword argument passed to deserialize().

Examples:

Minimal implementation:

>>> class MySerializer:
...     def serialize(self, obj: object) -> bytes: ...
...     def deserialize(self, data: bytes, *, ref_factory=None) -> object: ...

`serialize(obj)` ¶

Serialize an object to bytes.

`deserialize(data, *, ref_factory=None)` ¶

Deserialize bytes back to an object.

`casty.build_serializer(config, *, registry=None)` ¶

Build a Serializer chain from configuration.

Parameters:

Name	Type	Description	Default
`config`	`SerializationConfig`	Serialization settings (serializer kind + optional compression).	required
`registry`	`TypeRegistry \| None`	Type registry required when `config.serializer == "json"`.	`None`

Returns:

Type	Description
`PickleSerializer \| JsonSerializer \| CompressedSerializer`	Ready-to-use serializer, possibly wrapped with compression.

Examples:

>>> from casty.config import SerializationConfig, CompressionConfig
>>> config = SerializationConfig(compression=CompressionConfig(level=9))
>>> ser = build_serializer(config)

`casty.MsgpackSerializer` ¶

MessagePack serializer with structured type handling.

Reuses the same recursive dict-conversion as JsonSerializer but encodes to MessagePack binary format, giving compact output with fast encode/decode.

Requires the optional msgpack package.

Parameters:

Name	Type	Description	Default
`registry`	`TypeRegistry`	Registry for resolving type names.	`None`

Examples:

>>> registry = TypeRegistry()
>>> ser = MsgpackSerializer(registry)
>>> ser.deserialize(ser.serialize({"key": "value"}))
{'key': 'value'}

`registry` `property` ¶

Return the underlying type registry.

`init(registry=None)` ¶

`serialize(obj)` ¶

Serialize an object to MessagePack bytes.

Parameters:

Name	Type	Description	Default
`obj`	`M`	Object to serialize.	required

Returns:

Type	Description
`bytes`

`deserialize(data, *, ref_factory=None)` ¶

Deserialize MessagePack bytes back to a Python object.

Parameters:

Name	Type	Description	Default
`data`	`bytes`	Bytes from `serialize`.	required
`ref_factory`	`Callable or None`	Factory for reconstructing `ActorRef` instances from addresses.	`None`

Returns:

Type	Description
`Any`

`casty.CloudPickleSerializer` ¶

CloudPickle-based serializer for lambdas and closures.

Drop-in replacement for PickleSerializer that handles lambdas, closures, and dynamically defined classes via cloudpickle. Deserialization uses standard pickle.loads.

Requires the optional cloudpickle package.

Examples:

>>> ser = CloudPickleSerializer()
>>> ser.deserialize(ser.serialize({"key": "value"}))
{'key': 'value'}

`serialize(obj)` ¶

Serialize an object using cloudpickle (protocol 5).

Parameters:

Name	Type	Description	Default
`obj`	`M`	Object to serialize.	required

Returns:

Type	Description
`bytes`

`deserialize(data, *, ref_factory=None)` ¶

Deserialize bytes back to a Python object.

Uses standard pickle.loads since cloudpickle only customizes the dump side.

Parameters:

Name	Type	Description	Default
`data`	`bytes`	Bytes from `serialize`.	required
`ref_factory`	`Callable or None`	Factory for reconstructing `ActorRef` instances from addresses.	`None`

Returns:

Type	Description
`Any`

`casty.Lz4CompressedSerializer` ¶

Wraps any serializer with LZ4 frame compression.

Applies LZ4 compression on serialize() and decompression on deserialize(), delegating actual serialization to the wrapped inner serializer.

Requires the optional lz4 package.

Parameters:

Name	Type	Description	Default
`inner`	`Serializer`	The underlying serializer to wrap.	required
`level`	`int`	LZ4 compression level (0 = default, higher = more compression).	`0`

Examples:

>>> from casty.remote.serialization import PickleSerializer
>>> ser = Lz4CompressedSerializer(PickleSerializer())
>>> ser.deserialize(ser.serialize({"key": "value"}))
{'key': 'value'}

`init(inner, *, level=0)` ¶

`serialize(obj)` ¶

Serialize and compress an object to bytes.

Parameters:

Name	Type	Description	Default
`obj`	`M`	Object to serialize.	required

Returns:

Type	Description
`bytes`	LZ4-compressed serialized bytes.

`deserialize(data, *, ref_factory=None)` ¶

Decompress and deserialize bytes back to an object.

Parameters:

Name	Type	Description	Default
`data`	`bytes`	LZ4-compressed bytes from `serialize`.	required
`ref_factory`	`Callable or None`	Factory for reconstructing `ActorRef` instances.	`None`

Returns:

Type	Description
`Any`

Serialization¶

casty.TypeRegistry ¶

__init__() ¶

register(cls) ¶

register_all(*types) ¶

resolve(name) ¶

type_name(cls) ¶

is_registered(cls) ¶

casty.JsonSerializer ¶

registry property ¶

__init__(registry) ¶

serialize(obj) ¶

deserialize(data, *, ref_factory=None) ¶

to_dict(value) ¶

from_dict(value, *, ref_factory=None) ¶

casty.PickleSerializer ¶

serialize(obj) ¶

deserialize(data, *, ref_factory=None) ¶

casty.CompressedSerializer ¶

__init__(inner, config) ¶

serialize(obj) ¶

deserialize(data, *, ref_factory=None) ¶

casty.Serializer ¶

serialize(obj) ¶

deserialize(data, *, ref_factory=None) ¶

casty.build_serializer(config, *, registry=None) ¶

casty.MsgpackSerializer ¶

registry property ¶

__init__(registry=None) ¶

serialize(obj) ¶

deserialize(data, *, ref_factory=None) ¶

casty.CloudPickleSerializer ¶

serialize(obj) ¶

deserialize(data, *, ref_factory=None) ¶

casty.Lz4CompressedSerializer ¶

__init__(inner, *, level=0) ¶

serialize(obj) ¶

deserialize(data, *, ref_factory=None) ¶

`casty.TypeRegistry` ¶

`init()` ¶

`register(cls)` ¶

`register_all(*types)` ¶

`resolve(name)` ¶

`type_name(cls)` ¶

`is_registered(cls)` ¶

`casty.JsonSerializer` ¶

`registry` `property` ¶

`init(registry)` ¶

`serialize(obj)` ¶

`deserialize(data, *, ref_factory=None)` ¶

`to_dict(value)` ¶

`from_dict(value, *, ref_factory=None)` ¶

`casty.PickleSerializer` ¶

`serialize(obj)` ¶

`deserialize(data, *, ref_factory=None)` ¶

`casty.CompressedSerializer` ¶

`init(inner, config)` ¶

`serialize(obj)` ¶

`deserialize(data, *, ref_factory=None)` ¶

`casty.Serializer` ¶

`serialize(obj)` ¶

`deserialize(data, *, ref_factory=None)` ¶

`casty.build_serializer(config, *, registry=None)` ¶

`casty.MsgpackSerializer` ¶

`registry` `property` ¶

`init(registry=None)` ¶

`serialize(obj)` ¶

`deserialize(data, *, ref_factory=None)` ¶

`casty.CloudPickleSerializer` ¶

`serialize(obj)` ¶

`deserialize(data, *, ref_factory=None)` ¶

`casty.Lz4CompressedSerializer` ¶

`init(inner, *, level=0)` ¶

`serialize(obj)` ¶

`deserialize(data, *, ref_factory=None)` ¶