Author: mtredinnick
Date: 2007-02-16 22:59:49 -0600 (Fri, 16 Feb 2007)
New Revision: 4534
Modified:
django/trunk/docs/request_response.txt
Log:
Fixed #2906 -- Added documentation about HTTP error code returns and the
default 404 and 500 code error handlers. Based on a patch from Marc Fargas.
Modified: django/trunk/docs/request_response.txt
===================================================================
--- django/trunk/docs/request_response.txt 2007-02-17 01:38:03 UTC (rev
4533)
+++ django/trunk/docs/request_response.txt 2007-02-17 04:59:49 UTC (rev
4534)
@@ -432,3 +432,77 @@
``HttpResponseServerError``
Acts just like ``HttpResponse`` but uses a 500 status code.
+
+Returning Errors
+================
+
+Returning HTTP error codes in Django is easy; there are 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.
+
+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::
+
+ from django.http import Http404
+ # ...
+ def detail(request, poll_id):
+ try:
+ p = Poll.objects.get(pk=poll_id)
+ except Poll.DoesNotExist:
+ raise Http404
+ return render_to_response('polls/detail.html', {'poll': p})
+
+In order to use the ``Http404`` exception to its fullest, you should create a
+template that is displayed when a 404 error is raised. This template should be
+called ``404.html`` and located in the top level of your template tree.
+
+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.
+
+You normally won't have to bother with writing 404 views. By default, URLconfs
+contain the following line::
+
+ from django.conf.urls.defaults import *
+
+That takes care of setting ``handler404`` in the current module. As you can see
+in ``django/conf/urls/defaults.py``, ``handler404`` is set to
+``'django.views.defaults.page_not_found'`` by default.
+
+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.
--~--~---------~--~----~------------~-------~--~----~
You received this message because you are subscribed to the Google Groups
"Django updates" group.
To post to this group, send email to [email protected]
To unsubscribe from this group, send email to [EMAIL PROTECTED]
For more options, visit this group at
http://groups.google.com/group/django-updates?hl=en
-~----------~----~----~----~------~----~------~--~---
