Chris Craik | b2cbf15 | 2015-07-28 16:26:29 -0700 | [diff] [blame^] | 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 |