Django

Code

Changeset 4538

Show
Ignore:
Timestamp:
02/17/07 22:42:15 (2 years ago)
Author:
adrian
Message:

Copy edited new docs in docs/request_response.txt from [4534]

Files:

Legend:

Unmodified
Added
Removed
Modified
Copied
Moved

  • django/trunk/docs/request_response.txt

    r4534 r4538  
    434434    Acts just like ``HttpResponse`` but uses a 500 status code. 
    435435 
    436 Returning Errors 
     436Returning errors 
    437437================ 
    438438 
    439 Returning HTTP error codes in Django is easy; there are the 
     439Returning HTTP error codes in Django is easy. We've already mentioned the 
    440440``HttpResponseNotFound``, ``HttpResponseForbidden``, 
    441 ``HttpResponseServerError``, etc. subclasses mentioned above which, when 
    442 returned by a view, will make the Web server return the corresponding error 
    443 codes (404, 403, 500, ...) and HTTP headers. 
     441``HttpResponseServerError``, etc., subclasses; just return an instance of one 
     442of those subclasses instead of a normal ``HttpResponse`` in order to signify 
     443an error. For example:: 
     444 
     445    def my_view(request): 
     446        # ... 
     447        if foo: 
     448            return HttpResponseNotFound('<h1>Page not found</h1>') 
     449        else: 
     450            return HttpResponse('<h1>Page was found</h1>') 
     451 
     452Because 404 errors are by far the most common HTTP error, there's an easier way 
     453to handle those errors. 
    444454 
    445455The Http404 exception 
    446456--------------------- 
    447 When you return an error such as ``HttpResponseNotFound``, you are responsible 
    448 for returning the error page and everything yourself. Since this extra 
    449 information will normally be fairly uniform across your site and because you 
    450 often want to bail out of the middle of a view with a quick "content not 
    451 found" error, Django provides the ``Http404`` exception. This exception is 
    452 caught by Django and results in the standard error page for your application 
    453 being returned along with a 404 error code (although this behavior can be 
    454 customised, as described below). 
    455  
    456 Using this exception in your code would look something like:: 
     457 
     458When you return an error such as ``HttpResponseNotFound``, you're responsible 
     459for defining the HTML of the resulting error page:: 
     460 
     461    return HttpResponseNotFound('<h1>Page not found</h1>') 
     462 
     463For convenience, and because it's a good idea to have a consistent 404 error page 
     464across your site, Django provides an ``Http404`` exception. If you raise 
     465``Http404`` at any point in a view function, Django will catch it and return the 
     466standard error page for your application, along with an HTTP error code 404. 
     467 
     468Example usage:: 
    457469 
    458470    from django.http import Http404 
    459     # ... 
     471 
    460472    def detail(request, poll_id): 
    461473        try: 
    …… 
    473485 
    474486The 404 (page not found) view 
    475 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ 
    476  
    477 When you raise the ``Http404`` exception, Django will load a special view 
    478 devoted to handling 404 errors. It finds it by looking for the variable 
    479 ``handler404``, which is a string in Python dotted syntax -- the same format 
    480 the normal URLconf callbacks use. A 404 view itself has nothing special: It's 
    481 just a normal view. 
    482  
    483 You normally won't have to bother with writing 404 views. By default, URLconfs 
    484 contain the following line:: 
     487~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ 
     488 
     489When you raise an ``Http404`` exception, Django loads a special view devoted 
     490to handling 404 errors. By default, it's the view 
     491``django.views.defaults.page_not_found``, which loads and renders the template 
     492``404.html``. 
     493 
     494This means you need to define a ``404.html`` template in your root template 
     495directory. This template will be used for all 404 errors. 
     496 
     497This ``page_not_found`` view should suffice for 99% of Web applications, but if 
     498you want to override the 404 view, you can specify ``handler404`` in your 
     499URLconf, like so:: 
     500 
     501    handler404 = 'mysite.views.my_custom_404_view' 
     502 
     503Behind the scenes, Django determines the 404 view by looking for ``handler404``. 
     504By default, URLconfs contain the following line:: 
    485505 
    486506    from django.conf.urls.defaults import * 
    …… 
    494514    * The 404 view is also called if Django doesn't find a match after checking 
    495515      every regular expression in the URLconf. 
     516 
    496517    * If you don't define your own 404 view -- and simply use the default, 
    497518      which is recommended -- you still have one obligation: To create a 
    498519      ``404.html`` template in the root of your template directory. The default 
    499520      404 view will use that template for all 404 errors. 
     521 
    500522    * If ``DEBUG`` is set to ``True`` (in your settings module) then your 404 
    501523      view will never be used, and the traceback will be displayed instead. 
    502524 
    503525The 500 (server error) view 
    504 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~ 
    505  
    506 URLconfs may also define a ``handler500``, which points to a view to call in 
    507 case of server errors. Server errors happen when you have runtime errors in 
    508 view code. 
     526~~~~~~~~~~~~~~~~~~~~~~~~~~~ 
     527 
     528Similarly, Django executes special-case behavior in the case of runtime errors 
     529in view code. If a view results in an exception, Django will, by default, call 
     530the view ``django.views.defaults.server_error``, which loads and renders the 
     531template ``500.html``. 
     532 
     533This means you need to define a ``500.html`` template in your root template 
     534directory. This template will be used for all server errors. 
     535 
     536This ``server_error`` view should suffice for 99% of Web applications, but if 
     537you want to override the view, you can specify ``handler500`` in your 
     538URLconf, like so:: 
     539 
     540    handler500 = 'mysite.views.my_custom_error_view' 
     541 
     542Behind the scenes, Django determines the error view by looking for ``handler500``. 
     543By default, URLconfs contain the following line:: 
     544 
     545    from django.conf.urls.defaults import * 
     546 
     547That takes care of setting ``handler500`` in the current module. As you can see 
     548in ``django/conf/urls/defaults.py``, ``handler500`` is set to 
     549``'django.views.defaults.server_error'`` by default.