Request object ¶

The Request object contains all the information transmitted by the client of the application. You will retrieve from it GET and POST values, uploaded files, cookies and header information and more. All these things are so common that you will be very used to it.

The Request object is available inside handlers as self.request. It is an instance of werkzeug.Request.

Let's take a look at the most common values you will want to retrieve from the Request.

GET¶

GET values are available in request.args. It is a MultiDict object (a dictionary that can have multiple values for the same key). To get the first value for a given key, you use get(). To get all values for a given key, you use getlist(). For example:

For the URL http://www.tipfy.org/wiki/guide/request/?version=1&version=2:

>>> 
>>> request.args.get('version')
>>> u'1'
>>> request.args.getlist('version')
>>> [u'1', u'2']
>>>

You can also get using a default value as fall back, like in a dict:

>>> 
>>> request.args.get('section', 0)
>>> u'0'
>>>

Or convert the type returned (normally it will return unicode). Useful if you are expecting an int:

>>> 
>>> request.args.get('version', type=int)
>>> 1
>>> request.args.get('section', 0, type=int)
>>> 0
>>>

For the URL http://www.tipfy.org/wiki/guide/request/?version=foo (here the type conversion fails, so it will return None):
```
>>> 
>>> request.args.get('version', type=int)
>>> None
>>> 
```

Here's a summary of the most commonly used methods from request.args:

get(key, default=None, type=None): Return one value for a given key. If multiple values are set for that key, return the first one. If default is provided, return it if the key is not set. If type is set, use it to cast the returned value. If a ValueError exception is raised by this callable, return the default value.
getlist(key, type=None): Return the list of items for a given key. If type is set, use it to cast the returned values. If a ValueError exception is raised by this callable, the value will be removed from the list.
keys(): Returns a list with all keys set in GET.
values(): Returns a list of the first value on every key's value list.
items(multi=False): Return a list of (key, value) pairs. If multi is set to True the list returned will have a pair for each value of each key. Otherwise it will only contain pairs for the first value of each key.

POST¶

POST values are available in request.form. It is also a MultiDict object like request.args. To get the first value for a given key you use get() and to get all values for a given key you use getlist().

Check the methods above that we use to retrieve GET values. They are all available in request.form, but to retrieve POST values. For example:

>>> request.form.get('body')
>>> request.form.getlist('my_checkboxes')

And so on.

FILES¶

Uploaded files are available in request.files. This is a MultiDict object (a dictionary that can have multiple values for the same key). Each key is the name from a <input type="file" name="">. Each value is a werkzeug.FileStorage object.

So for example, for the form:

<form method="post" action="" enctype="multipart/form-data">
    <input type="file" name="image_upload">
    <input type="submit" name="submit" value="submit">
</form>

...you retrieve the image_upload file data directly from request.files. If no file was selected for upload it:

image = request.files.get('image_upload')

if image:
    # User uploaded a file. Process it.

    # This is the filename as uploaded by the user.
    filename = image.filename

    # This is the file data to process and/or save.
    filedata = image.read()
else:
    # User didn't select any file. Show an error if it is required.
    pass

A file returned from request.files is a werkzeug.FileStorage. These are probably the variables you will want to retrieve from it, as showed in the example above:

filename: The file name as uploaded by the user (for example, 'logo.png').
read(): Reads and returns the contents of the uploaded file.

Cookies¶

Cookie values are available in request.cookies. It is a dictionary, so to retrieve a specific cookie you do:

locale = request.cookies.get('locale')

Or you can pass a default value to be returned if the cookie is not set:

locale = request.cookies.get('locale', 'en_US')

Nothing special here; this is pretty straightforward.

Headers¶

Header values are available in request.headers. You can retrieve any environ headers from it, as in a dictionary. For example:

content_type = request.headers.get('content-type')

Other variables¶

Here are some other commonly used Request attributes:

request.base_url: Full requested URL excluding the querystring.
request.charset: The charset for the request. Default is 'utf-8'.
request.host: The host including the port if available (for example: 'localhost' or 'localhost:8080').
request.host_url: Same as request.host but including the scheme (for example: 'http://localhost/' or 'http://localhost:8080/').
request.is_secure: True if the request is made using https.
request.is_xhr: True if the request was triggered via a JavaScript XMLHttpRequest (aka AJAX). This only works with libraries that support the X-Requested-With header and set it to XMLHttpRequest. Libraries that do that are prototype, jQuery and Mochikit and probably some more.
request.method: The HTTP method (for example: 'GET', 'POST' or 'HEAD').
request.path: Requested path as unicode.
request.query_string: The URL parameters as raw bytestring.
request.remote_addr: The remote address (IP) of the client.
request.url: Full requested URL.

And here are some examples:

For the URL 'http://www.tipfy.org/wiki/guide/?version=1&section=0':

>>> 
>>> request.base_url
>>> 'http://www.tipfy.org/wiki/guide/'
>>> request.host
>>> 'www.tipfy.org'
>>> request.host_url
>>> 'http://www.tipfy.org/'
>>> request.method
>>> 'GET'
>>> request.path
>>> '/wiki/guide/'
>>> request.query_string
>>> 'version=1&section=0'
>>> request.url
>>> 'http://www.tipfy.org/wiki/guide/?version=1&section=0'
>>>

What else?¶

These are the most common values you may need from a Request object. If you are missing something, check Werkzeug's documentation or dive into the code.

Version: latest
Edited by moraes on 4/8/11 12:29 AM
Save on Delicious | Submit to Reddit
History
Edit