xtr_serializer.bundle ¶
The xtr-dependency-injection bundle for xtr-serializer.
ALL_SERIALIZERS
module-attribute
¶
The name a tag gives every serializer by, which no named serializer may take.
DEFAULT_SERIALIZER
module-attribute
¶
The name a tag gives the default serializer by, which no named serializer may take.
ENCODER_TAG
module-attribute
¶
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
¶
The tag a normalizer, a denormalizer or both carry to join a serializer.
It takes three attributes, each optional:
priority— anint, 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—Truefor one a named serializer can leave out withinclude_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_contextkey 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 ¶
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 ¶
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
¶
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 ¶
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.