1 .. _guide.response: 2 3 Building a Response 4 =================== 5 The request handler instance builds the response using its response property. 6 This is initialized to an empty `WebOb`_ ``Response`` object by the 7 application. 8 9 The response object's acts as a file-like object that can be used for 10 writing 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 16 The response buffers all output in memory, then sends the final output when 17 the handler exits. webapp2 does not support streaming data to the client. 18 19 The ``clear()`` method erases the contents of the output buffer, leaving it 20 empty. 21 22 If the data written to the output stream is a Unicode value, or if the 23 response includes a ``Content-Type`` header that ends with ``; charset=utf-8``, 24 webapp2 encodes the output as UTF-8. By default, the ``Content-Type`` header 25 is ``text/html; charset=utf-8``, including the encoding behavior. If the 26 ``Content-Type`` is changed to have a different charset, webapp2 assumes the 27 output 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 38 Setting cookies 39 --------------- 40 Cookies are set in the response object. The methods to handle cookies are: 41 42 set_cookie(key, value='', max_age=None, path='/', domain=None, secure=None, httponly=False, comment=None, expires=None, overwrite=False) 43 Sets a cookie. 44 45 delete_cookie(key, path='/', domain=None) 46 Deletes a cookie previously set in the client. 47 48 unset_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 52 For 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 64 Only the ``key`` parameter is required. The parameters are: 65 66 key 67 Cookie name. 68 value 69 Cookie value. 70 expires 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. 73 max_age 74 Cookie max age in seconds. 75 path 76 URI path in which the cookie is valid. 77 domain 78 URI domain in which the cookie is valid. 79 secure 80 If True, the cookie is only available via HTTPS. 81 httponly 82 Disallow JavaScript to access the cookie. 83 comment 84 Defines a cookie comment. 85 overwrite 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 92 Common Response attributes 93 -------------------------- 94 status 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'``. 98 status_int 99 Status code as an ``int``, e.g., 404. 100 status_message 101 Status message, e.g., 'Not Found'. 102 body 103 The contents of the response, as a string. 104 unicode_body 105 The contents of the response, as a unicode. 106 headers 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)``. 111 headerlist 112 List of headers, as a list of tuples ``(header_name, value)``. 113 charset 114 Character encoding. 115 content_type 116 'Content-Type' value from the headers, e.g., ``'text/html'``. 117 content_type_params 118 Dictionary of extra Content-type parameters, e.g., ``{'charset': 'utf8'}``. 119 location 120 'Location' header variable, used for redirects. 121 etag 122 'ETag' header variable. You can automatically generate an etag based on the 123 response body calling ``response.md5_etag()``. 124 125 126 Learn more about WebOb 127 ---------------------- 128 WebOb is an open source third-party library. See the `WebOb`_ documentation 129 for a detailed API reference and examples. 130 131 132 .. _WebOb: http://docs.webob.org/ 133
