codecs
¶
Interfaces for managing type-enforced wire protocols (codecs).
CodecT
module-attribute
¶
CodecT = TypeAliasType('CodecT', Codec, type_params=(T))
Generic type alias with an upper bound of Codec
.
DecoderT
module-attribute
¶
DecoderT: TypeAlias = Callable[[bytes], MarshalledValueT]
Protocol for a wire deserializer.
EncoderT
module-attribute
¶
EncoderT: TypeAlias = Callable[[MarshalledValueT], bytes]
Protocol for a wire serializer.
Codec
dataclass
¶
Codec(marshal: AbstractMarshaller[T], unmarshal: AbstractUnmarshaller[T], encoder: EncoderT, decoder: DecoderT)
Bases: Generic[T]
A standard wire protocol (codec).
This codec enables you to directly encode and decode your data model into your wire protocol.
decoder
instance-attribute
¶
decoder: DecoderT
The decoder used to deserialize a bytes-like object into a Python data structure for marshalling into T
.
encoder
instance-attribute
¶
encoder: EncoderT
The encoder used to serialize a marshalled T
into bytes.
marshal
instance-attribute
¶
marshal: AbstractMarshaller[T]
The marshaller used to convert an instance of T
to a serializable object.
unmarshal
instance-attribute
¶
unmarshal: AbstractUnmarshaller[T]
The unmarshaller used to convert a deserialized object into an instance of T
.
decode
¶
decode(value: bytes) -> T
Decode an instance of T
from bytes.
We will first decode the data from bytes using the
decoder
, then unmarshal the data into an
instance of T
using unmarshal
.
Parameters:
-
value
(bytes
) –The bytes to decode.
Source code in src/typelib/codecs.py
encode
¶
encode(value: T) -> bytes
Encode an instance of T
to bytes.
We will first marshal the given instance using the
marshal
, then encode the marshalled data
into bytes using the encoder
.
Parameters:
-
value
(T
) –The instance to encode.
Source code in src/typelib/codecs.py
codec
¶
codec(t: type[T], *, marshaller: AbstractMarshaller[T] | None = None, unmarshaller: AbstractUnmarshaller[T] | None = None, encoder: EncoderT = compat.json.dumps, decoder: DecoderT = compat.json.loads, codec_cls: type[CodecT[T]] | None = None) -> CodecT[T]
Factory function for creating a Codec
instance.
Note
In the simplest case, all that needs be provided is the first parameter (t
). We will
generate a marshaller, unmarshaller and build a codec. However, we provide ample
means for customization:
- You can pass in a subclass of
Codec
tocodec_cls
. - You may supply custom
marshaller
orunmarshaller
callables - we will generate one using the high-level APIs frommarshals
andunmarshals
if not supplied. - The
encoder
anddecoder
default to JSON, using either stdlibjson
ororjson
if available. You may provide customencoder
anddecoder
callables, the only requirement is they ser/des to/frombytes
.
Tip
If you installed the json
extra when you installed this library, then you have
installed orjson
.
Parameters:
-
t
(type[T]
) –The type to create the interchange protocol for.
-
marshaller
(AbstractMarshaller[T] | None
, default:None
) –The marshaller used to marshal inputs into the associated type. (optional)
-
unmarshaller
(AbstractUnmarshaller[T] | None
, default:None
) –The unmarshaller used to unmarshal inputs into the associated type. (optional)
-
encoder
(EncoderT
, default:dumps
) –The encoder for encoding data for over-the-wire (defaults to JSON).
-
decoder
(DecoderT
, default:loads
) –The decoder for decoding data from over-the-wire (defaults to JSON).
-
codec_cls
(type[CodecT[T]] | None
, default:None
) –The codec class definition, if overloading (optional).