1 .. _guide.request: 2 3 Request data 4 ============ 5 The request handler instance can access the request data using its ``request`` 6 property. This is initialized to a populated `WebOb`_ ``Request`` object by 7 the application. 8 9 The request object provides a ``get()`` method that returns values for 10 arguments parsed from the query and from POST data. The method takes the 11 argument name as its first parameter. For example:: 12 13 class MyHandler(webapp2.RequestHandler): 14 def post(self): 15 name = self.request.get('name') 16 17 By default, ``get()`` returns the empty string (``''``) if the requested 18 argument is not in the request. If the parameter ``default_value`` is 19 specified, ``get()`` returns the value of that parameter instead of the empty 20 string if the argument is not present. 21 22 If the argument appears more than once in a request, by default ``get()`` 23 returns the first occurrence. To get all occurrences of an argument that might 24 appear more than once as a list (possibly empty), give ``get()`` the argument 25 ``allow_multiple=True``:: 26 27 # <input name="name" type="text" /> 28 name = self.request.get("name") 29 30 # <input name="subscribe" type="checkbox" value="yes" /> 31 subscribe_to_newsletter = self.request.get("subscribe", default_value="no") 32 33 # <select name="favorite_foods" multiple="true">...</select> 34 favorite_foods = self.request.get("favorite_foods", allow_multiple=True) 35 36 # for food in favorite_foods: 37 # ... 38 39 For requests with body content that is not a set of CGI parameters, such as 40 the body of an HTTP PUT request, the request object provides the attributes 41 ``body`` and ``body_file``: ``body`` is the body content as a byte string and 42 ``body_file`` provides a file-like interface to the same data:: 43 44 uploaded_file = self.request.body 45 46 47 GET data 48 -------- 49 Query string variables are available in ``request.GET``. 50 51 ``.GET`` is a `MultiDict`_: it is like a dictionary but the same key can have 52 multiple values. When you call ``.get(key)`` for a key with multiple values, 53 the last value is returned. To get all values for a key, use ``.getall(key)``. 54 Examples:: 55 56 request = Request.blank('/test?check=a&check=b&name=Bob') 57 58 # The whole MultiDict: 59 # GET([('check', 'a'), ('check', 'b'), ('name', 'Bob')]) 60 get_values = request.GET 61 62 # The last value for a key: 'b' 63 check_value = request.GET['check'] 64 65 # All values for a key: ['a', 'b'] 66 check_values = request.GET.getall('check') 67 68 # An iterable with alll items in the MultiDict: 69 # [('check', 'a'), ('check', 'b'), ('name', 'Bob')] 70 request.GET.items() 71 72 The name ``GET`` is a bit misleading, but has historical reasons: 73 ``request.GET`` is not only available when the HTTP method is GET. It is 74 available for any request with query strings in the URI, for any HTTP method: 75 GET, POST, PUT etc. 76 77 78 POST data 79 --------- 80 Variables url encoded in the body of a request (generally a POST form submitted 81 using the ``application/x-www-form-urlencoded`` media type) are available in 82 ``request.POST``. 83 84 It is also a `MultiDict`_ and can be accessed in the same way as ``.GET``. 85 Examples:: 86 87 request = Request.blank('/') 88 request.method = 'POST' 89 request.body = 'check=a&check=b&name=Bob' 90 91 # The whole MultiDict: 92 # POST([('check', 'a'), ('check', 'b'), ('name', 'Bob')]) 93 post_values = request.POST 94 95 # The last value for a key: 'b' 96 check_value = request.POST['check'] 97 98 # All values for a key: ['a', 'b'] 99 check_values = request.POST.getall('check') 100 101 # An iterable with alll items in the MultiDict: 102 # [('check', 'a'), ('check', 'b'), ('name', 'Bob')] 103 request.POST.items() 104 105 Like ``GET``, the name ``POST`` is a somewjat misleading, but has historical 106 reasons: they are also available when the HTTP method is PUT, and not only 107 POST. 108 109 110 GET + POST data 111 --------------- 112 ``request.params`` combines the variables from ``GET`` and ``POST``. It can be 113 used when you don't care where the variable comes from. 114 115 116 Files 117 ----- 118 Uploaded files are available as ``cgi.FieldStorage`` (see the :py:mod:`cgi` 119 module) instances directly in ``request.POST``. 120 121 122 .. _guide.request.cookies: 123 124 Cookies 125 ------- 126 Cookies can be accessed in ``request.cookies``. It is a simple dictionary:: 127 128 request = Request.blank('/') 129 request.headers['Cookie'] = 'test=value' 130 131 # A value: 'value' 132 cookie_value = request.cookies.get('test') 133 134 .. seealso:: 135 :ref:`How to set cookies using the response object <guide.response.setting-cookies>` 136 137 138 Common Request attributes 139 ------------------------- 140 body 141 A file-like object that gives the body of the request. 142 content_type 143 Content-type of the request body. 144 method 145 The HTTP method, e.g., 'GET' or 'POST'. 146 url 147 Full URI, e.g., ``'http://localhost/blog/article?id=1'``. 148 scheme 149 URI scheme, e.g., 'http' or 'https'. 150 host 151 URI host, e.g., ``'localhost:80'``. 152 host_url 153 URI host including scheme, e.g., ``'http://localhost'``. 154 path_url 155 URI host including scheme and path, e.g., ``'http://localhost/blog/article'``. 156 path 157 URI path, e.g., ``'/blog/article'``. 158 path_qs 159 URI path including the query string, e.g., ``'/blog/article?id=1'``. 160 query_string 161 Query string, e.g., ``id=1``. 162 headers 163 A dictionary like object with request headers. Keys are case-insensitive. 164 GET 165 A dictionary-like object with variables from the query string, as unicode. 166 POST 167 A dictionary-like object with variables from a POST form, as unicode. 168 params 169 A dictionary-like object combining the variables GET and POST. 170 cookies 171 A dictionary-like object with cookie values. 172 173 174 Extra attributes 175 ---------------- 176 The parameters from the matched :class:`webapp2.Route` are set as attributes 177 of the request object. They are ``request.route_args``, for positional 178 arguments, and ``request.route_kwargs``, for keyword arguments. The matched 179 route object is available as ``request.route``. 180 181 A reference to the active WSGI application is also set as an attribute of the 182 request. You can access it in ``request.app``. 183 184 185 Getting the current request 186 --------------------------- 187 The active ``Request`` instance can be accessed during a request using the 188 function :func:`webapp2.get_request`. 189 190 191 .. _guide.request.registry: 192 193 Registry 194 -------- 195 A simple dictionary is available in the request object to register instances 196 that are shared during a request: it is the :attr:`webapp2.Request.registry` 197 attribute. 198 199 A registry dictionary is also available in the 200 :ref:`WSGI application object <guide.app.registry>`, to store objects shared 201 across requests. 202 203 204 Learn more about WebOb 205 ---------------------- 206 WebOb is an open source third-party library. See the `WebOb`_ documentation 207 for a detailed API reference and examples. 208 209 210 .. _WebOb: http://docs.webob.org/ 211 .. _MultiDict: http://pythonpaste.org/webob/class-webob.multidict.MultiDict.html 212
