WebOb

+++++

Other documents:

* `Reference <reference.html>`_

* Extracted documentation for the `request

  <class-webob.Request.html>`_ and `response

  <class-webob.Response.html>`_.

* `Differences between the WebOb API and other framework/libraries

  <differences.html>`_

* `File-serving example <file-example.html>`_

* `Comment middleware example <comment-example.html>`_

.. contents::

.. comment:

    >>> from dtopt import ELLIPSIS

Status & License

================

WebOb is an extraction and refinement of pieces from `Paste

<http://pythonpaste.org/>`_.  It is under active development.

Discussion should happen on the `Paste mailing lists

<http://pythonpaste.org/community/>`_, and bugs can go on the `Paste

trac instance <http://trac.pythonpaste.org/>`_.

WebOb is released under an `MIT-style license <license.html>`_.

WebOb is in an svn repository at

`http://svn.pythonpaste.org/Paste/WebOb/trunk

<http://svn.pythonpaste.org/Paste/WebOb/trunk#egg=WebOb-dev>`_.  You

can check it out with::

    $ svn co http://svn.pythonpaste.org/Paste/WebOb/trunk WebOb

Introduction

============

WebOb provides objects for HTTP requests and responses.  Specifically

it does this by wrapping the `WSGI <http://wsgi.org>`_ request

environment and response status/headers/app_iter(body).

The request and response objects provide many conveniences for parsing

HTTP request and forming HTTP responses.  Both objects are read/write:

as a result, WebOb is also a nice way to create HTTP requests and

parse HTTP responses; however, we won't cover that use case in this

document.  The `reference documentation <reference.html>`_ shows many

examples of creating requests.

Request

=======

The request object is a wrapper around the `WSGI environ dictionary

<http://www.python.org/dev/peps/pep-0333/#environ-variables>`_.  This

dictionary contains keys for each header, keys that describe the

request (including the path and query string), a file-like object for

the request body, and a variety of custom keys.  You can always access

the environ with ``req.environ``.

Some of the most important/interesting attributes of a request

object:

``req.method``:

    The request method, e.g., ``'GET'``, ``'POST'``

``req.GET``:

    A `dictionary-like object`_ with all the variables in the query

    string.

``req.POST``:

    A `dictionary-like object`_ with all the variables in the request

    body.  This only has variables if the request was a ``POST`` and

    it is a form submission.  

``req.params``:

    A `dictionary-like object`_ with a combination of everything in

    ``req.GET`` and ``req.POST``.

``req.body``:

    The contents of the body of the request.  This contains the entire

    request body as a string.  This is useful when the request is a

    ``POST`` that is *not* a form submission, or a request like a

    ``PUT``.  You can also get ``req.body_file`` for a file-like

    object.

``req.cookies``:

    A simple dictionary of all the cookies.

``req.headers``:

    A dictionary of all the headers.  This is dictionary is case-insensitive.

.. _`dictionary-like object`: #multidict

Also, for standard HTTP request headers there are usually attributes,

for instance: ``req.accept_language``, ``req.content_length``,

``req.user_agent``, as an example.  These properties expose the

*parsed* form of each header, for whatever parsing makes sense.  For

instance, ``req.if_modified_since`` returns a `datetime

<http://python.org/doc/current/lib/datetime-datetime.html>`_ object

(or None if the header is was not provided).  Details are in the

`Request reference <class-webob.Request.html>`_.

URLs

----

In addition to these attributes, there are several ways to get the URL

of the request.  I'll show various values for an example URL

``http://localhost/app-root/doc?article_id=10``, where the application

is mounted at ``http://localhost/app-root``.

``req.url``:

    The full request URL, with query string, e.g.,

    ``'http://localhost/app-root/doc?article_id=10'``

``req.application_url``:

    The URL of the application (just the SCRIPT_NAME portion of the

    path, not PATH_INFO).  E.g., ``'http://localhost/app-root'``

``req.host_url``:

    The URL with the host, e.g., ``'http://localhost'``

``req.relative_url(url, to_application=False)``:

    Gives a URL, relative to the current URL.  If ``to_application``

    is True, then resolves it relative to ``req.application_url``.

Methods

-------

There are `several methods <class-webob.Request.html#__init__>`_ but

only a few you'll use often:

``Request.blank(base_url)``:

    Creates a new request with blank information, based at the given

    URL.  This can be useful for subrequests and artificial requests.

    You can also use ``req.copy()`` to copy an existing request, or

    for subrequests ``req.copy_get()`` which copies the request but

    always turns it into a GET (which is safer to shrae for

    subrequests).

``req.get_response(wsgi_application)``:

    This method calls the given WSGI application with this request,

    and returns a `Response`_ object.  You can also use this for

    subrequests or testing.

Unicode

-------

Many of the properties in the request object will return unicode

values if the request encoding/charset is provided.  The client *can*

indicate the charset with something like ``Content-Type:

application/x-www-form-urlencoded; charset=utf8``, but browsers seldom

set this.  You can set the charset with ``req.charset = 'utf8'``, or

during instantiation with ``Request(environ, charset='utf8').  If you

subclass ``Request`` you can also set ``charset`` as a class-level

attribute.

If it is set, then ``req.POST``, ``req.GET``, ``req.params``, and

``req.cookies`` will contain unicode strings.  Each has a

corresponding ``req.str_*`` (like ``req.str_POST``) that is always

``str`` and never unicode.

Response

========

The response object looks a lot like the request object, though with

some differences.  The request object wraps a single ``environ``

object; the response object has three fundamental parts (based on

WSGI):

``response.status``:

    The response code plus message, like ``'200 OK'``.  To set the

    code without the reason, use ``response.status_int = 200``.

``response.headerlist``:

    A list of all the headers, like ``[('Content-Type',

    'text/html')]``.  There's a case-insensitive `dictionary-like

    object`_ in ``response.headers`` that also allows you to access

    these same headers.

``response.app_iter``:

    An iterable (such as a list or generator) that will produce the

    content of the response.  This is also accessible as

    ``response.body`` (a string), ``response.unicode_body`` (a

    unicode object, informed by ``response.charset``), and

    ``response.body_file`` (a file-like object; writing to it appends

    to ``app_iter``).

Everything else in the object derives from this underlying state.

Here's the highlights:

``response.content_type``:

    The content type *not* including the ``charset`` parameter.

    Typical use: ``response.content_type = 'text/html'``.  You can

    subclass ``Response`` and add a class-level attribute

    ``default_content_type`` to set this automatically on

    instantiation.

``response.charset``:

    The ``charset`` parameter of the content-type, it also informs

    encoding in ``response.unicode_body``.

    ``response.content_type_params`` is a dictionary of all the

    parameters.

``response.request``:

    This optional attribute can point to the request object associated

    with this response object.

``response.set_cookie(key, value, max_age=None, path='/', domain=None, secure=None, httponly=False, version=None, comment=None)``:

    Set a cookie.  The keyword arguments control the various cookie

    parameters.

``response.delete_cookie(key, path='/', domain=None)``:

    Delete a cookie from the client.  This sets ``max_age`` to 0 and

    the cookie value to ``''``.

``response.cache_expires(seconds=0)``:

    This makes this response cachable for the given number of seconds,

    or if ``seconds`` is 0 then the response is uncacheable (this also

    sets the ``Expires`` header).

``response(environ, start_response)``: The response object is a WSGI

    application.  As an application, it acts according to how you

    creat it.  It *can* do conditional responses if you pass

    ``conditional_response=True`` when instantiating (or set that

    attribute later).  It can also do HEAD and Range requests.

Headers

-------

Like the request, most HTTP response headers are available as

properties.  These are parsed, so you can do things like

``response.last_modified = os.path.getmtime(filename)``.

The details are available in the `extracted Response documentation

<class-webob.Response.html>`_.

Instantiating the Response

--------------------------

Of course most of the time you just want to *make* a response.  

Generally any attribute of the response can be passed in as a keyword

argument to the class; e.g.:

.. code-block::

  response = Response(body='hello world!', content_type='text/plain')

The status defaults to ``'200 OK'``.  The content_type does not

default to anything, though if you subclass ``Response`` and set

``default_content_type`` you can override this behavior.

Exceptions

==========

To facilitate error responses like 404 Not Found, the module

``webob.exc`` contains classes for each kind of error response.  These

include boring but appropriate error bodies.

Each class is named ``webob.exc.HTTP*``, where ``*`` is the reason for

the error.  For instance, ``webob.exc.HTTPNotFound``.  It subclasses

``Response``, so you can manipulate the instances in the same way.  A

typical example is:

.. code-block::

    response = HTTPNotFound('There is no such resource')

    # or:

    response = HTTPMovedPermanently(location=new_url)

These are not exceptions unless you are using Python 2.5+, because

they are new-style classes which are not allowed as exceptions until

Python 2.5.  To get an exception object use ``response.exception``.

You can use this like:

.. code-block::

    try:

        ... stuff ...

        raise HTTPNotFound('No such resource').exception

    except HTTPException, e:

        return e(environ, start_response)

The exceptions are still WSGI applications, but you cannot set

attributes like ``content_type``, ``charset``, etc. on these exception

objects.

Multidict

=========

Several parts of WebOb use a "multidict"; this is a dictionary where a

key can have multiple values.  The quintessential example is a query

string like ``?pref=red&pref=blue``; the ``pref`` variable has two

values: ``red`` and ``blue``.

In a multidict, when you do ``request.GET['pref']`` you'll get back

only ``'blue'`` (the last value of ``pref``).  Sometimes returning a

string, and sometimes returning a list, is the cause of frequent

exceptions.  If you want *all* the values back, use

``request.GET.getall('pref')``.  If you want to be sure there is *one

and only one* value, use ``request.GET.getone('pref')``, which will

raise an exception if there is zero or more than one value for

``pref``.

When you use operations like ``request.GET.items()`` you'll get back

something like ``[('pref', 'red'), ('pref', 'blue')]``.  All the

key/value pairs will show up.  Similarly ``request.GET.keys()``

returns ``['pref', 'pref']``.  Multidict is a view on a list of

tuples; all the keys are ordered, and all the values are ordered.

Example

=======

I haven't figured out the example I want to use here.  The

`file-serving example`_ shows how to do more advanced HTTP techniques,

while the `comment middleware example`_ shows middleware.  For

applications it's more reasonable to use WebOb in the context of a

larger framework.  `Pylons <http://pylonshq.com>`_ uses WebOb

optionally in 0.9.7+.