Merge pull request #1429 from flying-sheep/errorhandler-rework-docs

Added docs for the error handler rework

docs/errorhandling.rst

@@ -1,7 +1,7 @@
 .. _application-errors:
 
-Logging Application Errors
-==========================
+Application Errors
+==================
 
 .. versionadded:: 0.3
 
@@ -28,6 +28,54 @@ exception to the :attr:`~flask.Flask.logger`.
 But there is more you can do, and we will cover some better setups to deal
 with errors.
 
+.. _error-handlers:
+
+Error handlers
+--------------
+
+.. versionadded:: 1.0
+
+You might want to show custom error pages to the user when an error occurs.
+This can be done by registering error handlers.
+
+Error handlers are normal :ref:`views` but instead of being registered for
+routes they are registered for exceptions that are rised while trying to
+do something else.
+
+Registering
+```````````
+
+Register error handlers using :meth:`~flask.Flask.errorhandler` or
+:meth:`~flask.Flask.register_error_handler`::
+
+    @app.errorhandler(werkzeug.exceptions.BadRequest)
+    def handle_bad_request(e):
+        return 'bad request!'
+    
+    app.register_error_handler(400, lambda e: 'bad request!')
+
+Those two ways are equivalent, but the first one is more clear and leaves
+you with a function to call on your whim (and in tests).  Note that
+:exc:`werkzeug.exceptions.HTTPException` subclasses like
+:exc:`~werkzeug.exceptions.BadRequest` from the example and their HTTP codes
+are interchangable when handed to the registration methods or decorator
+(``BadRequest.code == 400``).
+
+You are however not limited to a :exc:`~werkzeug.exceptions.HTTPException`
+or its code but can register a handler for every exception class you like.
+
+Handling
+````````
+
+Once an exception instance is raised, its class hierarchy is traversed,
+and searched for in the exception classes for which handlers are registered.
+The most specific handler is selected.
+
+E.g. if a instance of :exc:`ConnectionRefusedError` is raised, and a handler
+is registered for :exc:`ConnectionError` and :exc:`ConnectionRefusedError`,
+the more specific :exc:`ConnectionRefusedError` handler is called on the
+exception instance, and its response is shown to the user.
+
 Error Mails
 -----------
 

docs/quickstart.rst

@@ -701,6 +701,8 @@ Note the ``404`` after the :func:`~flask.render_template` call.  This
 tells Flask that the status code of that page should be 404 which means
 not found.  By default 200 is assumed which translates to: all went well.
 
+See :ref:`error-handlers` for more details.
+
 .. _about-responses:
 
 About Responses

docs/upgrading.rst

@@ -29,6 +29,23 @@ applications.  Instead the new ``LOGGER_HANDLER_POLICY`` configuration can
 be used to disable the default log handlers and custom log handlers can be
 set up.
 
+The behavior of error handlers was changed.
+The precedence of handlers used to be based on the decoration/call order of
+:meth:`~flask.Flask.errorhandler` and
+:meth:`~flask.Flask.register_error_handler`, respectively.
+Now the inheritance hierarchy takes precedence and handlers for more
+specific exception classes are executed instead of more general ones.
+See :ref:`error-handlers` for specifics.
+
+.. note::
+
+    There used to be a logic error allowing you to register handlers
+    only for exception *instances*. This was unintended and plain wrong,
+    and therefore was replaced with the intended behavior of registering
+    handlers only using exception classes and HTTP error codes.
+    
+    Trying to register a handler on an instance now raises :exc:`ValueError`.
+
 .. _upgrading-to-010:
 
 Version 0.10