Ticket #6181: http-view-decorators.diff

docs/index.txt

@@ -93 +93 @@
       :doc:`View functions <topics/http/views>` |
       :doc:`Shortcuts <topics/http/shortcuts>`
 
-    * **Reference:**  :doc:`Request/response objects <ref/request-response>`
+    * **HTTP:**
+      :doc:`Request/response objects <ref/request-response>` |
+      :doc:`Decorators <topics/http/decorators>`
 
     * **File uploads:**
       :doc:`Overview <topics/http/file-uploads>` |

new file docs/topics/http/decorators.txt

@@ +1 @@
+===============
+View Decorators
+===============
+
+.. module:: django.views.decorators.http
+
+The decorators in the ``django.views.decorators.http`` module can be applied
+to views to process certain HTTP headers.
+
+
+
+``require_http_methods``
+========================
+
+.. function:: require_http_methods(request_method_list)
+
+This decorator to make a view only accept particular request methods.
+Usage::
+    from django.views.decorators.http import require_http_methods
+
+    @require_http_methods(["GET", "POST"])
+    def my_view(request):
+        # I can assume now that only GET or POST requests make it this far
+        # ...
+
+Note that request methods should be in uppercase.
+
+Two shorcuts are defined, ``require_GET`` and ``require_POST``, which limit
+the request method to GET and POST respectively.
+
+``condition``
+=============
+
+.. function:: condition(etag_func=None, last_modified_func=None)
+
+The ``condition`` decorator support conditional retrieval for a view
+function.
+
+The parameters are callables to compute the ETag and last modified time for
+the requested resource, respectively. The callables are passed the same
+parameters as the view itself. The Etag function should return a string (or
+None if the resource doesn't exist), whilst the last_modified function
+should return a datetime object (or None if the resource doesn't exist).
+
+If both parameters are provided, all the preconditions must be met before
+the view is processed.
+
+This decorator will either pass control to the wrapped view function or
+return an HTTP 304 response (unmodified) or 412 response (preconditions
+failed), depending upon the request method.
+
+Any behavior marked as "undefined" in the HTTP spec (e.g. ``If-none-match``
+plus ``If-modified-since`` headers) will result in the view function being
+called.
+
+Two shortcuts are defined for the common cases.
+
+.. function:: etag(etag_func)
+
+This decorator provides only an etag function.
+
+.. function:: last_modified(last_modified_func)
+
+This decorator provides only a last-modified function.

docs/topics/http/index.txt

@@ -10 +10 @@
    views
    file-uploads
    shortcuts
+   decorators
    generic-views
    middleware
    sessions