first attempt at an adjacently tagged union for consideration

.coveragerc

@@ -17,7 +17,7 @@ omit = *migrations*
 exclude_lines =
   # Lines matching these regexes don't need to be covered
   # https://coverage.readthedocs.io/en/coverage-5.5/excluding.html?highlight=exclude_lines#advanced-exclusion
-  
+
   # this is the default but must be explicitly specified since
   # we are overriding exclude_lines
   pragma: no cover

dev-requirements.txt

@@ -235,7 +235,9 @@ importlib-metadata==4.6.1 \
 importlib-resources==5.2.2 \
     --hash=sha256:2480d8e07d1890056cb53c96e3de44fead9c62f2ba949b0f2e4c4345f4afa977 \
     --hash=sha256:a65882a4d0fe5fbf702273456ba2ce74fe44892c25e42e057aca526b702a6d4b
-    # via virtualenv
+    # via
+    #   -r test-requirements.in
+    #   virtualenv
 incremental==21.3.0 \
     --hash=sha256:02f5de5aff48f6b9f665d99d48bfc7ec03b6e3943210de7cfc88856d755d6f57 \
     --hash=sha256:92014aebc6a20b78a8084cdd5645eeaa7f74b8933f70fa3ada2cfbd1e3b54321
@@ -600,6 +602,10 @@ typed-ast==1.4.3 \
     #   astroid
     #   black
     #   mypy
+typeguard==2.12.1 \
+    --hash=sha256:c2af8b9bdd7657f4bd27b45336e7930171aead796711bc4cfc99b4731bb9d051 \
+    --hash=sha256:cc15ef2704c9909ef9c80e19c62fb8468c01f75aad12f651922acf4dbe822e02
+    # via -r requirements.in
 typing-extensions==3.10.0.0 \
     --hash=sha256:0ac0f89795dd19de6b97debb0c6af1c70987fd80a2d62d1958f7e56fcc31b497 \
     --hash=sha256:50b6f157849174217d0656f99dc82fe932884fb250826c18350e159ec6cdf342 \

docs/reference/fields.rst

@@ -0,0 +1,124 @@
+..
+   TODO: figure out proper location for this stuff including making it public
+         if in desert
+
+
+desert._fields module
+=====================
+
+Tagged Unions
+-------------
+
+Serializing and deserializing data of uncertain type can be tricky.
+Cases where the type is hinted with :class:`typing.Union` create such cases.
+Some solutions have a list of possible types and use the first one that works.
+This can be used in some cases where the data for different types is sufficiently unique as to only work with a single type.
+In more general cases you have difficulties where data of one type ends up getting processed by another type that is similar, but not the same.
+
+In an effort to reduce the heuristics involved in serialization and deserialization an explicit tag can be added to identify the type.
+That is the basic feature of this group of utilities related to tagged unions.
+
+A tag indicating the object's type can be applied in various ways.
+Presently three forms are implemented: adjacently tagged, internally tagged, and externally tagged.
+Adjacently tagged is the most explicit form and is the recommended default.
+You can write your own helper functions to implement your own tagging form if needed and still make use of the rest of the mechanisms implemented here.
+A code example follows the forms below and provides related reference.
+
+- A class definition and bare serialized object for reference
+
+   .. literalinclude:: ../../tests/test_fields.py
+      :language: python
+      :start-after: # start cat_class_example
+      :end-before: # end cat_class_example
+
+   .. literalinclude:: ../../tests/example/untagged.json
+      :language: json
+
+
+- Adjacently tagged
+
+   .. literalinclude:: ../../tests/example/adjacent.json
+      :language: json
+
+- Internally tagged
+
+   .. literalinclude:: ../../tests/example/internal.json
+      :language: json
+
+- Externally tagged
+
+   .. literalinclude:: ../../tests/example/external.json
+      :language: json
+
+The code below is an actual test from the Desert test suite that provides an example usage of the tools that will be covered in detail below.
+
+.. literalinclude:: ../../tests/test_fields.py
+   :language: python
+   :start-after: # start tagged_union_example
+   :end-before: # end tagged_union_example
+
+
+Fields
+......
+
+A :class:`marshmallow.fields.Field` is needed to describe the serialization.
+This role is filled by :class:`desert._fields.TaggedUnionField`.
+Several helpers at different levels are included to generate field instances that support each of the tagging schemes shown above.
+:ref:`Registries <tagged_union_registries>` are used to collect and hold the information needed to make the choices the field needs.
+The helpers below create :class:`desert._fields.TaggedUnionField` instances that are backed by the passed registry.
+
+.. autofunction:: desert._fields.adjacently_tagged_union_from_registry
+.. autofunction:: desert._fields.internally_tagged_union_from_registry
+.. autofunction:: desert._fields.externally_tagged_union_from_registry
+
+.. autoclass:: desert._fields.TaggedUnionField
+   :members:
+   :undoc-members:
+   :show-inheritance:
+
+The fields can be created from :class:`desert._fields.FromObjectProtocol` and :class:`desert._fields.FromTagProtocol` instead of registries, if need.
+
+.. autofunction:: desert._fields.adjacently_tagged_union
+.. autofunction:: desert._fields.internally_tagged_union
+.. autofunction:: desert._fields.externally_tagged_union
+
+.. autoclass:: desert._fields.FromObjectProtocol
+   :members: __call__
+   :undoc-members:
+   :show-inheritance:
+
+.. autoclass:: desert._fields.FromTagProtocol
+   :members: __call__
+   :undoc-members:
+   :show-inheritance:
+
+
+.. _tagged_union_registries:
+
+Registries
+..........
+
+Since unions are inherently about handling multiple types, fields that handle unions must be able to make decisions about multiple types.
+Registries are not required to leverage other pieces of union support if you are developing their logic yourself.
+If you are using the builtin mechanisms then a registry will be needed to define the relationships between tags, fields, and object types.
+
+..
+   TODO: sure seems like the user shouldn't need to call Nested() themselves
+
+The registry's :meth:`desert._fields.FieldRegistryProtocol.register` method will primarily be used.
+As an example, you might register a custom class ``Cat`` by providing a hint of ``Cat``, a tag of ``"cat"``, and a field such as ``marshmallow.fields.Nested(desert.schema(Cat))``.
+
+.. autoclass:: desert._fields.FieldRegistryProtocol
+   :members:
+   :undoc-members:
+   :show-inheritance:
+
+.. autoclass:: desert._fields.TypeAndHintFieldRegistry
+   :members:
+   :undoc-members:
+   :show-inheritance:
+
+.. autoclass:: desert._fields.HintTagField
+   :members:
+   :undoc-members:
+   :show-inheritance:

docs/reference/index.rst

@@ -5,3 +5,4 @@ Reference
     :glob:
 
     desert*
+    fields

docs/requirements.txt

@@ -1,5 +1,7 @@
 sphinx~=4.1
 # >= 1.0.0rc1 for https://github.com/readthedocs/sphinx_rtd_theme/issues/1115
 sphinx-rtd-theme >= 1.0.0rc1
+# < 0.17 for /home/docs/checkouts/readthedocs.org/user_builds/desert/checkouts/94/src/desert/_fields.py:docstring of desert._fields.externally_tagged_union_from_registry:4: WARNING: circular inclusion in "include" directive: snippets/tag_forms/external.rst < snippets/tag_forms/internal.rst < snippets/tag_forms/adjacent.rst < snippets/tag_forms/external.rst < reference/fields.rst
+docutils < 0.17
 sphinx-autodoc-typehints
 -e .[dev]

requirements.in

@@ -2,3 +2,5 @@ marshmallow>=3.0
 attrs
 typing_inspect
 dataclasses; python_version < "3.7"
+#https://github.com/Stewori/pytypes/archive/b7271ec654d3553894febc6e0d8ad1b0e1ac570a.zip
+typeguard

requirements.txt

@@ -20,6 +20,10 @@ mypy-extensions==0.4.3 \
     --hash=sha256:090fedd75945a69ae91ce1303b5824f428daf5a028d2f6ab8a299250a846f15d \
     --hash=sha256:2d82818f5bb3e369420cb3c4060a7970edba416647068eb4c5343488a6c604a8
     # via typing-inspect
+typeguard==2.12.1 \
+    --hash=sha256:c2af8b9bdd7657f4bd27b45336e7930171aead796711bc4cfc99b4731bb9d051 \
+    --hash=sha256:cc15ef2704c9909ef9c80e19c62fb8468c01f75aad12f651922acf4dbe822e02
+    # via -r requirements.in
 typing-extensions==3.10.0.0 \
     --hash=sha256:0ac0f89795dd19de6b97debb0c6af1c70987fd80a2d62d1958f7e56fcc31b497 \
     --hash=sha256:50b6f157849174217d0656f99dc82fe932884fb250826c18350e159ec6cdf342 \