+
−WebOb Reference
+
−+++++++++++++++
+
−
+
−.. contents::
+
−
+
−.. comment:
+
−
+
−    >>> from dtopt import ELLIPSIS
+
−
+
−Introduction
+
−============
+
−
+
−This document covers all the details of the Request and Response
+
−objects.  It is written to be testable with `doctest
+
−<http://python.org/doc/current/lib/module-doctest.html>`_ -- this
+
−effects the flavor of the documentation, perhaps to its detriment.
+
−But it also means you can feel confident that the documentation is
+
−correct.
+
−
+
−This is a somewhat different approach to reference documentation
+
−compared to the extracted documentation for the `request
+
−<class-webob.Request.html>`_ and `response
+
−<class-webob.Response.html>`_.
+
−
+
−Request
+
−=======
+
−
+
−The primary object in WebOb is ``webob.Request``, a wrapper around a
+
−`WSGI environment <http://www.python.org/dev/peps/pep-0333/>`_.
+
−
+
−The basic way you create a request object is simple enough:
+
−
+
−.. code-block::
+
−
+
−   >>> from webob import Request
+
−   >>> environ = {}
+
−   >>> req = Request(environ)
+
−
+
−The request object *wraps* the environment; it has very little
+
−internal state of its own.  Instead attributes you access read and
+
−write to the environment dictionary.
+
−
+
−You don't have to understand the details of WSGI to use this library;
+
−this library handles those details for you.  You also don't have to
+
−use this exclusively of other libraries.  If those other libraries
+
−also keep their state in the environment, multiple wrappers can
+
−coexist.  Examples of libraries that can coexist include
+
−`paste.wsgiwrappers.Request
+
−<http://pythonpaste.org/class-paste.wsgiwrappers.WSGIRequest.html>`_
+
−(used by Pylons) and `yaro.Request
+
−<http://lukearno.com/projects/yaro/>`_.
+
−
+
−The WSGI environment has a number of required variables.  To make it
+
−easier to test and play around with, the ``Request`` class has a
+
−constructor that will fill in a minimal environment:
+
−
+
−.. code-block::
+
−
+
−   >>> req = Request.blank('/article?id=1')
+
−   >>> from pprint import pprint
+
−   >>> pprint(req.environ)
+
−   {'HTTP_HOST': 'localhost:80',
+
−    'PATH_INFO': '/article',
+
−    'QUERY_STRING': 'id=1',
+
−    'REQUEST_METHOD': 'GET',
+
−    'SCRIPT_NAME': '',
+
−    'SERVER_NAME': 'localhost',
+
−    'SERVER_PORT': '80',
+
−    'SERVER_PROTOCOL': 'HTTP/1.0',
+
−    'wsgi.errors': <open file '<stderr>', mode 'w' at ...>,
+
−    'wsgi.input': <cStringIO.StringI object at ...>,
+
−    'wsgi.multiprocess': False,
+
−    'wsgi.multithread': False,
+
−    'wsgi.run_once': False,
+
−    'wsgi.url_scheme': 'http',
+
−    'wsgi.version': (1, 0)}
+
−
+
−Request Body
+
−------------
+
−
+
−``req.body`` is a file-like object that gives the body of the request
+
−(e.g., a POST form, the body of a PUT, etc).  It's kind of boring to
+
−start, but you can set it to a string and that will be turned into a
+
−file-like object.  You can read the entire body with
+
−``req.body``.
+
−
+
−.. code-block:: 
+
−
+
−    >>> req.body_file
+
−    <cStringIO.StringI object at ...>
+
−    >>> req.body
+
−    ''
+
−    >>> req.body = 'test'
+
−    >>> req.body_file
+
−    <cStringIO.StringI object at ...>
+
−    >>> req.body
+
−    'test'
+
−
+
−Method & URL
+
−------------
+
−
+
−All the normal parts of a request are also accessible through the
+
−request object:
+
−
+
−.. code-block::
+
−
+
−    >>> req.method
+
−    'GET'
+
−    >>> req.scheme
+
−    'http'
+
−    >>> req.script_name  # The base of the URL
+
−    ''
+
−    >>> req.script_name = '/blog' # make it more interesting
+
−    >>> req.path_info    # The yet-to-be-consumed part of the URL
+
−    '/article'
+
−    >>> req.content_type # Content-Type of the request body
+
−    ''
+
−    >>> print req.remote_user  # The authenticated user (there is none set)
+
−    None
+
−    >>> print req.remote_addr  # The remote IP
+
−    None
+
−    >>> req.host
+
−    'localhost:80'
+
−    >>> req.host_url
+
−    'http://localhost'
+
−    >>> req.application_url
+
−    'http://localhost/blog'
+
−    >>> req.path_url
+
−    'http://localhost/blog/article'
+
−    >>> req.url
+
−    'http://localhost/blog/article?id=1'
+
−    >>> req.path
+
−    '/blog/article'
+
−    >>> req.path_qs
+
−    '/blog/article?id=1'
+
−    >>> req.query_string
+
−    'id=1'
+
−
+
−You can make new URLs:
+
−
+
−.. code-block::
+
−
+
−    >>> req.relative_url('archive')
+
−    'http://localhost/blog/archive'
+
−
+
−For parsing the URLs, it is often useful to deal with just the next
+
−path segment on PATH_INFO:
+
−
+
−.. code-block::
+
−
+
−    >>> req.path_info_peek() # Doesn't change request
+
−    'article'
+
−    >>> req.path_info_pop()  # Does change request!
+
−    'article'
+
−    >>> req.script_name
+
−    '/blog/article'
+
−    >>> req.path_info
+
−    ''
+
−
+
−Headers
+
−-------
+
−
+
−All request headers are available through a dictionary-like object
+
−``req.headers``.  Keys are case-insensitive.
+
−
+
−.. code-block::
+
−
+
−    >>> req.headers['content-type'] = 'application/x-www-urlencoded'
+
−    >>> req.headers
+
−    {'Content-Length': '4', 'Content-Type': 'application/x-www-urlencoded', 'Host': 'localhost:80'}
+
−    >>> req.environ['CONTENT_TYPE']
+
−    'application/x-www-urlencoded'
+
−
+
−Query & POST variables
+
−----------------------
+
−
+
−Requests can have variables in one of two locations: the query string
+
−(``?id=1``), or in the body of the request (generally a POST form).
+
−Note that even POST requests can have a query string, so both kinds of
+
−variables can exist at the same time.  Also, a variable can show up
+
−more than once, as in ``?check=a&check=b``.
+
−
+
−For these variables WebOb uses a `MultiDict
+
−<class-webob.multidict.MultiDict.html>`_, which is basically a
+
−dictionary wrapper on a list of key/value pairs.  It looks like a
+
−single-valued dictionary, but you can access all the values of a key
+
−with ``.getall(key)`` (which always returns a list, possibly an empty
+
−list).  You also get all key/value pairs when using ``.items()`` and
+
−all values with ``.values()``.
+
−
+
−Some examples:
+
−
+
−.. code-block::
+
−
+
−    >>> req = Request.blank('/test?check=a&check=b&name=Bob')
+
−    >>> req.GET
+
−    MultiDict([('check', 'a'), ('check', 'b'), ('name', 'Bob')])
+
−    >>> req.GET['check']
+
−    'b'
+
−    >>> req.GET.getall('check')
+
−    ['a', 'b']
+
−    >>> req.GET.items()
+
−    [('check', 'a'), ('check', 'b'), ('name', 'Bob')]
+
−
+
−We'll have to create a request body and change the method to get
+
−POST.  Until we do that, the variables are boring:
+
−
+
−.. code-block::
+
−
+
−    >>> req.POST
+
−    <NoVars: Not a POST request>
+
−    >>> req.POST.items()  # NoVars can be read like a dict, but not written
+
−    []
+
−    >>> req.method = 'POST'
+
−    >>> req.body = 'name=Joe&email=joe@example.com'
+
−    >>> req.POST
+
−    MultiDict([('name', 'Joe'), ('email', 'joe@example.com')])
+
−    >>> req.POST['name']
+
−    'Joe'
+
−
+
−Often you won't care where the variables come from.  (Even if you care
+
−about the method, the location of the variables might not be
+
−important.)  There is a dictionary called ``req.params`` that
+
−contains variables from both sources:
+
−
+
−.. code-block::
+
−
+
−    >>> req.params
+
−    NestedMultiDict([('check', 'a'), ('check', 'b'), ('name', 'Bob'), ('name', 'Joe'), ('email', 'joe@example.com')])
+
−    >>> req.params['name']
+
−    'Bob'
+
−    >>> req.params.getall('name')
+
−    ['Bob', 'Joe']
+
−    >>> for name, value in req.params.items():
+
−    ...     print '%s: %r' % (name, value)
+
−    check: 'a'
+
−    check: 'b'
+
−    name: 'Bob'
+
−    name: 'Joe'
+
−    email: 'joe@example.com'
+
−
+
−Unicode Variables
+
−~~~~~~~~~~~~~~~~~
+
−
+
−Submissions are non-unicode (``str``) strings, unless some character
+
−set is indicated.  A client can indicate the character set with
+
−``Content-Type: application/x-www-form-urlencoded; charset=utf8``, but
+
−very few clients actually do this (sometimes XMLHttpRequest requests
+
−will do this, as JSON is always UTF8 even when a page is served with a
+
−different character set).  You can force a charset, which will effect
+
−all the variables:
+
−
+
−.. code-block::
+
−
+
−    >>> req.charset = 'utf8'
+
−    >>> req.GET
+
−    UnicodeMultiDict([(u'check', u'a'), (u'check', u'b'), (u'name', u'Bob')])
+
−
+
−If you always want ``str`` values, you can use ``req.str_GET``
+
−and ``str_POST``.
+
−
+
−Cookies
+
−-------
+
−
+
−Cookies are presented in a simple dictionary.  Like other variables,
+
−they will be decoded into Unicode strings if you set the charset.
+
−
+
−.. code-block::
+
−
+
−    >>> req.headers['Cookie'] = 'test=value'
+
−    >>> req.cookies
+
−    UnicodeMultiDict([(u'test', u'value')])
+
−    >>> req.charset = None
+
−    >>> req.cookies
+
−    {'test': 'value'}
+
−
+
−Modifying the request
+
−---------------------
+
−
+
−The headers are all modifiable, as are other environmental variables
+
−(like ``req.remote_user``, which maps to
+
−``request.environ['REMOTE_USER']``).
+
−
+
−If you want to copy the request you can use ``req.copy()``; this
+
−copies the ``environ`` dictionary, and the request body from
+
−``environ['wsgi.input']``.
+
−
+
−The method ``req.remove_conditional_headers(remove_encoding=True)``
+
−can be used to remove headers that might result in a ``304 Not
+
−Modified`` response.  If you are writing some intermediary it can be
+
−useful to avoid these headers.  Also if ``remove_encoding`` is true
+
−(the default) then any ``Accept-Encoding`` header will be removed,
+
−which can result in gzipped responses.
+
−
+
−Header Getters
+
−--------------
+
−
+
−In addition to ``req.headers``, there are attributes for most of the
+
−request headers defined by the HTTP 1.1 specification.  These
+
−attributes often return parsed forms of the headers.
+
−
+
−Accept-* headers
+
−~~~~~~~~~~~~~~~~
+
−
+
−There are several request headers that tell the server what the client
+
−accepts.  These are ``accept`` (the Content-Type that is accepted),
+
−``accept_charset`` (the charset accepted), ``accept_encoding``
+
−(the Content-Encoding, like gzip, that is accepted), and
+
−``accept_language`` (generally the preferred language of the client).
+
−
+
−The objects returned support containment to test for acceptability.
+
−E.g.:
+
−
+
−.. code-block::
+
−
+
−    >>> 'text/html' in req.accept
+
−    True
+
−
+
−Because no header means anything is potentially acceptable, this is
+
−returning True.  We can set it to see more interesting behavior (the
+
−example means that ``text/html`` is okay, but
+
−``application/xhtml+xml`` is preferred):
+
−
+
−.. code-block::
+
−
+
−    >>> req.accept = 'text/html;q=0.5, application/xhtml+xml;q=1'
+
−    >>> req.accept
+
−    <MIMEAccept at ... Accept: text/html;q=0.5, application/xhtml+xml>
+
−    >>> 'text/html' in req.accept
+
−    True
+
−
+
−There's three methods for different strategies of finding a match.
+
−First, when you trust the server's preference over the client (a good
+
−idea for Accept):
+
−
+
−.. code-block::
+
−
+
−    >>> req.accept.first_match(['text/html', 'application/xhtml+xml'])
+
−    'text/html'
+
−
+
−Because ``text/html`` is at least *somewhat* acceptible, it is
+
−returned, even if the client says it prefers
+
−``application/xhtml+xml``.  If we trust the client more:
+
−
+
−.. code-block::
+
−
+
−    >>> req.accept.best_match(['text/html', 'application/xhtml+xml'])
+
−    'application/xhtml+xml'
+
−
+
−If we just want to know everything the client prefers, in the order it
+
−is preferred:
+
−
+
−.. code-block::
+
−
+
−    >>> req.accept.best_matches()
+
−    ['application/xhtml+xml', 'text/html']
+
−
+
−For languages you'll often have a "fallback" language.  E.g., if there's
+
−nothing better then use ``en-US`` (and if ``en-US`` is okay, ignore
+
−any less preferrable languages):
+
−
+
−.. code-block::
+
−
+
−    >>> req.accept_language = 'es, pt-BR'
+
−    >>> req.accept_language.best_matches('en-US')
+
−    ['es', 'pt-BR', 'en-US']
+
−    >>> req.accept_language.best_matches('es')
+
−    ['es']
+
−
+
−Conditional Requests
+
−~~~~~~~~~~~~~~~~~~~~
+
−
+
−There a number of ways to make a conditional request.  A conditional
+
−request is made when the client has a document, but it is not sure if
+
−the document is up to date.  If it is not, it wants a new version.  If
+
−the document is up to date then it doesn't want to waste the
+
−bandwidth, and expects a ``304 Not Modified`` response.
+
−
+
−ETags are generally the best technique for these kinds of requests;
+
−this is an opaque string that indicates the identity of the object.
+
−For instance, it's common to use the mtime (last modified) of the file,
+
−plus the number of bytes, and maybe a hash of the filename (if there's
+
−a possibility that the same URL could point to two different
+
−server-side filenames based on other variables).  To test if a 304
+
−response is appropriate, you can use:
+
−
+
−.. code-block::
+
−
+
−    >>> server_token = 'opaque-token'
+
−    >>> server_token in req.if_none_match # You shouldn't return 304
+
−    False
+
−    >>> req.if_none_match = server_token
+
−    >>> req.if_none_match
+
−    <ETag opaque-token>
+
−    >>> server_token in req.if_none_match # You *should* return 304
+
−    True
+
−
+
−For date-based comparisons If-Modified-Since is used:
+
−
+
−.. code-block::
+
−
+
−    >>> from webob import UTC
+
−    >>> from datetime import datetime
+
−    >>> req.if_modified_since = datetime(2006, 1, 1, 12, 0, tzinfo=UTC)
+
−    >>> req.headers['If-Modified-Since']
+
−    'Sun, 01 Jan 2006 12:00:00 GMT'
+
−    >>> server_modified = datetime(2005, 1, 1, 12, 0, tzinfo=UTC)
+
−    >>> req.if_modified_since and req.if_modified_since >= server_modified
+
−    True
+
−
+
−For range requests there are two important headers, If-Range (which is
+
−form of conditional request) and Range (which requests a range).  If
+
−the If-Range header fails to match then the full response (not a
+
−range) should be returned:
+
−
+
−.. code-block::
+
−
+
−    >>> req.if_range
+
−    <Empty If-Range>
+
−    >>> req.if_range.match(etag='some-etag', last_modified=datetime(2005, 1, 1, 12, 0))
+
−    True
+
−    >>> req.if_range = 'opaque-etag'
+
−    >>> req.if_range.match(etag='other-etag')
+
−    False
+
−    >>> req.if_range.match(etag='opaque-etag')
+
−    True
+
−
+
−You can also pass in a response object with:
+
−
+
−.. code-block::
+
−
+
−    >>> from webob import Response
+
−    >>> res = Response(etag='opaque-etag')
+
−    >>> req.if_range.match_response(res)
+
−    True
+
−
+
−To get the range information:
+
−
+
−    >>> req.range = 'bytes=0-100'
+
−    >>> req.range
+
−    <Range ranges=(0, 99)>
+
−    >>> cr = req.range.content_range(length=1000)
+
−    >>> cr.start, cr.stop, cr.length
+
−    (0, 99, 1000)
+
−
+
−Note that the range headers use *inclusive* ranges (the last byte
+
−indexed is included), where Python always uses a range where the last
+
−index is excluded from the range.  The ``.stop`` index is in the
+
−Python form.
+
−
+
−Another kind of conditional request is a request (typically PUT) that
+
−includes If-Match or If-Unmodified-Since.  In this case you are saying
+
−"here is an update to a resource, but don't apply it if someone else
+
−has done something since I last got the resource".  If-Match means "do
+
−this if the current ETag matches the ETag I'm giving".
+
−If-Unmodified-Since means "do this if the resource has remained
+
−unchanged".
+
−
+
−.. code-block::
+
−
+
−    >>> server_token in req.if_match # No If-Match means everything is ok
+
−    True
+
−    >>> req.if_match = server_token
+
−    >>> server_token in req.if_match # Still OK
+
−    True
+
−    >>> req.if_match = 'other-token'
+
−    >>> # Not OK, should return 412 Precondition Failed:
+
−    >>> server_token in req.if_match 
+
−    False
+
−
+
−For more on this kind of conditional request, see `Detecting the Lost
+
−Update Problem Using Unreserved Checkout
+
−<http://www.w3.org/1999/04/Editing/>`_.
+
−
+
−Calling WSGI Applications
+
−-------------------------
+
−
+
−The request object can be used to make handy subrequests or test
+
−requests against WSGI applications.  If you want to make subrequests,
+
−you should copy the request (with ``req.copy()``) before sending it to
+
−multiple applications, since applications might modify the request
+
−when they are run.
+
−
+
−There's two forms of the subrequest.  The more primitive form is
+
−this:
+
−
+
−.. code-block::
+
−
+
−    >>> req = Request.blank('/')
+
−    >>> def wsgi_app(environ, start_response):
+
−    ...     start_response('200 OK', [('Content-type', 'text/plain')])
+
−    ...     return ['Hi!']
+
−    >>> req.call_application(wsgi_app)
+
−    ('200 OK', [('Content-type', 'text/plain')], ['Hi!'])
+
−
+
−Note it returns ``(status_string, header_list, app_iter)``.  If
+
−``app_iter.close()`` exists, it is your responsibility to call it.
+
−
+
−A handier response can be had with:
+
−
+
−.. code-block::
+
−
+
−    >>> res = req.get_response(wsgi_app)
+
−    >>> res
+
−    <Response ... 200 OK>
+
−    >>> res.status
+
−    '200 OK'
+
−    >>> res.headers
+
−    HeaderDict([('Content-type', 'text/plain')])
+
−    >>> res.body
+
−    'Hi!'
+
−
+
−You can learn more about this response object in the Response_ section.
+
−
+
−Thread-local Request Wrappers
+
−-----------------------------
+
−
+
−You can also give the ``Request`` object a function to get the
+
−environment.  This can be used to make a single global request object
+
−dynamic.  An example:
+
−
+
−.. code-block::
+
−
+
−    >>> import threading
+
−    >>> import webob
+
−    >>> environments = threading.local()
+
−    >>> def get_environ():
+
−    ...     return environments.environ
+
−    >>> def set_thread_environ(environ):
+
−    ...     environments.environ = environ
+
−    >>> request = webob.Request(environ_getter=get_environ)
+
−    >>> set_thread_environ({'SCRIPT_NAME': '/test'})
+
−    >>> request.script_name
+
−    '/test'
+
−
+
−Ad-Hoc Attributes
+
−-----------------
+
−
+
−You can assign attributes to your request objects.  They will all go
+
−in ``environ['webob.adhoc_attrs']`` (a dictionary).  
+
−
+
−.. code-block::
+
−
+
−    >>> req = Request.blank('/')
+
−    >>> req.some_attr = 'blah blah blah'
+
−    >>> new_req = Request(req.environ)
+
−    >>> new_req.some_attr
+
−    'blah blah blah'
+
−    >>> req.environ['webob.adhoc_attrs']
+
−    {'some_attr': 'blah blah blah'}
+
−
+
−Response
+
−========
+
−
+
−The ``webob.Response`` object contains everything necessary to make a
+
−WSGI response.  Instances of it are in fact WSGI applications, but it
+
−can also represent the result of calling a WSGI application (as noted
+
−in `Calling WSGI Applications`_).  It can also be a way of
+
−accumulating a response in your WSGI application.
+
−
+
−A WSGI response is made up of a status (like ``200 OK``), a list of
+
−headers, and a body (or iterator that will produce a body).
+
−
+
−Core Attributes
+
−---------------
+
−
+
−The core attributes are unsurprising:
+
−
+
−.. code-block::
+
−
+
−    >>> from webob import Response
+
−    >>> res = Response()
+
−    >>> res.status
+
−    '200 OK'
+
−    >>> res.headerlist
+
−    [('Content-Length', '0')]
+
−    >>> res.body
+
−    ''
+
−
+
−You can set any of these attributes, e.g.:
+
−
+
−.. code-block::
+
−
+
−    >>> res.status = 404
+
−    >>> res.status
+
−    '404 Not Found'
+
−    >>> res.status_int
+
−    404
+
−    >>> res.headerlist = [('Content-type', 'text/html')]
+
−    >>> res.body = 'test'
+
−    >>> print res
+
−    404 Not Found
+
−    Content-type: text/html
+
−    Content-Length: 4
+
−    <BLANKLINE>
+
−    test
+
−    >>> res.body = u"test"
+
−    Traceback (most recent call last):
+
−        ...
+
−    TypeError: You cannot set Response.body to a unicode object (use Response.unicode_body)
+
−    >>> res.unicode_body = u"test"
+
−    Traceback (most recent call last):
+
−        ...
+
−    AttributeError: You cannot access Response.unicode_body unless charset is set
+
−    >>> res.charset = 'utf8'
+
−    >>> res.unicode_body = u"test"
+
−    >>> res.body
+
−    'test'
+
−
+
−You can set any attribute with the constructor, like
+
−``Response(charset='utf8')``
+
−
+
−Headers
+
−-------
+
−
+
−In addition to ``res.headerlist``, there is dictionary-like view on
+
−the list in ``res.headers``:
+
−
+
−.. code-block::
+
−
+
−    >>> res.headers
+
−    HeaderDict([('content-type', 'text/html; charset=utf8'), ('Content-Length', '4')])
+
−
+
−This is case-insensitive.  It can support multiple values for a key,
+
−though only if you use ``res.headers.add(key, value)`` or read them
+
−with ``res.headers.getall(key)``.
+
−
+
−Body & app_iter
+
−---------------
+
−
+
−The ``res.body`` attribute represents the entire body of the request
+
−as a single string (not unicode, though you can set it to unicode if
+
−you have a charset defined).  There is also a ``res.app_iter``
+
−attribute that reprsents the body as an iterator.  WSGI applications
+
−return these ``app_iter`` iterators instead of strings, and sometimes
+
−it can be problematic to load the entire iterator at once (for
+
−instance, if it returns the contents of a very large file).  Generally
+
−it is not a problem, and often the iterator is something simple like a
+
−one-item list containing a string with the entire body.
+
−
+
−If you set the body then Content-Length will also be set, and an
+
−``res.app_iter`` will be created for you.  If you set ``res.app_iter``
+
−then Content-Length will be cleared, but it won't be set for you.
+
−
+
−There is also a file-like object you can access, which will update the
+
−app_iter in-place (turning the app_iter into a list if necessary):
+
−
+
−.. code-block::
+
−
+
−    >>> res = Response(content_type='text/plain')
+
−    >>> f = res.body_file
+
−    >>> f.write('hey')
+
−    >>> f.write(u'test')
+
−    Traceback (most recent call last):
+
−      . . .
+
−    TypeError: You can only write unicode to Response.body_file if charset has been set
+
−    >>> f.encoding
+
−    >>> res.charset = 'utf8'
+
−    >>> f.encoding
+
−    'utf8'
+
−    >>> f.write(u'test')
+
−    >>> res.app_iter
+
−    ['hey', 'test']
+
−    >>> res.body
+
−    'heytest'
+
−
+
−Header Getters
+
−--------------
+
−
+
−Like Request, HTTP response headers are also available as individual
+
−properties.  These represent parsed forms of the headers.
+
−
+
−Content-Type is a special case, as the type and the charset are
+
−handled through two separate properties:
+
−
+
−.. code-block::
+
−
+
−    >>> res = Response()
+
−    >>> res.content_type = 'text/html'
+
−    >>> res.charset = 'utf8'
+
−    >>> res.content_type
+
−    'text/html'
+
−    >>> res.headers['content-type']
+
−    'text/html; charset=utf8'
+
−    >>> res.content_type = 'application/atom+xml'
+
−    >>> res.content_type_params
+
−    {'charset': 'utf8'}
+
−    >>> res.content_type_params = {'type': 'entry', 'charset': 'utf8'}
+
−    >>> res.headers['content-type']
+
−    'application/atom+xml; charset=utf8; type=entry'
+
−
+
−Other headers:
+
−
+
−.. code-block::
+
−
+
−    >>> # Used with a redirect:
+
−    >>> res.location = 'http://localhost/foo'
+
−
+
−    >>> # Indicates that the server accepts Range requests:
+
−    >>> res.accept_ranges = 'bytes'
+
−
+
−    >>> # Used by caching proxies to tell the client how old the
+
−    >>> # response is:
+
−    >>> res.age = 120
+
−
+
−    >>> # Show what methods the client can do; typically used in
+
−    >>> # a 405 Method Not Allowed response:
+
−    >>> res.allow = ['GET', 'PUT']
+
−
+
−    >>> # Set the cache-control header:
+
−    >>> res.cache_control.max_age = 360
+
−    >>> res.cache_control.no_transform = True
+
−
+
−    >>> # Used if you had gzipped the body:
+
−    >>> res.content_encoding = 'gzip'
+
−
+
−    >>> # What language(s) are in the content:
+
−    >>> res.content_language = ['en']
+
−
+
−    >>> # Seldom used header that tells the client where the content
+
−    >>> # is from:
+
−    >>> res.content_location = 'http://localhost/foo'
+
−
+
−    >>> # Seldom used header that gives a hash of the body:
+
−    >>> res.content_md5 = 'big-hash'
+
−
+
−    >>> # Means we are serving bytes 0-500 inclusive, out of 1000 bytes total:
+
−    >>> # you can also use the range setter shown earlier
+
−    >>> res.content_range = (0, 499, 1000)
+
−
+
−    >>> # The length of the content; set automatically if you set
+
−    >>> # res.body:
+
−    >>> res.content_length = 4
+
−
+
−    >>> # Used to indicate the current date as the server understands
+
−    >>> # it:
+
−    >>> res.date = datetime.now()
+
−
+
−    >>> # The etag:
+
−    >>> res.etag = 'opaque-token'
+
−    >>> # You can generate it from the body too:
+
−    >>> res.md5_etag()
+
−    >>> res.etag
+
−    '1B2M2Y8AsgTpgAmY7PhCfg'
+
−
+
−    >>> # When this page should expire from a cache (Cache-Control
+
−    >>> # often works better):
+
−    >>> import time
+
−    >>> res.expires = time.time() + 60*60 # 1 hour
+
−
+
−    >>> # When this was last modified, of course:
+
−    >>> res.last_modified = datetime(2007, 1, 1, 12, 0, tzinfo=UTC)
+
−
+
−    >>> # Used with 503 Service Unavailable to hint the client when to
+
−    >>> # try again:
+
−    >>> res.retry_after = 160
+
−
+
−    >>> # Indicate the server software:
+
−    >>> res.server = 'WebOb/1.0'
+
−
+
−    >>> # Give a list of headers that the cache should vary on:
+
−    >>> res.vary = ['Cookie']
+
−
+
−Note in each case you can general set the header to a string to avoid
+
−any parsing, and set it to None to remove the header (or do something
+
−like ``del res.vary``).
+
−
+
−In the case of date-related headers you can set the value to a
+
−``datetime`` instance (ideally with a UTC timezone), a time tuple, an
+
−integer timestamp, or a properly-formatted string.
+
−
+
−After setting all these headers, here's the result:
+
−
+
−.. code-block::
+
−
+
−    >>> for name, value in res.headerlist:
+
−    ...     print '%s: %s' % (name, value)
+
−    content-type: application/atom+xml; charset=utf8; type=entry
+
−    location: http://localhost/foo
+
−    Accept-Ranges: bytes
+
−    Age: 120
+
−    Allow: GET, PUT
+
−    Cache-Control: max-age=360, no-transform
+
−    Content-Encoding: gzip
+
−    Content-Language: en
+
−    Content-Location: http://localhost/foo
+
−    Content-MD5: big-hash
+
−    Content-Range: bytes 0-500/1000
+
−    Content-Length: 4
+
−    Date: ... GMT
+
−    ETag: ...
+
−    Expires: ... GMT
+
−    Last-Modified: Mon, 01 Jan 2007 12:00:00 GMT
+
−    Retry-After: 160
+
−    Server: WebOb/1.0
+
−    Vary: Cookie
+
−
+
−You can also set Cache-Control related attributes with
+
−``req.cache_expires(seconds, **attrs)``, like:
+
−
+
−.. code-block::
+
−
+
−    >>> res = Response()
+
−    >>> res.cache_expires(10)
+
−    >>> res.headers['Cache-Control']
+
−    'max-age=10'
+
−    >>> res.cache_expires(0)
+
−    >>> res.headers['Cache-Control']
+
−    'max-age=0, must-revalidate, no-cache, no-store'
+
−    >>> res.headers['Expires']
+
−    '... GMT'
+
−
+
−You can also use the `timedelta
+
−<http://python.org/doc/current/lib/datetime-timedelta.html>`_
+
−constants defined, e.g.:
+
−
+
−.. code-block::
+
−
+
−    >>> from webob import *
+
−    >>> res = Response()
+
−    >>> res.cache_expires(2*day+4*hour)
+
−    >>> res.headers['Cache-Control']
+
−    'max-age=187200'
+
−
+
−Cookies
+
−-------
+
−
+
−Cookies (and the Set-Cookie header) are handled with a couple
+
−methods.  Most importantly:
+
−
+
−.. code-block::
+
−
+
−    >>> res.set_cookie('key', 'value', max_age=360, path='/',
+
−    ...                domain='example.org', secure=True)
+
−    >>> res.headers['Set-Cookie']
+
−    'key=value; Domain=example.org; Max-Age=360; Path=/; secure;'
+
−    >>> # To delete a cookie previously set in the client:
+
−    >>> res.delete_cookie('bad_cookie')
+
−    >>> res.headers['Set-Cookie']
+
−    'bad_cookie=; Max-Age=0; Path=/;'
+
−
+
−The only other real method of note (note that this does *not* delete
+
−the cookie from clients, only from the response object):
+
−
+
−.. code-block::
+
−
+
−    >>> res.unset_cookie('key')
+
−    >>> res.unset_cookie('bad_cookie')
+
−    >>> print res.headers.get('Set-Cookie')
+
−    None
+
−
+
−Binding a Request
+
−-----------------
+
−
+
−You can bind a request (or request WSGI environ) to the response
+
−object.  This is available through ``res.request`` or
+
−``res.environ``.  This is currently only used in setting
+
−``res.location``, to make the location absolute if necessary.
+
−
+
−Response as a WSGI application
+
−------------------------------
+
−
+
−A response is a WSGI application, in that you can do:
+
−
+
−.. code-block::
+
−
+
−    >>> req = Request.blank('/')
+
−    >>> status, headers, app_iter = req.call_application(res)
+
−
+
−A possible pattern for your application might be:
+
−
+
−.. code-block::
+
−
+
−    >>> def my_app(environ, start_response):
+
−    ...     req = Request(environ)
+
−    ...     res = Response()
+
−    ...     res.content_type = 'text/plain'
+
−    ...     parts = []
+
−    ...     for name, value in sorted(req.environ.items()):
+
−    ...         parts.append('%s: %r' % (name, value))
+
−    ...     res.body = '\n'.join(parts)
+
−    ...     return res(environ, start_response)
+
−    >>> req = Request.blank('/')
+
−    >>> res = req.get_response(my_app)
+
−    >>> print res
+
−    200 OK
+
−    content-type: text/plain
+
−    Content-Length: 394
+
−    <BLANKLINE>
+
−    HTTP_HOST: 'localhost:80'
+
−    PATH_INFO: '/'
+
−    QUERY_STRING: ''
+
−    REQUEST_METHOD: 'GET'
+
−    SCRIPT_NAME: ''
+
−    SERVER_NAME: 'localhost'
+
−    SERVER_PORT: '80'
+
−    SERVER_PROTOCOL: 'HTTP/1.0'
+
−    wsgi.errors: <open file '<stderr>', mode 'w' at ...>
+
−    wsgi.input: <cStringIO.StringI object at ...>
+
−    wsgi.multiprocess: False
+
−    wsgi.multithread: False
+
−    wsgi.run_once: False
+
−    wsgi.url_scheme: 'http'
+
−    wsgi.version: (1, 0)
+
−
+
−Exceptions
+
−==========
+
−
+
−In addition to Request and Response objects, there are a set of Python
+
−exceptions for different HTTP responses (3xx, 4xx, 5xx codes).
+
−
+
−These provide a simple way to provide these non-200 response.  A very
+
−simple body is provided.
+
−
+
−.. code-block::
+
−
+
−    >>> from webob.exc import *
+
−    >>> exc = HTTPTemporaryRedirect(location='foo')
+
−    >>> req = Request.blank('/path/to/something')
+
−    >>> print str(req.get_response(exc)).strip()
+
−    307 Temporary Redirect
+
−    content-type: text/html
+
−    location: http://localhost/path/to/foo
+
−    Content-Length: 126
+
−    <BLANKLINE>
+
−    307 Temporary Redirect
+
−    <BLANKLINE>
+
−    The resource has been moved to http://localhost/path/to/foo; you should be redirected automatically.
+
−
+
−Note that only if there's an ``Accept: text/html`` header in the
+
−request will an HTML response be given:
+
−
+
−.. code-block::
+
−
+
−    >>> req.accept += 'text/html'
+
−    >>> print str(req.get_response(exc)).strip()
+
−    307 Temporary Redirect
+
−    content-type: text/html
+
−    location: http://localhost/path/to/foo
+
−    Content-Length: 270
+
−    <BLANKLINE>
+
−    <html>
+
−     <head>
+
−      <title>307 Temporary Redirect</title>
+
−     </head>
+
−     <body>
+
−      <h1>307 Temporary Redirect</h1>
+
−      The resource has been moved to <a href="http://localhost/path/to/foo">http://localhost/path/to/foo</a>;
+
−    you should be redirected automatically.
+
−    <BLANKLINE>
+
−    <BLANKLINE>
+
−     </body>
+
−    </html>
+
−
+
−
+
−This is taken from `paste.httpexceptions
+
−<http://pythonpaste.org/module-paste.httpexceptions.html>`_, and if
+
−you have Paste installed then these exceptions will be subclasses of
+
−the Paste exceptions.
+
−
+
−Note that on Python 2.4 and before, new-style classes could not be
+
−used as exceptions.  ``Response`` objects must be new-style classes,
+
−so this causes a bit of a conflict.  The base class
+
−``webob.exc.HTTPException`` *is* an exception, so you can catch that,
+
−and it *is* a WSGI application.  But you may not be able to use
+
−Response methods.  You can always get ``obj.exception`` to get an
+
−exception that you can raise, and ``obj.wsgi_response`` to get the
+
−``Response`` object that you can use.
+
−
+
−Conditional WSGI Application
+
−----------------------------
+
−
+
−The Response object can handle your conditional responses for you,
+
−checking If-None-Match, If-Modified-Since, and Range/If-Range.
+
−
+
−To enable this you must create the response like
+
−``Response(conditional_request=True)``, or make a subclass like:
+
−
+
−.. code-block::
+
−
+
−    >>> class AppResponse(Response):
+
−    ...     default_content_type = 'text/html'
+
−    ...     default_conditional_response = True
+
−    >>> res = AppResponse(body='0123456789',
+
−    ...                   last_modified=datetime(2005, 1, 1, 12, 0, tzinfo=UTC))
+
−    >>> req = Request.blank('/')
+
−    >>> req.if_modified_since = datetime(2006, 1, 1, 12, 0, tzinfo=UTC)
+
−    >>> req.get_response(res)
+
−    <Response ... 304 Not Modified>
+
−    >>> del req.if_modified_since
+
−    >>> res.etag = 'opaque-tag'
+
−    >>> req.if_none_match = 'opaque-tag'
+
−    >>> req.get_response(res)
+
−    <Response ... 304 Not Modified>
+
−    >>> del req.if_none_match
+
−    >>> req.range = (1, 5)
+
−    >>> result = req.get_response(res)
+
−    >>> result.headers['content-range']
+
−    'bytes 1-6/10'
+
−    >>> result.body
+
−    '1234'