Update docstrings for serialize, deserialize changes

nikhilym · nikhilym · commit dd16873682ec · 2019-01-30T18:52:17.000-08:00
diff --git a/ask-sdk-core/ask_sdk_core/serialize.py b/ask-sdk-core/ask_sdk_core/serialize.py
@@ -60,15 +60,19 @@ def serialize(self, obj):
         # type: (Any) -> Union[Dict[str, Any], List, Tuple, str, None]
         """Builds a serialized object.
 
-        If obj is None, return None.
-        If obj is str, int, long, float, bool, return directly.
-        If obj is datetime.datetime, datetime.date convert to
-        string in iso8601 format.
-        If obj is list, serialize each element in the list.
-        If obj is dict, return the dict with serialized values.
-        If obj is ask sdk model, return the dict with keys resolved
-        from model's ``attribute_map`` and values serialized
-        based on ``deserialized_types``.
+        * If obj is None, return None.
+        * If obj is str, int, long, float, bool, return directly.
+        * If obj is datetime.datetime, datetime.date convert to
+          string in iso8601 format.
+        * If obj is list, serialize each element in the list.
+        * If obj is dict, return the dict with serialized values.
+        * If obj is ask sdk model, return the dict with keys resolved
+          from the union of model's ``attribute_map`` and
+          ``deserialized_types`` and values serialized based on
+          ``deserialized_types``.
+        * If obj is a generic class instance, return the dict with keys
+          from instance's ``deserialized_types`` and values serialized
+          based on ``deserialized_types``.
 
         :param obj: The data to serialize.
         :type obj: object
@@ -96,13 +100,22 @@ def serialize(self, obj):
         if isinstance(obj, dict):
             obj_dict = obj
         else:
-            # Convert model obj to dict except
-            # attributes `deserialized_types`, `attribute_map`
-            # and attributes which value is not None.
-            # Convert attribute name to json key in
-            # model definition for request.
+            # Convert model obj to dict
+            # All the non null attributes under `deserialized_types`
+            # map are considered for serialization.
+            # The `attribute_map` provides the key names to be used
+            # in the dict. In case of missing `attribute_map` mapping,
+            # the original attribute name is retained as the key name.
+            class_attribute_map = getattr(obj, 'attribute_map', {})
+            class_attribute_map.update(
+                {
+                    k: k for k in obj.deserialized_types.keys()
+                    if k not in class_attribute_map
+                }
+            )
+
             obj_dict = {
-                obj.attribute_map[attr]: getattr(obj, attr)
+                class_attribute_map[attr]: getattr(obj, attr)
                 for attr, _ in iteritems(obj.deserialized_types)
                 if getattr(obj, attr) is not None
             }
@@ -111,7 +124,28 @@ def serialize(self, obj):
 
     def deserialize(self, payload, obj_type):
         # type: (str, Union[T, str]) -> Any
-        """Deserializes payload into ask sdk model object.
+        """Deserializes payload into an instance of provided ``obj_type``.
+
+        The ``obj_type`` parameter can be a primitive type, a generic
+        model object or a list / dict of model objects.
+
+        The list or dict object type has to be provided as a string
+        format. For eg:
+
+        * ``'list[a.b.C]'`` if the payload is a list of instances of
+          class ``a.b.C``.
+        * ``'dict(str, a.b.C)'`` if the payload is a dict containing
+          mappings of ``str : a.b.C`` class instance types.
+
+        The method looks for a ``deserialized_types`` dict in the model
+        class, that mentions which payload values has to be
+        deserialized. In case the payload key names are different than
+        the model attribute names, the corresponding mapping can be
+        provided in another special dict ``attribute_map``. The model
+        class should also have the ``__init__`` method with default
+        values for arguments. Check
+        :py:class:`ask_sdk_model.request_envelope.RequestEnvelope`
+        source code for an example implementation.
 
         :param payload: data to be deserialized.
         :type payload: str
@@ -134,14 +168,14 @@ def deserialize(self, payload, obj_type):
 
     def __deserialize(self, payload, obj_type):
         # type: (str, Union[T, str]) -> Any
-        """Deserializes payload into ask sdk model object.
+        """Deserializes payload into a model object.
 
         :param payload: data to be deserialized.
         :type payload: str
         :param obj_type: resolved class name for deserialized object
         :type obj_type: Union[str, object]
         :return: deserialized object
-        :rtype: T
+        :rtype: object
         """
         if payload is None:
             return None
@@ -179,7 +213,7 @@ def __deserialize(self, payload, obj_type):
             if obj_type in self.NATIVE_TYPES_MAPPING:
                 obj_type = self.NATIVE_TYPES_MAPPING[obj_type]
             else:
-                # deserialize ask sdk models
+                # deserialize models
                 obj_type = self.__load_class_from_name(obj_type)
 
         if obj_type in self.PRIMITIVE_TYPES:
@@ -194,7 +228,20 @@ def __deserialize(self, payload, obj_type):
             return self.__deserialize_model(payload, obj_type)
 
     def __load_class_from_name(self, class_name):
-        # type: (str) -> str
+        # type: (str) -> T
+        """Load the class from the ``class_name`` provided.
+
+        Resolve the class name from the ``class_name`` provided, load
+        the class on path and return the resolved class. If the module
+        information is not provided in the ``class_name``, then look
+        for the class on sys ``modules``.
+
+        :param class_name: absolute class name to be loaded
+        :type class_name: str
+        :return: Resolved class reference
+        :rtype: object
+        :raises: :py:class:`ask_sdk_core.exceptions.SerializationException`
+        """
         try:
             module_class_list = class_name.rsplit(".", 1)
             if len(module_class_list) > 1:
@@ -223,7 +270,7 @@ def __deserialize_primitive(self, payload, obj_type):
         :type obj_type: object
         :return: deserialized primitive datatype object
         :rtype: object
-        :raises SerializationException
+        :raises: :py:class:`ask_sdk_core.exceptions.SerializationException`
         """
         try:
             return obj_type(payload)
@@ -247,7 +294,7 @@ def __deserialize_datetime(self, payload, obj_type):
         :type obj_type: object
         :return: deserialized primitive datatype object
         :rtype: object
-        :raises SerializationException
+        :raises: :py:class:`ask_sdk_core.exceptions.SerializationException`
         """
         try:
             from dateutil.parser import parse
@@ -273,20 +320,25 @@ def __deserialize_model(self, payload, obj_type):
         :type obj_type: object
         :return: deserialized sdk model object
         :rtype: object
-        :raises SerializationException
+        :raises: :py:class:`ask_sdk_core.exceptions.SerializationException`
         """
         try:
             if issubclass(obj_type, Enum):
                 return obj_type(payload)
 
-            if hasattr(obj_type, 'deserialized_types') and hasattr(
-                    obj_type, 'attribute_map'):
+            if hasattr(obj_type, 'deserialized_types'):
                 if hasattr(obj_type, 'get_real_child_model'):
                     obj_type = self.__get_obj_by_discriminator(
                         payload, obj_type)
 
                 class_deserialized_types = obj_type.deserialized_types
-                class_attribute_map = obj_type.attribute_map
+                class_attribute_map = getattr(obj_type, 'attribute_map', {})
+                class_attribute_map.update(
+                    {
+                        k: k for k in obj_type.deserialized_types.keys()
+                        if k not in class_attribute_map
+                    }
+                )
 
                 deserialized_model = obj_type()
                 for class_param_name, payload_param_name in iteritems(
@@ -312,7 +364,19 @@ def __deserialize_model(self, payload, obj_type):
             raise SerializationException(str(e))
 
     def __get_obj_by_discriminator(self, payload, obj_type):
-        # type: (str, Union[T, str]) -> str
+        # type: (str, Union[T, str]) -> T
+        """Get correct subclass instance using the discriminator in
+        payload.
+
+        :param payload: Payload for deserialization
+        :type payload: str
+        :param obj_type: parent class for deserializing payload into
+        :type obj_type: object
+        :return: Subclass of provided parent class, that resolves to
+            the discriminator in payload.
+        :rtype: object
+        :raises: :py:class:`ask_sdk_core.exceptions.SerializationException`
+        """
         namespaced_class_name = obj_type.get_real_child_model(payload)
         if not namespaced_class_name:
             raise SerializationException(
diff --git a/ask-sdk-core/tests/unit/data/__init__.py b/ask-sdk-core/tests/unit/data/__init__.py
@@ -15,9 +15,12 @@
 # specific language governing permissions and limitations under the
 # License.
 #
+
 from .model_enum_object import ModelEnumObject
 from .model_test_object_1 import ModelTestObject1
 from .model_test_object_2 import ModelTestObject2
+from .model_test_object_3 import ModelTestObject3
+from .model_test_object_4 import ModelTestObject4
 from .invalid_model_object import InvalidModelObject
 from .model_abstract_parent_object import ModelAbstractParentObject
 from .model_child_objects import ModelChildObject1
diff --git a/ask-sdk-core/tests/unit/data/model_test_object_3.py b/ask-sdk-core/tests/unit/data/model_test_object_3.py
@@ -0,0 +1,31 @@
+# -*- coding: utf-8 -*-
+#
+# Copyright 2018 Amazon.com, Inc. or its affiliates. All Rights
+# Reserved.
+#
+# Licensed under the Apache License, Version 2.0 (the "License").
+# You may not use this file except in compliance with the License.
+# A copy of the License is located at
+#
+# http://aws.amazon.com/apache2.0/
+#
+# or in the "license" file accompanying this file. This file is
+# distributed on an "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS
+# OF ANY KIND, either express or implied. See the License for the
+# specific language governing permissions and limitations under the
+# License.
+#
+
+
+class ModelTestObject3(object):
+    deserialized_types = {
+        'str_var': 'str',
+        'int_var': 'int'
+    }
+
+    def __init__(self, str_var=None, int_var=None):
+        self.str_var = str_var
+        self.int_var = int_var
+
+    def __eq__(self, other):
+        return self.__dict__ == other.__dict__
diff --git a/ask-sdk-core/tests/unit/data/model_test_object_4.py b/ask-sdk-core/tests/unit/data/model_test_object_4.py
@@ -0,0 +1,35 @@
+# -*- coding: utf-8 -*-
+#
+# Copyright 2018 Amazon.com, Inc. or its affiliates. All Rights
+# Reserved.
+#
+# Licensed under the Apache License, Version 2.0 (the "License").
+# You may not use this file except in compliance with the License.
+# A copy of the License is located at
+#
+# http://aws.amazon.com/apache2.0/
+#
+# or in the "license" file accompanying this file. This file is
+# distributed on an "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS
+# OF ANY KIND, either express or implied. See the License for the
+# specific language governing permissions and limitations under the
+# License.
+#
+
+
+class ModelTestObject4(object):
+    deserialized_types = {
+        'str_var': 'str',
+        'float_var': 'float'
+    }
+
+    attribute_map = {
+        'float_var': 'floatingValue'
+    }
+
+    def __init__(self, str_var=None, float_var=None):
+        self.str_var = str_var
+        self.float_var = float_var
+
+    def __eq__(self, other):
+        return self.__dict__ == other.__dict__
diff --git a/ask-sdk-core/tests/unit/test_serialize.py b/ask-sdk-core/tests/unit/test_serialize.py
@@ -132,6 +132,24 @@ def test_model_obj_serialization(self):
         assert self.test_serializer.serialize(test_model_obj_1) == expected_serialized_obj, \
             "Default Serializer serialized model object incorrectly"
 
+    def test_model_obj_without_attrmap_serialization(self):
+        test_obj_inst = data.ModelTestObject3(str_var="test", int_var=123)
+        expected_dict = {
+            "str_var": "test",
+            "int_var": 123
+        }
+        assert self.test_serializer.serialize(test_obj_inst) == expected_dict, \
+            "Default Serializer serialized object without attribute_map incorrectly"
+
+    def test_model_obj_with_incomplete_attrmap_serialization(self):
+        test_obj_inst = data.ModelTestObject4(str_var="test", float_var=3.14)
+        expected_dict = {
+            "str_var": "test",
+            "floatingValue": 3.14
+        }
+        assert self.test_serializer.serialize(test_obj_inst) == expected_dict, \
+            "Default Serializer serialized object with incomplete attribute map incorrectly"
+
     def test_enum_obj_serialization(self):
         test_model_obj_2 = data.ModelTestObject2(int_var=123)
         test_enum_obj = data.ModelEnumObject("ENUM_VAL_1")
@@ -406,6 +424,34 @@ def test_model_obj_with_additional_params_in_payload_deserialization(self):
                 test_payload, test_obj_type) == expected_obj, (
                 "Default Serializer deserialized model object incorrectly when payload has additional parameters")
 
+    def test_model_obj_without_attrmap_deserialization(self):
+        test_payload = {
+            "str_var": "Test",
+            "int_var": 123
+        }
+        test_obj_type = data.ModelTestObject3
+        expected_obj = data.ModelTestObject3(str_var="Test", int_var=123)
+
+        with patch("json.loads") as mock_json_loader:
+            mock_json_loader.return_value = test_payload
+            assert self.test_serializer.deserialize(
+                test_payload, test_obj_type) == expected_obj, (
+                "Default Serializer deserialized model object without attribute map incorrectly")
+
+    def test_model_obj_with_incomplete_attrmap_deserialization(self):
+        test_payload = {
+            "str_var": "Test",
+            "floatingValue": 3.14
+        }
+        test_obj_type = data.ModelTestObject4
+        expected_obj = data.ModelTestObject4(str_var="Test", float_var=3.14)
+
+        with patch("json.loads") as mock_json_loader:
+            mock_json_loader.return_value = test_payload
+            assert self.test_serializer.deserialize(
+                test_payload, test_obj_type) == expected_obj, (
+                "Default Serializer deserialized model object with incomplete attribute map incorrectly")
+
     def test_invalid_model_obj_deserialization(self):
         test_payload = {
             "var_1": "some value"
