path: root/docs/index.txt

.. _index:

WebOb
+++++

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.

.. toctree::
   :maxdepth: 2

   reference
   differences
   license


API Documentation
=================

Reference material for every public API exposed by WebOb:

.. toctree::
   :maxdepth: 1
   :glob:

   api/*


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 and interesting attributes of a request object are
the following:

``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 dictionary is case-insensitive.

``req.urlvars`` and ``req.urlargs``:
    ``req.urlvars`` is the keyword parameters associated with the
    request URL.  ``req.urlargs`` are the positional parameters.
    These are set by products like `Routes
    <http://routes.readthedocs.io/en/latest/>`_ and `Selector
    <https://github.com/lukearno/selector>`_.

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

Also for standard HTTP request headers, there are usually attributes, e.g.,
``req.accept_language``, ``req.content_length``, and ``req.user_agent``. 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 the URL is resolved relative to ``req.application_url``.

Methods
-------

There are several methods in :class:`webob.Request` 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 share 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.

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_code = 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 are 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.set_cookie(name=None, value='', max_age=None, path='/', domain=None, secure=False, httponly=False, comment=None, overwrite=False)``:
    Set a cookie.  The keyword arguments control the various cookie
    parameters.  The ``max_age`` argument is the length for the cookie
    to live in seconds (you may also use a timedelta object). 

``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 cacheable 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
    create 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)``.

.. seealso:: :class:`webob.response.Response`

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:: python

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

The status defaults to ``'200 OK'``. The content_type defaults to
``default_content_type`` which is set to `text/html`, although 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:: python

    response = HTTPNotFound('There is no such resource')
    # or:
    response = HTTPMovedPermanently(location=new_url)

You can use this like:

.. code-block:: python

    try:
        # ... stuff ...
        raise HTTPNotFound('No such resource')
    except HTTPException, e:
        return e(environ, start_response)

Multidict
=========

Several parts of WebOb use a "multidict", which 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 other times returning a list is a 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
=======

The `file-serving example <file-example>`_ shows how to do more
advanced HTTP techniques, while the `comment middleware example
<comment-example>`_ shows middleware.  For applications, it's more
reasonable to use WebOb in the context of a larger framework.  `Pyramid
<https://trypyramid.com>`_, and its predecessor `Pylons
<http://docs.pylonsproject.org/projects/pylons-webframework/en/latest/>`_,
both use WebOb.

.. toctree::
   :maxdepth: 1

   file-example
   wiki-example
   comment-example
   jsonrpc-example
   do-it-yourself

Change History
==============

.. toctree::
   :maxdepth: 1

   whatsnew-1.5
   whatsnew-1.6
   whatsnew-1.7
   changes

Status and License
==================

WebOb is an extraction and refinement of pieces from `Paste
<http://pythonpaste.org/>`_.  It is under active development on `GitHub
<https://github.com/pylons/webob>`_. It was originally written by `Ian Bicking
<http://www.ianbicking.org/>`_, and is maintained by the `Pylons Project
<http://www.pylonsproject.org/>`_.

You can clone the source code with:

.. code-block:: bash

    $ git clone https://github.com/Pylons/webob.git

Report issues on the `issue tracker <https://github.com/Pylons/webob/issues>`_.

If you've got questions that aren't answered by this documentation, contact the
`pylons-discuss mail list
<https://groups.google.com/forum/#!forum/pylons-discuss>`_ or join the
`#pyramid IRC channel <https://webchat.freenode.net/?channels=pyramid>`_.

WebOb is released under an :doc:`MIT-style license <license>`.