1.. _guide.response:
2
3Building a Response
4===================
5The request handler instance builds the response using its response property.
6This is initialized to an empty `WebOb`_ ``Response`` object by the
7application.
8
9The response object's acts as a file-like object that can be used for
10writing the body of the response::
11
12    class MyHandler(webapp2.RequestHandler):
13        def get(self):
14            self.response.write("<html><body><p>Hi there!</p></body></html>")
15
16The response buffers all output in memory, then sends the final output when
17the handler exits. webapp2 does not support streaming data to the client.
18
19The ``clear()`` method erases the contents of the output buffer, leaving it
20empty.
21
22If the data written to the output stream is a Unicode value, or if the
23response includes a ``Content-Type`` header that ends with ``; charset=utf-8``,
24webapp2 encodes the output as UTF-8. By default, the ``Content-Type`` header
25is ``text/html; charset=utf-8``, including the encoding behavior. If the
26``Content-Type`` is changed to have a different charset, webapp2 assumes the
27output is a byte string to be sent verbatim.
28
29.. warning:
30   The ``status`` attribute from a response is the status code plus message,
31   e.g., '200 OK'. This is different from webapp, which has the status code
32   (an integer) stored in ``status``. In webapp2, the status code is stored
33   in the ``status_int`` attribute, as in WebOb.
34
35
36.. _guide.response.setting-cookies:
37
38Setting cookies
39---------------
40Cookies are set in the response object. The methods to handle cookies are:
41
42set_cookie(key, value='', max_age=None, path='/', domain=None, secure=None, httponly=False, comment=None, expires=None, overwrite=False)
43  Sets a cookie.
44
45delete_cookie(key, path='/', domain=None)
46  Deletes a cookie previously set in the client.
47
48unset_cookie(key)
49  Unsets a cookie previously set in the response object. Note that this
50  doesn't delete the cookie from clients, only from the response.
51
52For example::
53
54    # Saves a cookie in the client.
55    response.set_cookie('some_key', 'value', max_age=360, path='/',
56                        domain='example.org', secure=True)
57
58    # Deletes a cookie previously set in the client.
59    response.delete_cookie('bad_cookie')
60
61    # Cancels a cookie previously set in the response.
62    response.unset_cookie('some_key')
63
64Only the ``key`` parameter is required. The parameters are:
65
66key
67  Cookie name.
68value
69  Cookie value.
70expires
71  An expiration date. Must be a :py:mod:`datetime`.datetime object. Use this
72  instead of max_age since the former is not supported by Internet Explorer.
73max_age
74  Cookie max age in seconds.
75path
76  URI path in which the cookie is valid.
77domain
78  URI domain in which the cookie is valid.
79secure
80  If True, the cookie is only available via HTTPS.
81httponly
82  Disallow JavaScript to access the cookie.
83comment
84  Defines a cookie comment.
85overwrite
86  If true, overwrites previously set (and not yet sent to the client) cookies
87  with the same name.
88
89.. seealso::
90   :ref:`How to read cookies from the request object <guide.request.cookies>`
91
92Common Response attributes
93--------------------------
94status
95  Status code plus message, e.g., '404 Not Found'. The status can be set
96  passing an ``int``, e.g., ``request.status = 404``, or including the message,
97  e.g., ``request.status = '404 Not Found'``.
98status_int
99  Status code as an ``int``, e.g., 404.
100status_message
101  Status message, e.g., 'Not Found'.
102body
103  The contents of the response, as a string.
104unicode_body
105  The contents of the response, as a unicode.
106headers
107  A dictionary-like object with headers. Keys are case-insensitive. It supports
108  multiple values for a key, but you must use
109  ``response.headers.add(key, value)`` to add keys. To get all values, use
110  ``response.headers.getall(key)``.
111headerlist
112  List of headers, as a list of tuples ``(header_name, value)``.
113charset
114  Character encoding.
115content_type
116  'Content-Type' value from the headers, e.g., ``'text/html'``.
117content_type_params
118  Dictionary of extra Content-type parameters, e.g., ``{'charset': 'utf8'}``.
119location
120  'Location' header variable, used for redirects.
121etag
122  'ETag' header variable. You can automatically generate an etag based on the
123  response body calling ``response.md5_etag()``.
124
125
126Learn more about WebOb
127----------------------
128WebOb is an open source third-party library. See the `WebOb`_ documentation
129for a detailed API reference and examples.
130
131
132.. _WebOb: http://docs.webob.org/
133