feat(error-template-support): add support for response error templates (#25)

This commit bears the support for response error templates which are resolved at runtime in the response handler class. Other than the feature, this commit contains unit tests, a fix for the default case at the endpoint level along with some refactoring of the existing code in error case and response handler classes.

closes #24

Author: sufyankhanrao

apimatic_core/response_handler.py

@@ -1,12 +1,11 @@
+import re
 from apimatic_core.http.response.api_response import ApiResponse
 from apimatic_core.types.error_case import ErrorCase
 
 
 class ResponseHandler:
 
-    def __init__(
-            self
-    ):
+    def __init__(self):
         self._deserializer = None
         self._convertor = None
         self._deserialize_into = None
@@ -39,8 +38,16 @@ def is_nullify404(self, is_nullify404):
         self._is_nullify404 = is_nullify404
         return self
 
-    def local_error(self, error_code, description, exception_type):
-        self._local_errors[str(error_code)] = ErrorCase().description(description).exception_type(exception_type)
+    def local_error(self, error_code, error_message, exception_type):
+        self._local_errors[str(error_code)] = ErrorCase()\
+            .error_message(error_message)\
+            .exception_type(exception_type)
+        return self
+
+    def local_error_template(self, error_code, error_message_template, exception_type):
+        self._local_errors[str(error_code)] = ErrorCase()\
+            .error_message_template(error_message_template)\
+            .exception_type(exception_type)
         return self
 
     def datetime_format(self, datetime_format):
@@ -87,20 +94,12 @@ def handle(self, response, global_errors):
         return deserialized_value
 
     def validate(self, response, global_errors):
-        actual_status_code = str(response.status_code)
-        if self._local_errors:
-            for expected_status_code, error_case in self._local_errors.items():
-                if actual_status_code == expected_status_code:
-                    raise error_case.get_exception_type()(error_case.get_description(), response)
+        if response.status_code in range(200, 300):
+            return
 
-        if global_errors:
-            for expected_status_code, error_case in global_errors.items():
-                if actual_status_code == expected_status_code:
-                    raise error_case.get_exception_type()(error_case.get_description(), response)
+        self.validate_against_error_cases(response, self._local_errors)
 
-        if (response.status_code < 200 or response.status_code > 208) and global_errors.get('default'):
-            error_case = global_errors['default']
-            raise error_case.get_exception_type()(error_case.get_description(), response)
+        self.validate_against_error_cases(response, global_errors)
 
     def apply_xml_deserializer(self, response):
         if self._xml_item_name:
@@ -131,3 +130,23 @@ def apply_convertor(self, deserialized_value):
             return self._convertor(deserialized_value)
 
         return deserialized_value
+
+    @staticmethod
+    def validate_against_error_cases(response, error_cases):
+        actual_status_code = str(response.status_code)
+        # Handling error case when configured as explicit error code
+        error_case = error_cases.get(actual_status_code) if error_cases else None
+        if error_case:
+            error_case.raise_exception(response)
+
+        # Handling error case when configured as explicit error codes range
+        default_range_error_case = [error_cases[status_code] for status_code, error_case in error_cases.items()
+                                    if re.match(r'^[{}]XX$'.format(actual_status_code[0]),
+                                                status_code)] if error_cases else None
+        if default_range_error_case:
+            default_range_error_case[0].raise_exception(response)
+
+        # Handling default error case if configured
+        default_error_case = error_cases.get('default') if error_cases else None
+        if default_error_case:
+            default_error_case.raise_exception(response)

apimatic_core/types/error_case.py

@@ -1,22 +1,94 @@
+import re
+from apimatic_core.utilities.api_helper import ApiHelper
+
 
 class ErrorCase:
 
-    def get_description(self):
-        return self._description
+    def is_error_message_template(self):
+        """Checks if the set exception message is a template or not.
 
-    def get_exception_type(self):
-        return self._exception_type
+            Returns:
+                string: True if the exception message is a template.
+            """
+        return True if self._error_message_template else False
 
-    def __init__(
-            self
-    ):
-        self._description = None
+    def __init__(self):
+        self._error_message = None
+        self._error_message_template = None
         self._exception_type = None
 
-    def description(self, description):
-        self._description = description
+    def error_message(self, error_message):
+        """Setter for the error message.
+            Args:
+                error_message: The simple exception message.
+            """
+        self._error_message = error_message
+        return self
+
+    def error_message_template(self, error_message_template):
+        """Setter for the error message template.
+            Args:
+                error_message_template: The exception message template containing placeholders.
+            """
+        self._error_message_template = error_message_template
         return self
 
     def exception_type(self, exception_type):
+        """Setter for the exception type.
+            Args:
+                exception_type: The exception type to raise.
+            """
         self._exception_type = exception_type
         return self
+
+    def get_error_message(self, response):
+        """Getter for the error message for the exception case. This considers both error message
+        and error template message. Error message template has the higher precedence over an error message.
+            Args:
+                response: The received http response.
+
+            Returns:
+                string: The resolved exception message.
+            """
+        if self.is_error_message_template():
+            return self._get_resolved_error_message_template(response)
+        return self._error_message
+
+    def raise_exception(self, response):
+        """Raises the exception for the current error case type.
+            Args:
+                response: The received http response.
+            """
+        raise self._exception_type(self.get_error_message(response), response)
+
+    def _get_resolved_error_message_template(self, response):
+        """Updates all placeholders in the given message template with provided value.
+
+                Args:
+                    response: The received http response.
+
+                Returns:
+                    string: The resolved template value.
+                """
+        placeholders = re.findall(r'\{\$.*?\}', self._error_message_template)
+
+        status_code_placeholder = set(filter(lambda element: element == '{$statusCode}', placeholders))
+        header_placeholders = set(filter(lambda element: element.startswith('{$response.header'), placeholders))
+        body_placeholders = set(filter(lambda element: element.startswith('{$response.body'), placeholders))
+
+        # Handling response code placeholder
+        error_message_template = ApiHelper.resolve_template_placeholders(status_code_placeholder,
+                                                                         str(response.status_code),
+                                                                         self._error_message_template)
+
+        # Handling response header placeholder
+        error_message_template = ApiHelper.resolve_template_placeholders(header_placeholders, response.headers,
+                                                                         error_message_template)
+
+        # Handling response body placeholder
+        response_payload = ApiHelper.json_deserialize(response.text, as_dict=True)
+        error_message_template = ApiHelper.resolve_template_placeholders_using_json_pointer(body_placeholders,
+                                                                                            response_payload,
+                                                                                            error_message_template)
+
+        return error_message_template

apimatic_core/utilities/api_helper.py

@@ -1,15 +1,15 @@
 # -*- coding: utf-8 -*-
-
-
+from collections import abc
 import re
-import sys
 import datetime
 import calendar
 import email.utils as eut
 from time import mktime
 
 import jsonpickle
 import dateutil.parser
+from jsonpointer import JsonPointerException, resolve_pointer
+
 from apimatic_core.types.datetime_format import DateTimeFormat
 from apimatic_core.types.file_wrapper import FileWrapper
 from apimatic_core.types.array_serialization_format import SerializationFormats
@@ -516,6 +516,61 @@ def when_defined(func, value):
     def is_file_wrapper_instance(param):
         return isinstance(param, FileWrapper)
 
+    @staticmethod
+    def resolve_template_placeholders_using_json_pointer(placeholders, value, template):
+        """Updates all placeholders in the given message template with provided value.
+
+        Args:
+            placeholders: The placeholders that need to be searched and replaced in the given template value.
+            value: The dictionary containing the actual values to replace with.
+            template: The template string containing placeholders.
+
+        Returns:
+            string: The resolved template value.
+        """
+        for placeholder in placeholders:
+            extracted_value = ''
+
+            if '#' in placeholder:
+                # pick the 2nd chunk then remove the last character (i.e. `}`) of the string value
+                node_pointer = placeholder.rsplit('#')[1].rstrip('}')
+                try:
+                    extracted_value = resolve_pointer(value, node_pointer) if node_pointer else ''
+                    extracted_value = ApiHelper.json_serialize(extracted_value) \
+                        if type(extracted_value) in [list, dict] else str(extracted_value)
+                except JsonPointerException:
+                    pass
+            elif value is not None:
+                extracted_value = ApiHelper.json_serialize(value)
+            template = template.replace(placeholder, extracted_value)
+
+        return template
+
+    @staticmethod
+    def resolve_template_placeholders(placeholders, values, template):
+        """Updates all placeholders in the given message template with provided value.
+
+                Args:
+                    placeholders: The placeholders that need to be searched and replaced in the given template value.
+                    values: The dictionary|string value which refers to the actual values to replace with.
+                    template: The template string containing placeholders.
+
+                Returns:
+                    string: The resolved template value.
+                """
+        for placeholder in placeholders:
+            if isinstance(values, abc.Mapping):
+                # pick the last chunk then strip the last character (i.e. `}`) of the string value
+                key = placeholder.rsplit('.', maxsplit=1)[-1].rstrip('}') if '.' in placeholder \
+                    else placeholder.lstrip('{').rstrip('}')
+                value_to_replace = str(values.get(key)) if values.get(key) else ''
+                template = template.replace(placeholder, value_to_replace)
+            else:
+                values = str(values) if values is not None else ''
+                template = template.replace(placeholder, values)
+
+        return template
+
     class CustomDate(object):
 
         """ A base class for wrapper classes of datetime.

requirements.txt

@@ -4,3 +4,4 @@ enum34~=1.1, >=1.1.10
 apimatic-core-interfaces~=0.1.0
 requests~=2.28.1
 setuptools~=58.1.0
+jsonpointer~=2.3

setup.py

@@ -12,7 +12,7 @@
 
 setup(
     name='apimatic-core',
-    version='0.1.4',
+    version='0.2.0',
     description='A library that contains core logic and utilities for '
                 'consuming REST APIs using Python SDKs generated by APIMatic.',
     long_description=long_description,
@@ -27,7 +27,8 @@
         'python-dateutil~=2.8.1',
         'requests~=2.28.1',
         'enum34~=1.1, >=1.1.10',
-        'setuptools~=58.1.0'
+        'setuptools~=58.1.0',
+        'jsonpointer~=2.3'
     ],
     tests_require=[
         'pytest~=7.1.3',

tests/apimatic_core/base.py

@@ -123,9 +123,24 @@ def read_file(file_name):
     @staticmethod
     def global_errors():
         return {
-            '400': ErrorCase().description('400 Global').exception_type(GlobalTestException),
-            '412': ErrorCase().description('Precondition Failed').exception_type(NestedModelException),
-            'default': ErrorCase().description('Invalid response').exception_type(GlobalTestException),
+            '400': ErrorCase().error_message('400 Global').exception_type(GlobalTestException),
+            '412': ErrorCase().error_message('Precondition Failed').exception_type(NestedModelException),
+            '3XX': ErrorCase().error_message('3XX Global').exception_type(GlobalTestException),
+            'default': ErrorCase().error_message('Invalid response').exception_type(GlobalTestException),
+        }
+
+    @staticmethod
+    def global_errors_with_template_message():
+        return {
+            '400': ErrorCase()
+            .error_message_template('error_code => {$statusCode}, header => {$response.header.accept}, '
+                                    'body => {$response.body#/ServerCode} - {$response.body#/ServerMessage}')
+            .exception_type(GlobalTestException),
+            '412': ErrorCase()
+            .error_message_template('global error message -> error_code => {$statusCode}, header => '
+                                    '{$response.header.accept}, body => {$response.body#/ServerCode} - '
+                                    '{$response.body#/ServerMessage} - {$response.body#/model/name}')
+            .exception_type(NestedModelException)
         }
 
     @staticmethod