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