diff --git a/docs/request_response.txt b/docs/request_response.txt index e05b4fc8d8..6dfe78a686 100644 --- a/docs/request_response.txt +++ b/docs/request_response.txt @@ -433,30 +433,42 @@ types of HTTP responses. Like ``HttpResponse``, these subclasses live in ``HttpResponseServerError`` Acts just like ``HttpResponse`` but uses a 500 status code. -Returning Errors +Returning errors ================ -Returning HTTP error codes in Django is easy; there are the +Returning HTTP error codes in Django is easy. We've already mentioned the ``HttpResponseNotFound``, ``HttpResponseForbidden``, -``HttpResponseServerError``, etc. subclasses mentioned above which, when -returned by a view, will make the Web server return the corresponding error -codes (404, 403, 500, ...) and HTTP headers. +``HttpResponseServerError``, etc., subclasses; just return an instance of one +of those subclasses instead of a normal ``HttpResponse`` in order to signify +an error. For example:: + + def my_view(request): + # ... + if foo: + return HttpResponseNotFound('

Page not found

') + else: + return HttpResponse('

Page was found

') + +Because 404 errors are by far the most common HTTP error, there's an easier way +to handle those errors. The Http404 exception --------------------- -When you return an error such as ``HttpResponseNotFound``, you are responsible -for returning the error page and everything yourself. Since this extra -information will normally be fairly uniform across your site and because you -often want to bail out of the middle of a view with a quick "content not -found" error, Django provides the ``Http404`` exception. This exception is -caught by Django and results in the standard error page for your application -being returned along with a 404 error code (although this behavior can be -customised, as described below). -Using this exception in your code would look something like:: +When you return an error such as ``HttpResponseNotFound``, you're responsible +for defining the HTML of the resulting error page:: + + return HttpResponseNotFound('

Page not found

') + +For convenience, and because it's a good idea to have a consistent 404 error page +across your site, Django provides an ``Http404`` exception. If you raise +``Http404`` at any point in a view function, Django will catch it and return the +standard error page for your application, along with an HTTP error code 404. + +Example usage:: from django.http import Http404 - # ... + def detail(request, poll_id): try: p = Poll.objects.get(pk=poll_id) @@ -472,16 +484,24 @@ Customing error views --------------------- The 404 (page not found) view -~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ -When you raise the ``Http404`` exception, Django will load a special view -devoted to handling 404 errors. It finds it by looking for the variable -``handler404``, which is a string in Python dotted syntax -- the same format -the normal URLconf callbacks use. A 404 view itself has nothing special: It's -just a normal view. +When you raise an ``Http404`` exception, Django loads a special view devoted +to handling 404 errors. By default, it's the view +``django.views.defaults.page_not_found``, which loads and renders the template +``404.html``. -You normally won't have to bother with writing 404 views. By default, URLconfs -contain the following line:: +This means you need to define a ``404.html`` template in your root template +directory. This template will be used for all 404 errors. + +This ``page_not_found`` view should suffice for 99% of Web applications, but if +you want to override the 404 view, you can specify ``handler404`` in your +URLconf, like so:: + + handler404 = 'mysite.views.my_custom_404_view' + +Behind the scenes, Django determines the 404 view by looking for ``handler404``. +By default, URLconfs contain the following line:: from django.conf.urls.defaults import * @@ -493,16 +513,37 @@ Three things to note about 404 views: * The 404 view is also called if Django doesn't find a match after checking every regular expression in the URLconf. + * If you don't define your own 404 view -- and simply use the default, which is recommended -- you still have one obligation: To create a ``404.html`` template in the root of your template directory. The default 404 view will use that template for all 404 errors. + * If ``DEBUG`` is set to ``True`` (in your settings module) then your 404 view will never be used, and the traceback will be displayed instead. The 500 (server error) view -~~~~~~~~~~~~~~~~~~~~~~~~~~~~ +~~~~~~~~~~~~~~~~~~~~~~~~~~~ -URLconfs may also define a ``handler500``, which points to a view to call in -case of server errors. Server errors happen when you have runtime errors in -view code. +Similarly, Django executes special-case behavior in the case of runtime errors +in view code. If a view results in an exception, Django will, by default, call +the view ``django.views.defaults.server_error``, which loads and renders the +template ``500.html``. + +This means you need to define a ``500.html`` template in your root template +directory. This template will be used for all server errors. + +This ``server_error`` view should suffice for 99% of Web applications, but if +you want to override the view, you can specify ``handler500`` in your +URLconf, like so:: + + handler500 = 'mysite.views.my_custom_error_view' + +Behind the scenes, Django determines the error view by looking for ``handler500``. +By default, URLconfs contain the following line:: + + from django.conf.urls.defaults import * + +That takes care of setting ``handler500`` in the current module. As you can see +in ``django/conf/urls/defaults.py``, ``handler500`` is set to +``'django.views.defaults.server_error'`` by default.