Serializers

Custom serializers

class walnats.serializers.Serializer(schema: type[T])

Base class for all serializers.

Serializers convert Python message into binary payload, so that it can be transferred over the network.

classmethod new(schema: type[T]) → Serializer[T] | None

Create a new instance of the middleware for the given type if possible.

This constructor is used by get_serializer to pick a serializer when you don’t specify one for an walnats.Event. You don’t need to implement it for your custom serializers because you specify them explicitly.

encode(message: T) → bytes

Convert a Python message into binary Nats message payload.

decode(data: bytes) → T

Convert a binary Nats message payload into Python message.

Autodetected

class walnats.serializers.BytesSerializer

Assume bytes to be already serialized, emit it as is.

class walnats.serializers.DataclassSerializer

Serialize dataclass classes as JSON.

class walnats.serializers.DatetimeSerializer

Serialize datetime or date in ISO 8601 string.

class walnats.serializers.MarshmallowSerializer

Serialize marshmallow schemas as JSON.

If you use marshmallow schemas for events, you’ll get false-positives from mypy on actors because the data you serialize with a marshmallow schema has a dict type, not the schema type. If you care about type safety, use dtaclasses or pydantic for models instead. If you can’t, throw in # type: ignore where is applicable.

class walnats.serializers.PrimitiveSerializer

Serialize built-in types as JSON.

class walnats.serializers.ProtobufSerializer

Serialize protobuf messages.

class walnats.serializers.PydanticSerializer

Serialize pydantic models as JSON.

Optional

Optional serializers are the ones that aren’t automatically detected, so you have to specify them explicitly to use.

class walnats.serializers.MessagePackSerializer

Serialize built-in types as msgpack message.

Requires msgpack package to be installed.

Wrappers

Wrappers are serializers that wrap another serializer to modify its output in some way.

class walnats.serializers.FernetSerializer(schema: type[T], serializer: Serializer[M], key: str | bytes)

Sign and encrypt the message using Fernet algorithm.

Parameters:

  • serializer – serializer whose output should be encrypted.

  • key – secret key to use. See cryptography docs on how to generate the key.

Requires cryptography package to be installed.

class walnats.serializers.GZipSerializer(schema: type[T], serializer: Serializer[M], level: int = 9)

Compress serialized data using gzip compression algorithm.

Parameters:

serializer – serializer whose output should be compressed.

class walnats.serializers.HMACSerializer(schema: type[T], serializer: Serializer[M], key: bytes, hash_algorithm: str = 'sha512')

Sign the message using HMAC algorithm.

The signed binary digest will be added at the beginning of the message.

Parameters:

  • serializer – serializer whose output should be signed.

  • key – the secret key to use.

  • hash_algorithm – hash algorithm name to use, anything supported by hashlib.