Skip to content

xtr_serializer.bundle

The xtr-dependency-injection bundle for xtr-serializer.

ALL_SERIALIZERS module-attribute

ALL_SERIALIZERS: Final = '*'

The name a tag gives every serializer by, which no named serializer may take.

DEFAULT_SERIALIZER module-attribute

DEFAULT_SERIALIZER: Final = 'default'

The name a tag gives the default serializer by, which no named serializer may take.

ENCODER_TAG module-attribute

ENCODER_TAG: Final = 'serializer.encoder'

The tag an encoder, a decoder or both carry to join a serializer.

Its attributes, and the classes tagged without being told, are those of :data:NORMALIZER_TAG, with include_built_in_encoders deciding for a built-in one.

NORMALIZER_TAG module-attribute

NORMALIZER_TAG: Final = 'serializer.normalizer'

The tag a normalizer, a denormalizer or both carry to join a serializer.

It takes three attributes, each optional:

  • priority — an int, higher tried first; without it, the definition's own priority, or 0;
  • serializer — the name of the serializer it joins, or a sequence of names: "default" (the default when absent), a configured name, or "*" for every serializer;
  • built_in — True for one a named serializer can leave out with include_built_in_normalizers=False.

A class subclassing NormalizerInterface or DenormalizerInterface carries it without being told, with no attribute; a bundle tagging it explicitly gives the attributes it needs::

services.set(MoneyNormalizer).add_tag(NORMALIZER_TAG, priority=10, serializer="*")

NamedSerializerConfig dataclass

NamedSerializerConfig(default_context: Mapping[str, object] = dict[str, object](), include_built_in_normalizers: bool = True, include_built_in_encoders: bool = True)

How a named serializer differs from the default one.

A named serializer is for a part of the application that writes differently — an API whose clients expect other options, a store that keeps only some types. It gets the normalizers and encoders tagged for its name, or for every serializer, and the built-in ones unless it leaves them out.

Attributes:

  • default_context (Mapping[str, object]) –

    Options every call to it starts from, over the bundle's own default_context key by key; a call's context still wins over both.

  • include_built_in_normalizers (bool) –

    Whether the bundle's own normalizers join it. Left out, the serializer has only the normalizers tagged for it, and must be given one.

  • include_built_in_encoders (bool) –

    Whether the bundle's own encoders join it. Left out, the serializer has only the encoders tagged for it, and must be given one.

SerializerBundle

SerializerBundle()

Bases: Bundle[SerializerConfig]

Registers the serializers, and hands each the normalizers and encoders tagged for it.

Start with the default configuration, until the kernel hands the resolved one.

build

build(builder: ContainerBuilder) -> None

Tag every normalizer and encoder class, and register the pass handing them over.

The pass runs after every bundle's process hook, so a service a bundle tags there joins its serializer too.

load_extension

load_extension(config: SerializerConfig, services: ServiceConfigurator, builder: ContainerBuilder) -> None

Register the built-in normalizer and encoder, a serializer per name, and the command.

The command joins in debug mode only, when a console bundle is active. When the http kernel profiles requests, the interfaces give a traced serializer, and the profiler's panel joins.

boot async

boot() -> None

Build every serializer, so a service tagged as what it is not fails here.

SerializerConfig dataclass

SerializerConfig(default_context: Mapping[str, object] = dict[str, object](), named_serializers: Mapping[str, NamedSerializerConfig] = dict[str, NamedSerializerConfig]())

How the bundle builds the container's serializers.

Buildable with no arguments: an application listing the bundle without configuring it gets one serializer writing JSON, with every normalizer and encoder it registers.

SerializerConfig(
    default_context={STRICT: True},
    named_serializers={"api": NamedSerializerConfig(default_context={SKIP_NULL_VALUES: True})},
)

Attributes:

  • default_context (Mapping[str, object]) –

    Options every call to every serializer starts from; a call's context wins over them key by key.

  • named_serializers (Mapping[str, NamedSerializerConfig]) –

    Serializers besides the default one, each registered under its name as the qualifier. "default" and "*" are the names tags use for the default serializer and for all of them, so neither names one here.

SerializerPass

Bases: CompilerPassInterface

Gives every serializer the services tagged for it, highest priority first.

A serializer is the default one, registered unqualified, and one per configured name, registered under that name. The pass reads the services tagged :data:NORMALIZER_TAG and :data:ENCODER_TAG, picks those each serializer is to hold — by the tag's serializer and, for a built-in one, whether a named serializer keeps built-ins — orders them by priority, then by the order they were registered in, and writes the serializer's factory to take exactly those. A mistake in a tag, or a serializer left with nothing to convert or nothing to write with, fails the build rather than the first call.

A named serializer gets its own instance of every service it shares with another — a service is handed the serializer holding it, and one instance can only be handed one. A service provided as an object, rather than built by the container, cannot be copied and is shared: one the serializer is handed to joins one serializer only.

A serializer is a normalizer and an encoder itself, so the container tags its definitions as one; the pass takes those tags off, as a serializer holds no serializer. A service decorating another joins as the service it decorates, which carries the tag.

:class:~xtr_serializer.bundle.SerializerBundle registers it behind every bundle's process hook, so a service another bundle tags there joins too.

process

process(builder: ContainerBuilder) -> None

Write the factory of every serializer.

Raises:

  • LogicError –

    When a tag cannot be read or names a serializer that does not exist, or a serializer is left without a normalizer or an encoder, or an object the serializer is handed to joins more than one.