acemq_amqp.codecs

 1# Copyright 2026 AceMQ.
 2#
 3# Licensed under the Apache License, Version 2.0 (the "License");
 4# you may not use this file except in compliance with the License.
 5# You may obtain a copy of the License at
 6#
 7#     https://www.apache.org/licenses/LICENSE-2.0
 8#
 9# Unless required by applicable law or agreed to in writing, software
10# distributed under the License is distributed on an "AS IS" BASIS,
11# WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
12# See the License for the specific language governing permissions and
13# limitations under the License.
14
15"""The formats the other AceMQ libraries ship, each behind its own extra.
16
17:mod:`acemq_amqp.codec` carries JSON, text and bytes, and nothing there needs
18anything installed. The Java and Go libraries ship five more as separate
19optional modules — YAML, TOML, XML, Protobuf and Avro — and a Java or Go service
20publishing any of those produced a message this library could not read. That is
21the gap these close. It is an interoperability gap rather than a capability one:
22the formats were always available in Python, but the *content types* were not
23claimed by anything here, so a perfectly readable message was refused.
24
25Each one is a module of its own and none of them is imported by
26``acemq_amqp``, so the core keeps its promise of depending on nothing::
27
28    pip install "acemq-amqp[yaml]"
29
30    from acemq_amqp.codecs.yaml import YamlCodec
31
32    mq = await connect(url, codec=CompositeCodec(JsonCodec(), YamlCodec()))
33
34XML is the exception and needs no extra: it is written against
35:mod:`xml.etree.ElementTree` and :mod:`xml.parsers.expat` from the standard
36library. See :mod:`acemq_amqp.codecs.xml` for what was done about external
37entities, which a message body from a queue very much invites.
38
39Importing a module registers its codec by name where a codec can be built with
40no arguments — ``yaml``, ``toml`` and ``xml``. Protobuf and Avro cannot be:
41neither format's bytes describe themselves, so a codec needs a message type or a
42schema before it can read anything, and there is nothing sensible for a no-
43argument factory to hand back.
44
45The write types are the contract, and they are the ones Java and Go write:
46
47============  ==============================
48``yaml``      ``application/yaml``
49``toml``      ``application/toml``
50``xml``       ``application/xml``
51``protobuf``  ``application/x-protobuf``
52``avro``      ``avro/binary``, or
53              ``application/vnd.acemq.avro`` when a schema identifier is framed
54              into the message
55============  ==============================
56
57What each *reads* is deliberately wider, because a producer in another stack
58writes whichever spelling its own library picked. See each module.
59"""
60
61from __future__ import annotations
62
63__all__: list[str] = []