Merge branch 'error-changes'

Fixes #7, #4.

Author: toastdriven

docs/tutorial.rst

@@ -451,6 +451,56 @@ allowed by Restless. It's the only sane/safe default to have & it's very easy
 to fix.
 
 
+Error Handling
+==============
+
+By default, Restless tries to serialize any exceptions that may be encountered.
+What gets serialized depends on two methods: ``Resource.is_debug()`` &
+``Resource.bubble_exceptions()``.
+
+``is_debug``
+------------
+
+Regardless of the error type, the exception's message will get serialized into
+the response under the ``"error"`` key. For example, if an ``IOError`` is
+raised during processing, you'll get a response like::
+
+    HTTP/1.0 500 INTERNAL SERVER ERROR
+    Content-Type: application/json
+    # Other headers...
+
+    {
+        "error": "Whatever."
+    }
+
+If ``Resource.is_debug()`` returns ``True`` (the default is ``False``), Restless
+will also include a traceback. For example::
+
+    HTTP/1.0 500 INTERNAL SERVER ERROR
+    Content-Type: application/json
+    # Other headers...
+
+    {
+        "error": "Whatever.",
+        "traceback": "Traceback (most recent call last):\n # Typical traceback..."
+    }
+
+Each framework-specific ``Resource`` subclass implements ``is_debug()`` in a
+way most appropriate for the framework. In the case of the ``DjangoResource``,
+it returns ``settings.DEBUG``, allowing your resources to stay consistent with
+the rest of your application.
+
+``bubble_exceptions``
+---------------------
+
+If ``Resource.bubble_exceptions()`` returns ``True`` (the default is ``False``),
+any exception encountered will simply be re-raised & it's up to your setup to
+handle it. Typically, this behavior is undesirable except in development & with
+frameworks that can provide extra information/debugging on exceptions. Feel
+free to override it (``return True``) or implement application-specific logic
+if that meets your needs.
+
+
 Authentication
 ==============
 

restless/resources.py

@@ -1,8 +1,9 @@
 import six
+import sys
 
 from .constants import OK, CREATED, ACCEPTED, NO_CONTENT
 from .exceptions import MethodNotImplemented, Unauthorized
-from .utils import json, lookup_data, MoreTypesJSONEncoder
+from .utils import json, lookup_data, MoreTypesJSONEncoder, format_traceback
 
 
 class Resource(object):
@@ -192,18 +193,23 @@ def build_error(self, err):
 
         :returns: A response object
         """
-        data = json.dumps({
+        data = {
             'error': six.text_type(err),
-        })
+        }
+
+        if self.is_debug():
+            # Add the traceback.
+            data['traceback'] = format_traceback(sys.exc_info())
+
+        body = self.raw_serialize(data)
         status = getattr(err, 'status', 500)
-        return self.build_response(data, status=status)
+        return self.build_response(body, status=status)
 
     def is_debug(self):
         """
         Controls whether or not the resource is in a debug environment.
 
-        If so, exceptions will be reraised instead of returning a serialized
-        response.
+        If so, tracebacks will be added to the serialized response.
 
         The default implementation simply returns ``False``, so if you're
         integrating with a new web framework, you'll need to override this
@@ -214,6 +220,21 @@ def is_debug(self):
         """
         return False
 
+    def bubble_exceptions(self):
+        """
+        Controls whether or not exceptions will be re-raised when encountered.
+
+        The default implementation returns ``False``, which means errors should
+        return a serialized response.
+
+        If you'd like exceptions to be re-raised, override this method & return
+        ``True``.
+
+        :returns: Whether exceptions should be re-raised or not
+        :rtype: boolean
+        """
+        return False
+
     def handle(self, endpoint, *args, **kwargs):
         """
         A convenient dispatching method, this centralized some of the common
@@ -257,14 +278,27 @@ def handle(self, endpoint, *args, **kwargs):
             data = view_method(*args, **kwargs)
             serialized = self.serialize(method, endpoint, data)
         except Exception as err:
-            if self.is_debug():
-                raise
-
-            return self.build_error(err)
+            return self.handle_error(err)
 
         status = self.status_map.get(self.http_methods[endpoint][method], OK)
         return self.build_response(serialized, status=status)
 
+    def handle_error(self, err):
+        """
+        When an exception is encountered, this generates a serialized error
+        message to return the user.
+
+        :param err: The exception seen. The message is exposed to the user, so
+            beware of sensitive data leaking.
+        :type err: Exception
+
+        :returns: A response object
+        """
+        if self.bubble_exceptions():
+            raise err
+
+        return self.build_error(err)
+
     def raw_deserialize(self, body):
         """
         The low-level deserialization.

restless/utils.py

@@ -1,5 +1,6 @@
 import datetime
 import decimal
+import traceback
 
 try:
     import json
@@ -82,3 +83,15 @@ def default(self, data):
             return str(data)
         else:
             return super(MoreTypesJSONEncoder, self).default(data)
+
+
+def format_traceback(exc_info):
+    stack = traceback.format_stack()
+    stack = stack[:-2]
+    stack.extend(traceback.format_tb(exc_info[2]))
+    stack.extend(traceback.format_exception_only(exc_info[0], exc_info[1]))
+    stack_str = "Traceback (most recent call last):\n"
+    stack_str += "".join(stack)
+    # Remove the last \n
+    stack_str = stack_str[:-1]
+    return stack_str

tests/test_dj.py

@@ -189,25 +189,46 @@ def test_as_view(self):
     def test_handle_not_implemented(self):
         self.res.request = FakeHttpRequest('TRACE')
 
-        with self.assertRaises(MethodNotImplemented):
-            self.res.handle('list')
+        resp = self.res.handle('list')
+        self.assertEqual(resp['Content-Type'], 'application/json')
+        self.assertEqual(resp.status_code, 501)
+        resp_json = json.loads(resp.content.decode('utf-8'))
+        self.assertEqual(resp_json['error'], "Unsupported method 'TRACE' for list endpoint.")
+        self.assertTrue('traceback' in resp_json)
 
     def test_handle_not_authenticated(self):
         # Special-cased above for testing.
         self.res.request = FakeHttpRequest('DELETE')
 
-        with self.assertRaises(Unauthorized):
-            self.res.handle('list')
+        # First with DEBUG on
+        resp = self.res.handle('list')
+        self.assertEqual(resp['Content-Type'], 'application/json')
+        self.assertEqual(resp.status_code, 401)
+        resp_json = json.loads(resp.content.decode('utf-8'))
+        self.assertEqual(resp_json['error'], 'Unauthorized.')
+        self.assertTrue('traceback' in resp_json)
 
         # Now with DEBUG off.
         settings.DEBUG = False
         self.addCleanup(setattr, settings, 'DEBUG', True)
         resp = self.res.handle('list')
         self.assertEqual(resp['Content-Type'], 'application/json')
         self.assertEqual(resp.status_code, 401)
-        self.assertEqual(json.loads(resp.content.decode('utf-8')), {
+        resp_json = json.loads(resp.content.decode('utf-8'))
+        self.assertEqual(resp_json, {
             'error': 'Unauthorized.',
         })
+        self.assertFalse('traceback' in resp_json)
+
+        # Last, with bubble_exceptions.
+        class Bubbly(DjTestResource):
+            def bubble_exceptions(self):
+                return True
+
+        with self.assertRaises(Unauthorized):
+            bubb = Bubbly()
+            bubb.request = FakeHttpRequest('DELETE')
+            bubb.handle('list')
 
     def test_handle_build_err(self):
         # Special-cased above for testing.

tests/test_resources.py

@@ -100,6 +100,9 @@ def test_build_error(self):
     def test_is_debug(self):
         self.assertFalse(self.res.is_debug())
 
+    def test_bubble_exceptions(self):
+        self.assertFalse(self.res.bubble_exceptions())
+
     def test_raw_deserialize(self):
         body = '{"title": "Hitchhiker\'s Guide To The Galaxy", "author": "Douglas Adams"}'
         self.assertEqual(self.res.raw_deserialize(body), {

tests/test_utils.py

@@ -1,6 +1,7 @@
+import sys
 import unittest
 
-from restless.utils import lookup_data
+from restless.utils import lookup_data, format_traceback
 
 
 class InstaObj(object):
@@ -65,3 +66,17 @@ def test_empty_lookup(self):
     def test_complex_miss(self):
         with self.assertRaises(AttributeError):
             lookup_data('more.nested.nope', self.dict_data)
+
+
+class FormatTracebackTestCase(unittest.TestCase):
+    def test_format_traceback(self):
+        try:
+            raise ValueError("Because we need an exception.")
+        except:
+            exc_info = sys.exc_info()
+            result = format_traceback(exc_info)
+            self.assertTrue(result.startswith('Traceback (most recent call last):\n'))
+            self.assertFalse(result.endswith('\n'))
+            lines = result.split('\n')
+            self.assertTrue(len(lines) > 3)
+            self.assertEqual(lines[-1], 'ValueError: Because we need an exception.')