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())