Fix: Make error initializers more consistent

README.rst

@@ -455,8 +455,8 @@ bodies.
                            'database. It worked on my box.')
 
             raise falcon.HTTPError(falcon.HTTP_725,
-                                   'Database Error',
-                                   description)
+                                   title='Database Error',
+                                   description=description)
 
 
     class SinkAdapter:
@@ -488,18 +488,18 @@ bodies.
                 description = ('Please provide an auth token '
                                'as part of the request.')
 
-                raise falcon.HTTPUnauthorized('Auth token required',
-                                              description,
-                                              challenges,
+                raise falcon.HTTPUnauthorized(title='Auth token required',
+                                              description=description,
+                                              challenges=challenges,
                                               href='http://docs.example.com/auth')
 
             if not self._token_is_valid(token, account_id):
                 description = ('The provided auth token is not valid. '
                                'Please request a new token and try again.')
 
-                raise falcon.HTTPUnauthorized('Authentication required',
-                                              description,
-                                              challenges,
+                raise falcon.HTTPUnauthorized(title='Authentication required',
+                                              description=description,
+                                              challenges=challenges,
                                               href='http://docs.example.com/auth')
 
         def _token_is_valid(self, token, account_id):
@@ -511,13 +511,13 @@ bodies.
         def process_request(self, req, resp):
             if not req.client_accepts_json:
                 raise falcon.HTTPNotAcceptable(
-                    'This API only supports responses encoded as JSON.',
+                    title='This API only supports responses encoded as JSON.',
                     href='http://docs.examples.com/api/json')
 
             if req.method in ('POST', 'PUT'):
                 if 'application/json' not in req.content_type:
                     raise falcon.HTTPUnsupportedMediaType(
-                        'This API only supports requests encoded as JSON.',
+                        title='This API only supports requests encoded as JSON.',
                         href='http://docs.examples.com/api/json')
 
 
@@ -537,16 +537,16 @@ bodies.
 
             body = req.stream.read()
             if not body:
-                raise falcon.HTTPBadRequest('Empty request body',
-                                            'A valid JSON document is required.')
+                raise falcon.HTTPBadRequest(title='Empty request body',
+                                            description='A valid JSON document is required.')
 
             try:
                 req.context.doc = json.loads(body.decode('utf-8'))
 
             except (ValueError, UnicodeDecodeError):
                 raise falcon.HTTPError(falcon.HTTP_753,
-                                       'Malformed JSON',
-                                       'Could not decode the request body. The '
+                                       title='Malformed JSON',
+                                       description='Could not decode the request body. The '
                                        'JSON was incorrect or not encoded as '
                                        'UTF-8.')
 
@@ -566,7 +566,7 @@ bodies.
                        'exceed ' + str(limit) + ' bytes in length.')
 
                 raise falcon.HTTPPayloadTooLarge(
-                    'Request body is too large', msg)
+                    title='Request body is too large', description=msg)
 
         return hook
 
@@ -591,9 +591,9 @@ bodies.
                                'We appreciate your patience.')
 
                 raise falcon.HTTPServiceUnavailable(
-                    'Service Outage',
-                    description,
-                    30)
+                    title='Service Outage',
+                    description=description,
+                    retry_after=30)
 
             # NOTE: Normally you would use resp.media for this sort of thing;
             # this example serves only to demonstrate how the context can be
@@ -610,8 +610,8 @@ bodies.
                 doc = req.context.doc
             except AttributeError:
                 raise falcon.HTTPBadRequest(
-                    'Missing thing',
-                    'A thing must be submitted in the request body.')
+                    title='Missing thing',
+                    description='A thing must be submitted in the request body.')
 
             proper_thing = self.db.add_thing(doc)
 

docs/_newsfragments/777.feature.rst

@@ -0,0 +1,3 @@
+The error classes in ``falcon.errors`` were updated to have the ``title`` and
+``description`` keyword arguments and to correctly handle headers passed as
+list of tuples

docs/_newsfragments/777.misc.rst

@@ -0,0 +1,2 @@
+Deprecate the use of positional arguments for the optional kw args of
+the HTTPError subclasses

docs/_newsfragments/777.removal.rst

@@ -0,0 +1,2 @@
+The class :class:`~.falcon.http_error.NoRepresentation` was removed since
+all :class:`~.falcon.HTTPError` have optional representation.

docs/api/errors.rst

@@ -54,8 +54,8 @@ All classes are available directly in the ``falcon`` package namespace::
             # ...
 
             raise falcon.HTTPBadRequest(
-                "TTL Out of Range",
-                "The message's TTL must be between 60 and 300 seconds, inclusive."
+                title="TTL Out of Range",
+                description="The message's TTL must be between 60 and 300 seconds, inclusive."
             )
 
             # ...
@@ -79,7 +79,7 @@ Base Class
 Mixins
 ------
 
-.. autoclass:: falcon.http_error.NoRepresentation
+.. autoclass:: falcon.http_error.OptionalRepresentation
     :members:
 
 .. _predefined_errors:

docs/api/hooks.rst

@@ -15,7 +15,7 @@ an image resource:
     def validate_image_type(req, resp, resource, params):
         if req.content_type not in ALLOWED_IMAGE_TYPES:
             msg = 'Image type not allowed. Must be PNG, JPEG, or GIF'
-            raise falcon.HTTPBadRequest('Bad request', msg)
+            raise falcon.HTTPBadRequest(title='Bad request', description=msg)
 
 You would attach this hook to an ``on_post`` responder like so:
 
@@ -56,7 +56,7 @@ as needed:
     def validate_image_type(req, resp, resource, params, allowed_types):
         if req.content_type not in allowed_types:
             msg = 'Image type not allowed.'
-            raise falcon.HTTPBadRequest('Bad request', msg)
+            raise falcon.HTTPBadRequest(title='Bad request', description=msg)
 
     @falcon.before(validate_image_type, ['image/png'])
     def on_post(self, req, resp):

docs/user/quickstart.rst

@@ -112,8 +112,8 @@ parameters, handling errors, and working with request and response bodies.
                            'database. It worked on my box.')
 
             raise falcon.HTTPError(falcon.HTTP_725,
-                                   'Database Error',
-                                   description)
+                                   title='Database Error',
+                                   description=description)
 
 
     class SinkAdapter:
@@ -145,18 +145,18 @@ parameters, handling errors, and working with request and response bodies.
                 description = ('Please provide an auth token '
                                'as part of the request.')
 
-                raise falcon.HTTPUnauthorized('Auth token required',
-                                              description,
-                                              challenges,
+                raise falcon.HTTPUnauthorized(title='Auth token required',
+                                              description=description,
+                                              challenges=challenges,
                                               href='http://docs.example.com/auth')
 
             if not self._token_is_valid(token, account_id):
                 description = ('The provided auth token is not valid. '
                                'Please request a new token and try again.')
 
-                raise falcon.HTTPUnauthorized('Authentication required',
-                                              description,
-                                              challenges,
+                raise falcon.HTTPUnauthorized(title='Authentication required',
+                                              description=description,
+                                              challenges=challenges,
                                               href='http://docs.example.com/auth')
 
         def _token_is_valid(self, token, account_id):
@@ -168,13 +168,13 @@ parameters, handling errors, and working with request and response bodies.
         def process_request(self, req, resp):
             if not req.client_accepts_json:
                 raise falcon.HTTPNotAcceptable(
-                    'This API only supports responses encoded as JSON.',
+                    title='This API only supports responses encoded as JSON.',
                     href='http://docs.examples.com/api/json')
 
             if req.method in ('POST', 'PUT'):
                 if 'application/json' not in req.content_type:
                     raise falcon.HTTPUnsupportedMediaType(
-                        'This API only supports requests encoded as JSON.',
+                        title='This API only supports requests encoded as JSON.',
                         href='http://docs.examples.com/api/json')
 
 
@@ -194,16 +194,16 @@ parameters, handling errors, and working with request and response bodies.
 
             body = req.stream.read()
             if not body:
-                raise falcon.HTTPBadRequest('Empty request body',
-                                            'A valid JSON document is required.')
+                raise falcon.HTTPBadRequest(title='Empty request body',
+                                            description='A valid JSON document is required.')
 
             try:
                 req.context.doc = json.loads(body.decode('utf-8'))
 
             except (ValueError, UnicodeDecodeError):
                 raise falcon.HTTPError(falcon.HTTP_753,
-                                       'Malformed JSON',
-                                       'Could not decode the request body. The '
+                                       title='Malformed JSON',
+                                       description='Could not decode the request body. The '
                                        'JSON was incorrect or not encoded as '
                                        'UTF-8.')
 
@@ -223,7 +223,7 @@ parameters, handling errors, and working with request and response bodies.
                        'exceed ' + str(limit) + ' bytes in length.')
 
                 raise falcon.HTTPPayloadTooLarge(
-                    'Request body is too large', msg)
+                    title='Request body is too large', description=msg)
 
         return hook
 
@@ -248,9 +248,9 @@ parameters, handling errors, and working with request and response bodies.
                                'We appreciate your patience.')
 
                 raise falcon.HTTPServiceUnavailable(
-                    'Service Outage',
-                    description,
-                    30)
+                    title='Service Outage',
+                    description=description,
+                    retry_after=30)
 
             # NOTE: Normally you would use resp.media for this sort of thing;
             # this example serves only to demonstrate how the context can be
@@ -267,8 +267,8 @@ parameters, handling errors, and working with request and response bodies.
                 doc = req.context.doc
             except AttributeError:
                 raise falcon.HTTPBadRequest(
-                    'Missing thing',
-                    'A thing must be submitted in the request body.')
+                    title='Missing thing',
+                    description='A thing must be submitted in the request body.')
 
             proper_thing = self.db.add_thing(doc)
 

docs/user/tutorial.rst

@@ -1293,7 +1293,7 @@ message. Add this method below the definition of ``ALLOWED_IMAGE_TYPES``:
     def validate_image_type(req, resp, resource, params):
         if req.content_type not in ALLOWED_IMAGE_TYPES:
             msg = 'Image type not allowed. Must be PNG, JPEG, or GIF'
-            raise falcon.HTTPBadRequest('Bad request', msg)
+            raise falcon.HTTPBadRequest(title='Bad request', description=msg)
 
 And then attach the hook to the ``on_post()`` responder:
 

examples/things_advanced.py

@@ -26,8 +26,8 @@ def handle(ex, req, resp, params):
                        'database. It worked on my box.')
 
         raise falcon.HTTPError(falcon.HTTP_725,
-                               'Database Error',
-                               description)
+                               title='Database Error',
+                               description=description)
 
 
 class SinkAdapter:
@@ -59,18 +59,18 @@ def process_request(self, req, resp):
             description = ('Please provide an auth token '
                            'as part of the request.')
 
-            raise falcon.HTTPUnauthorized('Auth token required',
-                                          description,
-                                          challenges,
+            raise falcon.HTTPUnauthorized(title='Auth token required',
+                                          description=description,
+                                          challenges=challenges,
                                           href='http://docs.example.com/auth')
 
         if not self._token_is_valid(token, account_id):
             description = ('The provided auth token is not valid. '
                            'Please request a new token and try again.')
 
-            raise falcon.HTTPUnauthorized('Authentication required',
-                                          description,
-                                          challenges,
+            raise falcon.HTTPUnauthorized(title='Authentication required',
+                                          description=description,
+                                          challenges=challenges,
                                           href='http://docs.example.com/auth')
 
     def _token_is_valid(self, token, account_id):
@@ -82,13 +82,13 @@ class RequireJSON:
     def process_request(self, req, resp):
         if not req.client_accepts_json:
             raise falcon.HTTPNotAcceptable(
-                'This API only supports responses encoded as JSON.',
+                title='This API only supports responses encoded as JSON.',
                 href='http://docs.examples.com/api/json')
 
         if req.method in ('POST', 'PUT'):
             if 'application/json' not in req.content_type:
                 raise falcon.HTTPUnsupportedMediaType(
-                    'This API only supports requests encoded as JSON.',
+                    title='This API only supports requests encoded as JSON.',
                     href='http://docs.examples.com/api/json')
 
 
@@ -108,16 +108,16 @@ def process_request(self, req, resp):
 
         body = req.stream.read()
         if not body:
-            raise falcon.HTTPBadRequest('Empty request body',
-                                        'A valid JSON document is required.')
+            raise falcon.HTTPBadRequest(title='Empty request body',
+                                        description='A valid JSON document is required.')
 
         try:
             req.context.doc = json.loads(body.decode('utf-8'))
 
         except (ValueError, UnicodeDecodeError):
             raise falcon.HTTPError(falcon.HTTP_753,
-                                   'Malformed JSON',
-                                   'Could not decode the request body. The '
+                                   title='Malformed JSON',
+                                   description='Could not decode the request body. The '
                                    'JSON was incorrect or not encoded as '
                                    'UTF-8.')
 
@@ -137,7 +137,7 @@ def hook(req, resp, resource, params):
                    'exceed ' + str(limit) + ' bytes in length.')
 
             raise falcon.HTTPPayloadTooLarge(
-                'Request body is too large', msg)
+                title='Request body is too large', description=msg)
 
     return hook
 
@@ -162,9 +162,9 @@ def on_get(self, req, resp, user_id):
                            'We appreciate your patience.')
 
             raise falcon.HTTPServiceUnavailable(
-                'Service Outage',
-                description,
-                30)
+                title='Service Outage',
+                description=description,
+                retry_after=30)
 
         # NOTE: Normally you would use resp.media for this sort of thing;
         # this example serves only to demonstrate how the context can be
@@ -181,8 +181,8 @@ def on_post(self, req, resp, user_id):
             doc = req.context.doc
         except AttributeError:
             raise falcon.HTTPBadRequest(
-                'Missing thing',
-                'A thing must be submitted in the request body.')
+                title='Missing thing',
+                description='A thing must be submitted in the request body.')
 
         proper_thing = self.db.add_thing(doc)
 

falcon/app.py

@@ -732,7 +732,8 @@ def set_error_serializer(self, serializer):
             The default serializer will not render any response body for
             :class:`~.HTTPError` instances where the `has_representation`
             property evaluates to ``False`` (such as in the case of types
-            that subclass :class:`falcon.http_error.NoRepresentation`).
+            that subclass :class:`falcon.http_error.OptionalRepresentation`
+            and do not provide a description).
             However a custom serializer will be called regardless of the
             property value, and it may choose to override the
             representation logic.