Merge pull request #176 from python-odin/development

2.11rc3

Author: timsavage

.readthedocs.yaml

@@ -5,6 +5,10 @@
 # Required
 version: 2
 
+sphinx:
+  # Path to your Sphinx configuration file.
+  configuration: docs/conf.py
+
 # Set the version of Python and other tools you might need
 build:
   os: ubuntu-22.04

HISTORY

@@ -1,3 +1,15 @@
+2.11rc3
+=======
+
+Changes
+-------
+
+- Move the inclusion of the type field (typically `$`) into the resource and not individual codecs.
+  Ensuring it is defined first.
+
+  This could cause a breaking change to any tests that expect existing field order.
+
+
 2.11rc2
 =======
 

docs/conf.py

@@ -61,9 +61,9 @@
 # built documents.
 #
 # The short X.Y version.
-version = "1.0"
+version = "2.0"
 # The full version, including alpha/beta/rc tags.
-release = "1.0"
+release = "2.0"
 
 # The language for content autogenerated by Sphinx. Refer to documentation
 # for a list of supported languages.
@@ -271,4 +271,4 @@
 # texinfo_no_detailmenu = False
 
 # Example configuration for intersphinx: refer to the Python standard library.
-intersphinx_mapping = {"http://docs.python.org/": None}
+intersphinx_mapping = {"python": ("https://docs.python.org/3", None)}

pyproject.toml

@@ -4,7 +4,7 @@ build-backend = "poetry.core.masonry.api"
 
 [tool.poetry]
 name = "odin"
-version = "2.11rc2"
+version = "2.11rc3"
 description = "Data-structure definition/validation/traversal, mapping and serialisation toolkit for Python"
 authors = ["Tim Savage <tim@savage.company>"]
 license = "BSD-3-Clause"

src/odin/codecs/dict_codec.py

@@ -1,5 +1,4 @@
 from odin import ResourceAdapter, bases, resources
-from odin.utils import getmeta
 
 TYPE_SERIALIZERS = {}
 
@@ -10,12 +9,8 @@ def __init__(self, include_virtual_fields=True, include_type_field=True):
         self.include_type_field = include_type_field
 
     def default(self, o):
-        if isinstance(o, (resources.ResourceBase, ResourceAdapter)):
-            meta = getmeta(o)
-            obj = o.to_dict(self.include_virtual_fields)
-            if self.include_type_field:
-                obj[meta.type_field] = meta.resource_name
-            return obj
+        if isinstance(o, resources.ResourceBase | ResourceAdapter):
+            return o.to_dict(self.include_virtual_fields, self.include_type_field)
         elif isinstance(o, bases.ResourceIterable):
             return list(o)
         elif o.__class__ in TYPE_SERIALIZERS:
@@ -35,9 +30,11 @@ def encode(self, o):
 
     :param d: Dict to load
 
-    :param resource: A resource type, resource name or list of resources and names to use as the base for creating a
-        resource. If a list is supplied the first item will be used if a resource type is not supplied.
-    :raises ValidationError: During building of the object graph and issues discovered are raised as a ValidationError.
+    :param resource: A resource type, resource name or list of resources and names to
+        use as the base for creating a resource. If a list is supplied the first item
+        will be used if a resource type is not supplied.
+    :raises ValidationError: During building of the object graph and issues discovered
+        are raised as a ValidationError.
 
     """
 
@@ -46,8 +43,9 @@ def dump(resource, cls=OdinEncoder, **kwargs):
     """
     Dump a resource structure into a nested :py:class:`dict`.
 
-    While a resource includes a *to_dict* method this method is not recursive. The dict codec recursively iterates
-    through the resource structure to produce a full dict. This is useful for testing for example.
+    While a resource includes a *to_dict* method this method is not recursive. The dict
+    codec recursively iterates through the resource structure to produce a full dict.
+    This is useful for testing for example.
 
     :param resource: The root resource to dump
     :param cls: Encoder class to utilise
@@ -66,13 +64,13 @@ def _encode_dict(dct):
         return {k: _encode(o) for k, o in dct.items()}
 
     def _encode(o):
-        if isinstance(o, (list, tuple)):
+        if isinstance(o, list | tuple):
             return _encode_list(o)
         elif isinstance(o, dict):
             return _encode_dict(o)
         else:
             o = _default(o)
-            if isinstance(o, (list, tuple, dict)):
+            if isinstance(o, list | tuple | dict):
                 return _encode(o)
             return o
 

src/odin/codecs/json_codec.py

@@ -5,7 +5,6 @@
 
 from odin import ResourceAdapter, bases, resources, serializers
 from odin.exceptions import CodecDecodeError, CodecEncodeError
-from odin.utils import getmeta
 
 LIST_TYPES = (bases.ResourceIterable, typing.ValuesView, typing.KeysView)
 JSON_TYPES = {
@@ -18,9 +17,7 @@
 
 
 class OdinEncoder(json.JSONEncoder):
-    """
-    Encoder for Odin resources.
-    """
+    """Encoder for Odin resources."""
 
     def __init__(
         self, include_virtual_fields=True, include_type_field=True, *args, **kwargs
@@ -30,12 +27,8 @@ def __init__(
         self.include_type_field = include_type_field
 
     def default(self, o):
-        if isinstance(o, (resources.ResourceBase, ResourceAdapter)):
-            meta = getmeta(o)
-            obj = o.to_dict(self.include_virtual_fields)
-            if self.include_type_field:
-                obj[meta.type_field] = meta.resource_name
-            return obj
+        if isinstance(o, resources.ResourceBase | ResourceAdapter):
+            return o.to_dict(self.include_virtual_fields, self.include_type_field)
 
         elif isinstance(o, LIST_TYPES):
             return list(o)
@@ -53,11 +46,12 @@ def load(fp, resource=None, full_clean=True, default_to_not_supplied=False):
     See :py:meth:`loads` for more details of the loading operation.
 
     :param fp: a file pointer to read JSON data from.
-    :param resource: A resource type, resource name or list of resources and names to use as the base for creating a
-        resource. If a list is supplied the first item will be used if a resource type is not supplied.
+    :param resource: A resource type, resource name or list of resources and names to
+        use as the base for creating a resource. If a list is supplied the first item
+        will be used if a resource type is not supplied.
     :param full_clean: Do a full clean of the object as part of the loading process.
-    :param default_to_not_supplied: Used for loading partial resources. Any fields not supplied are replaced with
-        NOT_SUPPLIED.
+    :param default_to_not_supplied: Used for loading partial resources. Any fields not
+        supplied are replaced with NOT_SUPPLIED.
     :returns: A resource object or object graph of resources loaded from file.
 
     """
@@ -68,18 +62,21 @@ def loads(s, resource=None, full_clean=True, default_to_not_supplied=False):
     """
     Load from a JSON encoded string.
 
-    If a ``resource`` value is supplied it is used as the base resource for the supplied JSON. I one is not supplied a
-    resource type field ``$`` is used to obtain the type represented by the dictionary. A ``ValidationError`` will be
-    raised if either of these values are supplied and not compatible. It is valid for a type to be supplied in the file
-    to be a child object from within the inheritance tree.
+    If a ``resource`` value is supplied it is used as the base resource for the
+    supplied JSON. I one is not supplied a resource type field ``$`` is used to obtain
+    the type represented by the dictionary. A ``ValidationError`` will be raised if
+    either of these values are supplied and not compatible. It is valid for a type to
+    be supplied in the file to be a child object from within the inheritance tree.
 
     :param s: String to load and parse.
-    :param resource: A resource type, resource name or list of resources and names to use as the base for creating a
-        resource. If a list is supplied the first item will be used if a resource type is not supplied.
+    :param resource: A resource type, resource name or list of resources and names to
+        use as the base for creating a resource. If a list is supplied the first item
+        will be used if a resource type is not supplied.
     :param full_clean: Do a full clean of the object as part of the loading process.
-    :param default_to_not_supplied: Used for loading partial resources. Any fields not supplied are replaced with
-        NOT_SUPPLIED.
-    :returns: A resource object or object graph of resources parsed from supplied string.
+    :param default_to_not_supplied: Used for loading partial resources. Any fields not
+        supplied are replaced with NOT_SUPPLIED.
+    :returns: A resource object or object graph of resources parsed from supplied
+        string.
 
     """
     try:
@@ -95,7 +92,8 @@ def dump(resource, fp, cls=OdinEncoder, **kwargs):
     Dump to a JSON encoded file.
 
     :param resource: The root resource to dump to a JSON encoded file.
-    :param cls: Encoder to use serializing to a string; default is the :py:class:`OdinEncoder`.
+    :param cls: Encoder to use serializing to a string; default is the
+        :py:class:`OdinEncoder`.
     :param fp: The file pointer that represents the output file.
 
     """
@@ -110,7 +108,8 @@ def dumps(resource, cls=OdinEncoder, **kwargs):
     Dump to a JSON encoded string.
 
     :param resource: The root resource to dump to a JSON encoded file.
-    :param cls: Encoder to use serializing to a string; default is the :py:class:`OdinEncoder`.
+    :param cls: Encoder to use serializing to a string; default is the
+        :py:class:`OdinEncoder`.
     :returns: JSON encoded string.
 
     """

src/odin/codecs/msgpack_codec.py

@@ -1,4 +1,5 @@
 """Codec to load/save Message Pack (msgpack) documents."""
+
 import datetime
 import uuid
 from typing import TextIO
@@ -11,7 +12,6 @@
     ) from None  # noqa
 
 from odin import ResourceAdapter, bases, resources, serializers
-from odin.utils import getmeta
 
 TYPE_SERIALIZERS = {
     datetime.date: serializers.date_iso_format,
@@ -31,11 +31,8 @@ def __init__(self, include_virtual_fields: bool = True, *args, **kwargs):
         self.include_virtual_fields = include_virtual_fields
 
     def default(self, o):
-        if isinstance(o, (resources.ResourceBase, ResourceAdapter)):
-            meta = getmeta(o)
-            obj = o.to_dict(self.include_virtual_fields)
-            obj[meta.type_field] = meta.resource_name
-            return obj
+        if isinstance(o, resources.ResourceBase | ResourceAdapter):
+            return o.to_dict(self.include_virtual_fields, True)
 
         elif isinstance(o, bases.ResourceIterable):
             return list(o)
@@ -55,7 +52,8 @@ def load(
     See :py:meth:`loads` for more details of the loading operation.
 
     :param fp: a file pointer to read MessagePack data from.
-    :param resource: A resource instance or a resource name to use as the base for creating a resource.
+    :param resource: A resource instance or a resource name to use as the base for
+        creating a resource.
     :param full_clean: Do a full clean of the object as part of the loading process.
     :param default_to_not_supplied:
     :returns: A resource object or object graph of resources loaded from file.
@@ -73,16 +71,20 @@ def loads(
 ):
     """Load from a MessagePack encoded string/bytes.
 
-    If a ``resource`` value is supplied it is used as the base resource for the supplied MessagePack data. I one is not
-    supplied a resource type field ``$`` is used to obtain the type represented by the dictionary. A ``ValidationError``
-    will be raised if either of these values are supplied and not compatible. It is valid for a type to be supplied in
-    the file to be a child object from within the inheritance tree.
+    If a ``resource`` value is supplied it is used as the base resource for the
+    supplied MessagePack data. I one is not supplied a resource type field ``$`` is
+    used to obtain the type represented by the dictionary. A ``ValidationError``
+    will be raised if either of these values are supplied and not compatible. It is
+    valid for a type to be supplied in the file to be a child object from within the
+    inheritance tree.
 
     :param s: String to load and parse.
-    :param resource: A resource instance or a resource name to use as the base for creating a resource.
+    :param resource: A resource instance or a resource name to use as the base for
+        creating a resource.
     :param full_clean: Do a full clean of the object as part of the loading process.
     :param default_to_not_supplied:
-    :returns: A resource object or object graph of resources parsed from supplied string.
+    :returns: A resource object or object graph of resources parsed from supplied
+        string.
     """
     return resources.build_object_graph(
         msgpack.loads(s), resource, full_clean, False, default_to_not_supplied
@@ -94,13 +96,14 @@ def dump(
     fp: TextIO,
     cls=OdinPacker,
     include_virtual_fields: bool = True,
-    **kwargs
+    **kwargs,
 ):
     """Dump to a MessagePack encoded file.
 
     :param include_virtual_fields:
     :param resource: The root resource to dump to a MessagePack encoded file.
-    :param cls: Encoder to use serializing to a string; default is the :py:class:`OdinEncoder`.
+    :param cls: Encoder to use serializing to a string; default is the
+        :py:class:`OdinEncoder`.
     :param fp: The file pointer that represents the output file.
     """
     fp.write(cls(include_virtual_fields, **kwargs).pack(resource))
@@ -110,13 +113,14 @@ def dumps(
     resource: resources.ResourceBase,
     cls=OdinPacker,
     include_virtual_fields: bool = True,
-    **kwargs
+    **kwargs,
 ):
     """Dump to a MessagePack encoded string.
 
     :param include_virtual_fields:
     :param resource: The root resource to dump to a MessagePack encoded file.
-    :param cls: Encoder to use serializing to a string; default is the :py:class:`OdinEncoder`.
+    :param cls: Encoder to use serializing to a string; default is the
+        :py:class:`OdinEncoder`.
     :returns: MessagePack encoded string.
     """
     return cls(include_virtual_fields, **kwargs).pack(resource)