Merge pull request #138 from python-odin/development

Release 2.2

Author: timsavage

HISTORY

@@ -1,3 +1,14 @@
+2.2
+===
+
+- Fix a bug where annotated resource fields failed to get resolved.
+- Fix issues where functools.cached_property does not work on annotated resources as __set_name__
+  was not being called.
+- Updates to documentation
+  - Introduce integration example for mapping Django models
+  - Flesh out mapping documentation
+  - Fix missing link to dict_codec reference.
+
 2.1
 ===
 

docs/contents.rst

@@ -10,3 +10,4 @@ Contents
    ref/index
    integration/index
    examples/index
+   change-history

docs/integration/django/index.rst

@@ -0,0 +1,31 @@
+#######################
+Integration with Django
+#######################
+
+
+Mapping Django models to resources
+==================================
+
+To utilise a Django database model in a :doc:`/ref/mapping/index` a
+``FieldResolver`` is required to identify fields available on the model.
+
+The following is an example of a resolver for Django models.
+
+.. code-block:: python
+
+    from odin import registration
+    from odin.utils import getmeta
+    from odin.mapping import FieldResolverBase
+
+
+    class ModelFieldResolver(FieldResolverBase):
+        """
+        Field resolver for Django Models
+        """
+
+        def get_field_dict(self):
+            meta = getmeta(self.obj)
+            return {f.attname: f for f in meta.fields}
+
+
+    registration.register_field_resolver(ModelFieldResolver, models.Model)

docs/ref/codecs/index.rst

@@ -11,6 +11,7 @@ JSON data Odin provides the same ``load``, ``loads`` style interface.
    :maxdepth: 2
 
    csv_codec
+   dict_codec
    json_codec
    msgpack_codec
    toml_codec

docs/ref/mapping/classes.rst

@@ -238,3 +238,20 @@ resources.
 There is also the simpler method when only a forward mapping is desired.
 
     .. autofunction:: forward_mapping_factory
+
+
+Mapping Other Types
+===================
+
+Mappers can also be used to map other to and from other object types that are not odin Resources.
+
+.. tip:: There is worked example for :doc:`Django Models </integration/django/index>` in the integration section.
+
+For mapping rules to be determined the mapper must resolve which fields/attributes
+are available on a type that can be mapped. This is done using a field resolver
+that is associated with the type (or sub type) of the object to be mapped.
+
+The field resolver is a class inherited from ``FieldResolverBase`` that can resolve
+what fields are available. This class is them registered with Odins type registry.
+
+    .. autoclass:: FieldResolverBase

docs/ref/mapping/helpers.rst

@@ -11,7 +11,30 @@ When defining mappings using the shorthand mappings property these methods simpl
 They also provide sensible defaults.
 
 .. automodule:: odin.mapping
+    :noindex:
 
     .. autofunction:: define
 
     .. autofunction:: assign
+
+
+Action Helpers
+==============
+
+Predefined actions for use in mapping definitions.
+
+.. automodule:: odin.mapping.helpers
+
+    .. autofunction:: sum_fields
+
+    .. autoclass:: JoinFields
+
+    .. autoclass:: SplitField
+
+    .. autoclass:: ApplyMapping
+
+
+Special Mappers
+===============
+
+    .. autoclass:: NoOpMapper

poetry.lock

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

pyproject.toml

@@ -42,9 +42,7 @@ def _new_meta_instance(
     meta_def: Optional[object],
     new_class: "AnnotatedResourceType",
 ) -> MOT:
-    """
-    Instantiate meta options instance and handle inheritance of required fields
-    """
+    """Instantiate meta options instance and handle inheritance of required fields."""
     base_meta = getattr(new_class, "_meta", None)
     new_meta = meta_options_type(meta_def)
     new_class.add_to_class("_meta", new_meta)
@@ -73,9 +71,7 @@ def _new_meta_instance(
 
 
 def _iterate_attrs(attrs: Dict[str, Any]) -> Iterable[Tuple[str, BaseField]]:
-    """
-    Iterate through attributes and combine with annotations
-    """
+    """Iterate through attributes and combine with annotations."""
     annotations = attrs.pop("__annotations__", None) or {}
 
     # Yield any annotations processed into field instances
@@ -92,9 +88,7 @@ def _iterate_attrs(attrs: Dict[str, Any]) -> Iterable[Tuple[str, BaseField]]:
 def _add_parent_fields_to_class(
     new_class: "AnnotatedResourceType", new_meta: ResourceOptions, parents
 ):
-    """
-    Iterate through parent attrs and yield fields
-    """
+    """Iterate through parent attrs and yield fields."""
     # All the fields of any type declared on this model
     local_field_attr_names = {f.attname for f in new_meta.fields}
     field_attr_names = set(local_field_attr_names)
@@ -201,15 +195,15 @@ def add_to_class(cls, name, value):
         if hasattr(value, "contribute_to_class"):
             value.contribute_to_class(cls, name)
         else:
+            if hasattr(value, "__set_name__"):
+                value.__set_name__(cls, name)
             setattr(cls, name, value)
 
 
 class AnnotatedResource(
     ResourceBase, metaclass=AnnotatedResourceType, meta_options_type=ResourceOptions
 ):
-    """
-    New Style Resource utilising type annotations for defining fields
-    """
+    """New Style Resource utilising type annotations for defining fields."""
 
 
 AResource = AnnotatedResource

src/odin/annotated_resource/__init__.py

@@ -1,23 +1,16 @@
 import abc
-from typing import Protocol
 
 
 class ResourceIterable(abc.ABC):
-    """
-    Iterable object that yields resources.
-    """
+    """Iterable object that yields resources."""
 
     @abc.abstractmethod
     def __iter__(self):
-        """
-        Iterate resources
-        """
+        """Iterate resources"""
 
 
 class TypedResourceIterable(ResourceIterable, abc.ABC):
-    """
-    Iterable object that yields a specific resource.
-    """
+    """Iterable object that yields a specific resource."""
 
     def __init__(self, resource_type):
         self.resource_type = resource_type