typelib
¶
The top-level API for typelib.
Typical Usage
>>> import dataclasses
>>> import typelib
>>>
>>> @dataclasses.dataclass
... class Data:
... attr: int
... key: str
...
>>>
>>> typelib.unmarshal(Data, '{"key":"string","attr":"1"}')
Data(attr=1, key='string')
>>> typelib.marshal(Data(attr=1, key='string'))
{'attr': 1, 'key': 'string'}
>>> codec = typelib.codec(Data)
>>> codec.encode(Data(attr=1, key='string'))
b'{"attr":1,"key":"string"}'
>>> codec.decode(b'{"key":"string","attr":1}')
Data(attr=1, key='string')
AbstractMarshaller
¶
Abstract base class defining the common interface for marshallers.
Marshallers are custom callables which maintain type-specific information. They use this information to provide robust, performant logic reducing Python objects into their primitive representations for over-the-wire encoding.
Marshallers support contextual serialization, which enables the marshalling of nested types.
Attributes:
-
t
(type[T]
) –The root type of this marshaller.
-
origin
(type[T]
) –If
t
is a generic, this will be an actionable runtime type related tot
, otherwise it is the same ast
. -
context
(ContextT
) –The complete type context for this unmarshaller.
-
var
(str | None
) –If this unmarshaller is used in a nested context, this will reference the field/parameter/index at which this unmarshaller should be used.
Parameters:
-
t
(type[T]
) –The root type of this marshaller.
-
context
(ContextT
) –The complete type context for this marshaller.
-
var
(str | None
, default:None
) –The associated field or parameter name for this unmarshaller (optional).
Source code in src/typelib/marshals/routines.py
AbstractUnmarshaller
¶
Abstract base class defining the common interface for unmarshallers.
Unmarshallers are custom callables which maintain type-specific information. They use this information to provide robust, performant logic for decoding and converting primtive Python objects or JSON-endcoded data into their target type.
Unmarshallers support contextual deserialization, which enables the unmarshalling of nested types.
Attributes:
-
t
(type[T]
) –The root type of this unmarshaller.
-
origin
(type[T]
) –If
t
is a generic, this will be an actionable runtime type related tot
, otherwise it is the same ast
. -
context
(ContextT
) –The complete type context for this unmarshaller.
-
var
(str | None
) –If this unmarshaller is used in a nested context, this will reference the field/parameter/index at which this unmarshaller should be used.
Parameters:
-
t
(type[T]
) –The root type of this unmarshaller.
-
context
(ContextT
) –The complete type context for this unmarshaller.
-
var
(str | None
, default:None
) –The associated field or parameter name for this unmarshaller (optional).
Source code in src/typelib/unmarshals/routines.py
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).
Source code in src/typelib/codecs.py
decode
¶
Decode a bytes object into an instance of t
.
Parameters:
-
t
(type[T] | ForwardRef | str
) –A type hint for resolving the unmarshaller.
-
value
(bytes
) –The value to decode.
-
decoder
(DecoderT
, default:loads
) –A callable that takes a bytes object and returns a Python value.
Source code in src/typelib/api.py
encode
¶
encode(value: T, *, t: type[T] | ForwardRef | str | None = None, encoder: EncoderT = compat.json.dumps) -> bytes
Encode a value into a bytes object.
Parameters:
-
value
(T
) –The value to encode.
-
t
(type[T] | ForwardRef | str | None
, default:None
) –A type hint for resolving the marshaller.
-
encoder
(EncoderT
, default:dumps
) –A callable that takes a value and returns a bytes object.
Source code in src/typelib/api.py
marshal
¶
marshal(value: Any, *, t: type[T] | ForwardRef | str | None = None) -> MarshalledValueT
Marshal value
from typ
into MarshalledValueT
.
Parameters:
-
value
(Any
) –The value to reduce to a simple, encode-able type.
-
t
(type[T] | ForwardRef | str | None
, default:None
) –The type to use for building the marshaller (optional). If not provided, we'll default to the type of the input value.
Source code in src/typelib/marshals/api.py
marshaller
¶
marshaller(t: type[T] | ForwardRef | TypeAliasType | str) -> AbstractMarshaller[T]
Get a marshaller routine for a given type.
Parameters:
-
t
(type[T] | ForwardRef | TypeAliasType | str
) –The type annotation to generate a marshaller for. Can be a type, type alias,
typing.ForwardRef
, or string reference.
Source code in src/typelib/marshals/api.py
unmarshal
¶
unmarshaller
¶
unmarshaller(t: type[T] | ForwardRef | TypeAliasType | str) -> AbstractUnmarshaller[T]
Get an un-marshaller routine for a given type.
Parameters:
-
t
(type[T] | ForwardRef | TypeAliasType | str
) –The type annotation to generate an unmarshaller for. May be a type, type alias,
typing.ForwardRef
, or string reference.