Merge pull request #1092 from rouge8/custom-exception-handler-setting

Support customizable view EXCEPTION_HANDLER (#907)

docs/api-guide/exceptions.md

@@ -30,9 +30,27 @@ Might receive an error response indicating that the `DELETE` method is not allow
     HTTP/1.1 405 Method Not Allowed
     Content-Type: application/json; charset=utf-8
     Content-Length: 42
-    
+
     {"detail": "Method 'DELETE' not allowed."}
 
+## Custom exception handling
+
+To implement custom exception handling (e.g. to handle additional exception classes or to override the error response format), create an exception handler function with the following signature:
+
+    exception_handler(exc)
+
+* `exc`: The exception.
+
+If the function returns `None`, a 500 error will be raised.
+
+The exception handler is set globally, using the `EXCEPTION_HANDLER` setting. For example:
+
+    'EXCEPTION_HANDLER': 'project.app.module.function'
+
+If not specified, this setting defaults to the exception handler described above:
+
+    'EXCEPTION_HANDLER': 'rest_framework.views.exception_handler'
+
 ---
 
 # API Reference

docs/api-guide/settings.md

@@ -25,7 +25,7 @@ If you need to access the values of REST framework's API settings in your projec
 you should use the `api_settings` object.  For example.
 
     from rest_framework.settings import api_settings
-    
+
     print api_settings.DEFAULT_AUTHENTICATION_CLASSES
 
 The `api_settings` object will check for any user-defined settings, and otherwise fall back to the default values.  Any setting that uses string import paths to refer to a class will automatically import and return the referenced class, instead of the string literal.
@@ -339,6 +339,20 @@ Default: `'rest_framework.views.get_view_description'`
 
 ## Miscellaneous settings
 
+#### EXCEPTION_HANDLER
+
+A string representing the function that should be used when returning a response for any given exception.  If the function returns `None`, a 500 error will be raised.
+
+This setting can be changed to support error responses other than the default `{"detail": "Failure..."}` responses.  For example, you can use it to provide API responses like `{"errors": [{"message": "Failure...", "code": ""} ...]}`.
+
+This should be a function with the following signature:
+
+    exception_handler(exc)
+
+* `exc`: The exception.
+
+Default: `'rest_framework.views.exception_handler'`
+
 #### FORMAT_SUFFIX_KWARG
 
 The name of a parameter in the URL conf that may be used to provide a format suffix.

rest_framework/settings.py

@@ -77,6 +77,9 @@ DEFAULTS = {
     'VIEW_NAME_FUNCTION': 'rest_framework.views.get_view_name',
     'VIEW_DESCRIPTION_FUNCTION': 'rest_framework.views.get_view_description',
 
+    # Exception handling
+    'EXCEPTION_HANDLER': 'rest_framework.views.exception_handler',
+
     # Testing
     'TEST_REQUEST_RENDERER_CLASSES': (
         'rest_framework.renderers.MultiPartRenderer',
@@ -125,6 +128,7 @@ IMPORT_STRINGS = (
     'DEFAULT_MODEL_SERIALIZER_CLASS',
     'DEFAULT_PAGINATION_SERIALIZER_CLASS',
     'DEFAULT_FILTER_BACKENDS',
+    'EXCEPTION_HANDLER',
     'FILTER_BACKEND',
     'TEST_REQUEST_RENDERER_CLASSES',
     'UNAUTHENTICATED_USER',

rest_framework/tests/test_views.py

@@ -32,6 +32,16 @@ def basic_view(request):
         return {'method': 'PATCH', 'data': request.DATA}
 
 
+class ErrorView(APIView):
+    def get(self, request, *args, **kwargs):
+        raise Exception
+
+
+@api_view(['GET'])
+def error_view(request):
+    raise Exception
+
+
 def sanitise_json_error(error_dict):
     """
     Exact contents of JSON error messages depend on the installed version
@@ -99,3 +109,34 @@ class FunctionBasedViewIntegrationTests(TestCase):
         }
         self.assertEqual(response.status_code, status.HTTP_400_BAD_REQUEST)
         self.assertEqual(sanitise_json_error(response.data), expected)
+
+
+class TestCustomExceptionHandler(TestCase):
+    def setUp(self):
+        self.DEFAULT_HANDLER = api_settings.EXCEPTION_HANDLER
+
+        def exception_handler(exc):
+            return Response('Error!', status=status.HTTP_400_BAD_REQUEST)
+
+        api_settings.EXCEPTION_HANDLER = exception_handler
+
+    def tearDown(self):
+        api_settings.EXCEPTION_HANDLER = self.DEFAULT_HANDLER
+
+    def test_class_based_view_exception_handler(self):
+        view = ErrorView.as_view()
+
+        request = factory.get('/', content_type='application/json')
+        response = view(request)
+        expected = 'Error!'
+        self.assertEqual(response.status_code, status.HTTP_400_BAD_REQUEST)
+        self.assertEqual(response.data, expected)
+
+    def test_function_based_view_exception_handler(self):
+        view = error_view
+
+        request = factory.get('/', content_type='application/json')
+        response = view(request)
+        expected = 'Error!'
+        self.assertEqual(response.status_code, status.HTTP_400_BAD_REQUEST)
+        self.assertEqual(response.data, expected)

rest_framework/views.py

@@ -361,7 +361,7 @@ class APIView(View):
             else:
                 exc.status_code = status.HTTP_403_FORBIDDEN
 
-        response = exception_handler(exc)
+        response = self.settings.EXCEPTION_HANDLER(exc)
 
         if response is None:
             raise