Commits

Anonymous committed f6bc120

Adding documentation on custom headers
Updated documentation on _cprequest.Response.header_list to clarify behavior.

  • Participants
  • Parent commits d5e53c3

Comments (0)

Files changed (2)

cherrypy/_cprequest.py

     header_list = []
     header_list__doc = """
     A list of the HTTP response headers as (name, value) tuples.
-    In general, you should use response.headers (a dict) instead."""
+    In general, you should use response.headers (a dict) instead. This
+    attribute is generated from response.headers and is not valid until
+    after the finalize phase."""
     
     headers = httputil.HeaderMap()
     headers__doc = """

sphinx/source/progguide/customheaders.rst

+
+Custom Response Headers
+***********************
+
+Although the ``cherrypy.response.headers`` is usually adequate for
+supplying headers in a CherryPy response, it is sometimes desirable for
+the server application to customize the order of the resultant headers
+or provide multiple headers with duplicate keys. This section describes
+how one can accomplish these tasks within the CherryPy framework.
+
+Process
+=======
+
+The CherryPy Response object maintains a dictionary of headers until the
+finalize phase, after which the headers in the dictionary are converted
+into a list of (name, value) tuples. See
+``cherrypy._cprequest.Response`` for details.
+
+Therefore, since a dictionary discards order and duplicate keys,
+customizing the order or duplicity of keys must occur after the finalize
+phase.
+
+This end can be effected using a tool bound to the ``on_end_resource``
+hook.
+
+Multiple Headers
+================
+
+The following example illustrates the creation of a multiheaders tool to
+deliver multiple headers with the same key in the response.
+
+::
+
+    #python
+    import cherrypy
+
+    def multi_headers():
+        cherrypy.response.header_list.extend(cherrypy.response.multiheaders)
+
+    cherrypy.tools.multiheaders = cherrypy.Tool('on_end_resource', multi_headers)
+
+    class Root(object):
+        @cherrypy.expose
+        @cherrypy.tools.multiheaders()
+        def index(self):
+            cherrypy.response.multiheaders = [('foo', '1'), ('foo', '2')]
+            return "Hello"
+
+    cherrypy.quickstart(Root())
+
+Header Order
+============
+
+The following example illustrates the creation of a firstheaders tool to
+deliver headers in a specified order (at the beginning) in the response.
+
+::
+
+    #python
+    import cherrypy
+
+    def first_headers():
+        cherrypy.response.header_list[:0] = cherrypy.response.first_headers
+
+    cherrypy.tools.firstheaders = cherrypy.Tool('on_end_resource', first_headers)
+
+    class Root(object):
+        @cherrypy.expose
+        @cherrypy.tools.firstheaders()
+        def index(self):
+            cherrypy.response.first_headers = [('foo', '1'), ('foo', '2')]
+            return "Hello"
+
+    cherrypy.quickstart(Root())