maya-chen/flask
1
0
Fork 0
forked from orbit-oss/flask
Code Pull requests Activity

adjust header levels and spacing

Browse source 
use code-block consistently
This commit is contained in:
David Lord 2020-07-28 10:46:22 -07:00
parent 2db3c9a72e
commit ba118b4543
No known key found for this signature in database
GPG key ID: 7A1C87E3F5BC42A8
1 changed files with 37 additions and 28 deletions
Download patch file Download diff file Expand all files Collapse all files

65
docs/errorhandling.rst
View file

@ -101,6 +101,7 @@ Follow-up reads:
* `Getting started with Sentry <https://docs.sentry.io/quickstart/?platform=python>`_ * `Getting started with Sentry <https://docs.sentry.io/quickstart/?platform=python>`_
* `Flask-specific documentation <https://docs.sentry.io/platforms/python/flask/>`_. * `Flask-specific documentation <https://docs.sentry.io/platforms/python/flask/>`_.
.. _error-handlers: .. _error-handlers:
Error Handlers Error Handlers
@ -118,13 +119,16 @@ The status code of the response will not be set to the handler's code. Make
sure to provide the appropriate HTTP status code when returning a response from sure to provide the appropriate HTTP status code when returning a response from
a handler. a handler.
Registering Registering
``````````` ```````````
Register handlers by decorating a function with Register handlers by decorating a function with
:meth:`~flask.Flask.errorhandler`. Or use :meth:`~flask.Flask.errorhandler`. Or use
:meth:`~flask.Flask.register_error_handler` to register the function later. :meth:`~flask.Flask.register_error_handler` to register the function later.
Remember to set the error code when returning the response. :: Remember to set the error code when returning the response.
.. code-block:: python
@app.errorhandler(werkzeug.exceptions.BadRequest) @app.errorhandler(werkzeug.exceptions.BadRequest)
def handle_bad_request(e): def handle_bad_request(e):
@ -140,7 +144,9 @@ when registering handlers. (``BadRequest.code == 400``)
Non-standard HTTP codes cannot be registered by code because they are not known Non-standard HTTP codes cannot be registered by code because they are not known
by Werkzeug. Instead, define a subclass of by Werkzeug. Instead, define a subclass of
:class:`~werkzeug.exceptions.HTTPException` with the appropriate code and :class:`~werkzeug.exceptions.HTTPException` with the appropriate code and
register and raise that exception class. :: register and raise that exception class.
.. code-block:: python
class InsufficientStorage(werkzeug.exceptions.HTTPException): class InsufficientStorage(werkzeug.exceptions.HTTPException):
code = 507 code = 507
@ -155,6 +161,7 @@ Handlers can be registered for any exception class, not just
codes. Handlers can be registered for a specific class, or for all subclasses codes. Handlers can be registered for a specific class, or for all subclasses
of a parent class. of a parent class.
Handling Handling
```````` ````````
@ -191,6 +198,7 @@ raises the exception. However, the blueprint cannot handle 404 routing errors
because the 404 occurs at the routing level before the blueprint can be because the 404 occurs at the routing level before the blueprint can be
determined. determined.
Generic Exception Handlers Generic Exception Handlers
`````````````````````````` ``````````````````````````
@ -223,7 +231,6 @@ so you don't lose information about the HTTP error.
response.content_type = "application/json" response.content_type = "application/json"
return response return response
An error handler for ``Exception`` might seem useful for changing how An error handler for ``Exception`` might seem useful for changing how
all errors, even unhandled ones, are presented to the user. However, all errors, even unhandled ones, are presented to the user. However,
this is similar to doing ``except Exception:`` in Python, it will this is similar to doing ``except Exception:`` in Python, it will
@ -252,6 +259,7 @@ register handlers for both ``HTTPException`` and ``Exception``, the
``Exception`` handler will not handle ``HTTPException`` subclasses ``Exception`` handler will not handle ``HTTPException`` subclasses
because it the ``HTTPException`` handler is more specific. because it the ``HTTPException`` handler is more specific.
Unhandled Exceptions Unhandled Exceptions
```````````````````` ````````````````````
@ -286,6 +294,7 @@ An error handler for "500 Internal Server Error" will be passed uncaught excepti
addition to explicit 500 errors. In debug mode, a handler for "500 Internal Server Error" will not be used. addition to explicit 500 errors. In debug mode, a handler for "500 Internal Server Error" will not be used.
Instead, the interactive debugger will be shown. Instead, the interactive debugger will be shown.
Custom Error Pages Custom Error Pages
------------------ ------------------
@ -323,7 +332,9 @@ username and we can't find it, we raise a "404 Not Found".
return render_template("profile.html", user=user) return render_template("profile.html", user=user)
Here is another example implementation for a "404 Page Not Found" exception:: Here is another example implementation for a "404 Page Not Found" exception:
.. code-block:: python
from flask import render_template from flask import render_template
@ -332,7 +343,9 @@ Here is another example implementation for a "404 Page Not Found" exception::
# note that we set the 404 status explicitly # note that we set the 404 status explicitly
return render_template('404.html'), 404 return render_template('404.html'), 404
When using :doc:`/patterns/appfactories`:: When using :doc:`/patterns/appfactories`:
.. code-block:: python
from flask import Flask, render_template from flask import Flask, render_template
@ -346,7 +359,7 @@ When using :doc:`/patterns/appfactories`::
An example template might be this: An example template might be this:
.. sourcecode:: html+jinja .. code-block:: html+jinja
{% extends "layout.html" %} {% extends "layout.html" %}
{% block title %}Page Not Found{% endblock %} {% block title %}Page Not Found{% endblock %}
@ -356,13 +369,14 @@ An example template might be this:
<p><a href="{{ url_for('index') }}">go somewhere nice</a> <p><a href="{{ url_for('index') }}">go somewhere nice</a>
{% endblock %} {% endblock %}
Further Examples Further Examples
```````````````` ````````````````
The above examples wouldn't actually be an improvement on the default The above examples wouldn't actually be an improvement on the default
exception pages. We can create a custom 500.html template like this: exception pages. We can create a custom 500.html template like this:
.. sourcecode:: html+jinja .. code-block:: html+jinja
{% extends "layout.html" %} {% extends "layout.html" %}
{% block title %}Internal Server Error{% endblock %} {% block title %}Internal Server Error{% endblock %}
@ -383,12 +397,10 @@ It can be implemented by rendering the template on "500 Internal Server Error":
# note that we set the 500 status explicitly # note that we set the 500 status explicitly
return render_template('500.html'), 500 return render_template('500.html'), 500
When using :doc:`/patterns/appfactories`: When using :doc:`/patterns/appfactories`:
.. code-block:: python .. code-block:: python
from flask import Flask, render_template from flask import Flask, render_template
def internal_server_error(e): def internal_server_error(e):
@ -399,7 +411,6 @@ When using :doc:`/patterns/appfactories`:
app.register_error_handler(500, internal_server_error) app.register_error_handler(500, internal_server_error)
return app return app
When using :doc:`/blueprints`: When using :doc:`/blueprints`:
.. code-block:: python .. code-block:: python
@ -416,20 +427,22 @@ When using :doc:`/blueprints`:
# or with register_error_handler # or with register_error_handler
blog.register_error_handler(500, internal_server_error) blog.register_error_handler(500, internal_server_error)
Blueprint Error Handling
````````````````````````
In blueprints, error handlers will work as expected. However, there is a caveat Blueprint Error Handlers
concerning handlers for 404 and 405 exceptions. These error handlers are only ------------------------
invoked from an appropriate ``raise`` statement or a call to ``abort`` in another
of the blueprint's view functions; they are not invoked by, e.g., an invalid URL In :doc:`/blueprints`, most error handlers will work as expected.
access. However, there is a caveat concerning handlers for 404 and 405
exceptions. These error handlers are only invoked from an appropriate
``raise`` statement or a call to ``abort`` in another of the blueprint's
view functions; they are not invoked by, e.g., an invalid URL access.
This is because the blueprint does not "own" a certain URL space, so This is because the blueprint does not "own" a certain URL space, so
the application instance has no way of knowing which blueprint error handler it the application instance has no way of knowing which blueprint error
should run if given an invalid URL. If you would like to execute different handler it should run if given an invalid URL. If you would like to
handling strategies for these errors based on URL prefixes, they may be defined execute different handling strategies for these errors based on URL
at the application level using the ``request`` proxy object: prefixes, they may be defined at the application level using the
``request`` proxy object.
.. code-block:: python .. code-block:: python
@ -447,7 +460,6 @@ at the application level using the ``request`` proxy object:
# otherwise we return our generic site-wide 404 page # otherwise we return our generic site-wide 404 page
return render_template("404.html"), 404 return render_template("404.html"), 404
@app.errorhandler(405) @app.errorhandler(405)
def method_not_allowed(e): def method_not_allowed(e):
# if a request has the wrong method to our API # if a request has the wrong method to our API
@ -459,11 +471,8 @@ at the application level using the ``request`` proxy object:
return render_template("405.html"), 405 return render_template("405.html"), 405
Returning API Errors as JSON
For more information on Blueprint Error Handling see :ref:`my-blueprint-error-label`. ----------------------------
Returning API errors as JSON
````````````````````````````
When building APIs in Flask, some developers realise that the built-in When building APIs in Flask, some developers realise that the built-in
exceptions are not expressive enough for APIs and that the content type of exceptions are not expressive enough for APIs and that the content type of
@ -535,11 +544,11 @@ This is a simple example:
return jsonify(user.to_dict()) return jsonify(user.to_dict())
A view can now raise that exception with an error message. Additionally A view can now raise that exception with an error message. Additionally
some extra payload can be provided as a dictionary through the `payload` some extra payload can be provided as a dictionary through the `payload`
parameter. parameter.
Logging Logging
------- -------