Differences Between WebOb and Other Systems

+++++++++++++++++++++++++++++++++++++++++++

This document points out some of the API differences between the

Request and Response object, and the objects in other systems.

.. contents::

paste.wsgiwrappers and Pylons

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

The Pylons ``request`` and ``response`` object are based on

``paste.wsgiwrappers.WSGIRequest`` and ``WSGIResponse``

There is no concept of ``defaults`` in WebOb.  In Paste/Pylons these

serve as threadlocal settings that control certain policies on the

request and response object.  In WebOb you should make your own

subclasses to control policy (though in many ways simply being

explicit elsewhere removes the need for this policy).

Request

-------

``body``:

    This is a file-like object in WSGIRequest.  In WebOb it is a

    string (to match Response.body) and the file-like object is

    available through ``req.body_file``

``languages()``:

    This is available through ``req.accept_language``, particularly

    ``req.accept_language.best_matches(fallback_language)``

``match_accept(mimetypes)``:

    This is available through ``req.accept.first_match(mimetypes)``;

    or if you trust the client's quality ratings, you can use

    ``req.accept.best_match(mimetypes)``

``errors``:

    This controls how unicode decode errors are handled; it is now

    named ``unicode_errors``

There are also many extra methods and attributes on WebOb Request

objects.

Response

--------

default ``content_type``:

    The base Response object has no default content_type or charset.

    You can set ``default_content_type`` in a subclass.

``determine_charset()``:

    Is now available as ``res.charset``

``has_header(header)``:

    Should be done with ``header in res.headers``

``get_content()`` and ``wsgi_response()``:

    These are gone; you should use ``res.body`` or ``res(environ,

    start_response)``

``write(content)``:

    Available in ``res.body_file.write(content)``.

``flush()`` and ``tell()``:

    Not available.

There are also many extra methods and attributes on WebOb Response

objects.

Django

======

This is a quick summary from reading `the Django documentation

<http://www.djangoproject.com/documentation/request_response/>`_.

Request

-------

``encoding``:

    Is ``req.charset``

``REQUEST``:

    Is ``req.params``

``FILES``:

    File uploads are ``cgi.FieldStorage`` objects directly in

    ``res.POST``

``META``:

    Is ``req.environ``

``user``:

    No equivalent (too connected to application model for WebOb).

    There is ``req.remote_user``, which is only ever a string.

``session``:

    No equivalent

``raw_post_data``:

    Available with ``req.body``

``__getitem__(key)``:

    You have to use ``req.params``

``is_secure()``:

    No equivalent; you could use ``req.scheme == 'https'``.

QueryDict

---------

QueryDict is the way Django represents the multi-key dictionary-like

objects that are request variables (query string and POST body

variables).  The equivalent in WebOb is MultiDict.

Mutability:

    WebOb dictionaries are sometimes mutable (req.GET is,

    req.params is not)

Ordering:

    I believe Django does not order the keys fully; MultiDict is a

    full ordering.  Methods that iterate over the parameters iterate

    over keys in their order in the original request.

``keys()``, ``items()``, ``values()`` (plus ``iter*``):

    These return all values in MultiDict, but only the last value for

    a QueryDict.  That is, given ``a=1&a=2`` with MultiDict

    ``d.items()`` returns ``[('a', '1'), ('a', '2')]``, but QueryDict

    returns ``[('a', '1')]``

``getlist(key)``:

    Available as ``d.getall(key)``

``setlist(key)``:

    No direct equivalent

``appendlist(key, value)``:

    Available as ``d.add(key, value)``

``setlistdefault(key, default_list)``:

    No direct equivalent

``lists()``:

    Is ``d.dict_of_lists()``

The MultiDict object has a ``d.getone(key)`` method, that raises

KeyError if there is not exactly one key.  There is a method

``d.mixed()`` which returns a version where values are lists *if*

there are multiple values for a list.  This is similar to how many

cgi-based request forms are represented.

Response

--------

Constructor:

    Totally different.  The WebOb Response object should probably be

    subclassed for direct application use; in WebOb it does not

    *prefer* HTML or anything normal web application conventions

dictionary-like:

    The Django response object is somewhat dictionary-like, setting

    headers.  The equivalent dictionary-like object is

    ``res.headers``.  In WebOb this is a MultiDict.

``has_header(header)``:

    Use ``header in res.headers``

``write(content)``:

    As ``res.body_file.write(content)``

``flush()``, ``tell()``:

    Not available

``content``:

    Use ``res.body`` for the ``str`` value, ``res.unicode_body`` for

    the ``unicode`` value

Response Subclasses

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

These are generally like ``webob.exc`` objects.

``HttpResponseNotModified`` is ``HTTPNotModified``; this naming

translation generally works.

CherryPy/TurboGears

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

The `CherryPy request object

<http://www.cherrypy.org/wiki/RequestObject>`_ is also used by

TurboGears 1.x.

Request

-------

``app``:

    No equivalent

``base``:

    ``req.application_url``

``close()``:

    No equivalent

``closed``:

    No equivalent

``config``:

    No equivalent

``cookie``:

    A ``SimpleCookie`` object in CherryPy; a dictionary in WebOb

    (``SimpleCookie`` can represent cookie parameters, but cookie

    parameters are only sent with responses not requests)

``dispatch``:

    No equivalent (this is the object dispatcher in CherryPy).

``error_page``, ``error_response``, ``handle_error``:

    No equivalent

``get_resource()``:

    Similar to ``req.get_response(app)``

``handler``:

    No equivalent

``headers``, ``header_list``:

    The WSGI environment represents headers as a dictionary, available

    through ``req.headers`` (no list form is available in the request).

``hooks``:

    No equivalent

``local``:

    No equivalent

``methods_with_bodies``:

    This represents methods where CherryPy will automatically try to

    read the request body.  WebOb lazily reads POST requests with the

    correct content type, and no other bodies.

``namespaces``:

    No equivalent

``protocol``:

    As ``req.environ['SERVER_PROTOCOL']``

``query_string``:

    As ``req.query_string``

``remote``:

    ``remote.ip`` is like ``req.remote_addr``.  ``remote.port`` is not

    available.  ``remote.name`` is in

    ``req.environ.get('REMOTE_HOST')``

``request_line``:

    No equivalent

``respond()``:

    A method that is somewhat similar to ``req.get_response()``.

``rfile``:

    ``req.body_file``

``run``:

    No equivalent

``server_protocol``:

    As ``req.environ['SERVER_PROTOCOL']``

``show_tracebacks``:

    No equivalent

``throw_errors``:

    No equivalent

``throws``:

    No equivalent

``toolmaps``:

    No equivalent

``wsgi_environ``:

    As ``req.environ``

Response

--------

From information `from the wiki

<http://www.cherrypy.org/wiki/ResponseObject>`_.

``body``:

    This is an iterable in CherryPy, a string in WebOb;

    ``res.app_iter`` gives an iterable in WebOb.

``check_timeout``:

    No equivalent

``collapse_body()``:

    This turns a stream/iterator body into a single string.  Accessing

    ``res.body`` will do this automatically.

``cookie``:

    Accessible through ``res.set_cookie(...)``, ``res.delete_cookie``,

    ``res.unset_cookie()``

``finalize()``:

    No equivalent

``header_list``:

    In ``res.headerlist``

``stream``:

    This can make CherryPy stream the response body out directory.

    There is direct no equivalent; you can use a dynamically generated

    iterator to do something similar.

``time``:

    No equivalent

``timed_out``:

    No equivalent

Yaro

====

`Yaro <http://lukearno.com/projects/yaro/>`_ is a small wrapper around

the WSGI environment, much like WebOb in scope.

The WebOb objects have many more methods and attributes.  The Yaro

Response object is a much smaller subset of WebOb's Response.

Request

-------

``query``:

    As ``req.GET``

``form``:

    As ``req.POST``

``cookie``:

    A ``SimpleCookie`` object in Yaro; a dictionary in WebOb

    (``SimpleCookie`` can represent cookie parameters, but cookie

    parameters are only sent with responses not requests)

``uri``:

    Returns a URI object, no equivalent (only string URIs available).

``redirect``:

    Not available (response-related).  ``webob.exc.HTTPFound()`` can

    be useful here.

``forward(yaroapp)``, ``wsgi_forward(wsgiapp)``:

    Available with ``req.get_response(app)`` and

    ``req.call_application(app)``.  In both cases it is a WSGI

    application in WebOb, there is no special kind of communication;

    ``req.call_application()`` just returns a ``webob.Response`` object.

``res``:

    The request object in WebOb *may* have a ``req.response``

    attribute.

Werkzeug

========

Probably not that many people know about this library, which is a

offshoot of `Pocoo <http://pocoo.org>`_, and used to go by another

name (Columbrid?)  This library is based around WSGI, similar to Paste

and Yaro.

This is take from the `wrapper documentation

<http://werkzeug.pocoo.org/documentation/wrappers>`_.

Request

-------

path:

    As ``req.path_info``

args:

    As ``req.GET``

form:

    As ``req.POST``

values:

    As ``req.params``

files:

    In ``req.POST`` (as FieldStorage objects)

data:

    In ``req.body_file``

Response

--------

response:

    In ``res.body`` (settable as ``res.body`` or ``res.app_iter``)

status:

    In ``res.status_int``

mimetype:

    In ``res.content_type``

write(data):

    With ``res.body_file.write(data)``

Zope 3

======

From the Zope 3 interfaces for the `Request

<http://apidoc.zope.org/++apidoc++/Interface/zope.publisher.interfaces.browser.IBrowserRequest/index.html>`_

and `Response

<http://apidoc.zope.org/++apidoc++/Interface/zope.publisher.interfaces.http.IHTTPResponse/index.html>`_.

Request

-------

``locale``, ``setupLocale()``:

    This is not fully calculated, but information is available in

    ``req.accept_languages``.

``principal``, ``setPrincipal(principal)``:

    ``req.remote_user`` gives the username, but there is no standard

    place for a user *object*.

``publication``, ``setPublication()``, 

    These are associated with the object publishing system in Zope.

    This kind of publishing system is outside the scope of WebOb.

``traverse(object)``, ``getTraversalStack()``, ``setTraversalStack()``:

    These all relate to traversal, which is part of the publishing

    system.

``processInputs()``, ``setPathSuffix(steps)``:

    Also associated with traversal and preparing the request.

``environment``:

    In ``req.environ``

``bodyStream``:

    In ``req.body_file``

``interaction``:

    This is the security context for the request; all the possible

    participants or principals in the request.  There's no

    equivalent.

``annotations``:

    Extra information associated with the request.  This would

    generally go in custom keys of ``req.environ``, or if you set

    attributes those attributes are stored in

    ``req.environ['webob.adhoc_attrs']``.

``debug``:

    There is no standard debug flag for WebOb.

``__getitem__(key)``, ``get(key)``, etc:

    These treat the request like a dictionary, which WebOb does not

    do.  They seem to take values from the environment, not

    parameters.  Also on the Zope request object is ``items()``,

    ``__contains__(key)``, ``__iter__()``, ``keys()``, ``__len__()``,

    ``values()``.

``getPositionalArguments()``:

    I'm not sure what the equivalent would be, as there are no

    positional arguments during instantiation (it doesn't fit into

    WSGI).  Maybe ``wsgiorg.urlvars``?

``retry()``, ``supportsRetry()``:

    Creates a new request that can be used to retry a request.

    Similar to ``req.copy()``.

``close()``, ``hold(obj)``: 

    This closes resources associated with the request, including any

    "held" objects.  There's nothing similar.

Response

--------

``authUser``:

    Not sure what this is or does.

``reset()``:

    No direct equivalent; you'd have to do ``res.headers = [];

    res.body = ''; res.status = 200``

``setCookie(name, value, **kw)``:

    Is ``res.set_cookie(...)``.

``getCookie(name)``:

    No equivalent.  Hm.

``expireCookie(name)``:

    Is ``res.delete_cookie(name)``.

``appendToCookie(name, value)``:

    This appends the value to any existing cookie (separating values

    with a colon).  WebOb does not do this.

``setStatus(status)``:

    Availble by setting ``res.status`` (can be set to an integer or a

    string of "code reason").

``getHeader(name, default=None)``:

    Is ``res.headers.get(name)``.

``getStatus()``:

    Is ``res.status_int`` (or ``res.status`` to include reason)

``addHeader(name, value)``:

    Is ``res.headers.add(name, value)`` (in Zope and WebOb, this does

    not clobber any previous value).

``getHeaders()``:

    Is ``res.headerlist``.

``setHeader(name, value)``:

    Is ``res.headers[name] = value``.

``getStatusString()``:

    Is ``res.status``.

``consumeBody()``:

    This consumes any non-string body to turn the body into a single

    string.  Any access to ``res.body`` will do this (e.g., when you

    have set the ``res.app_iter``).

``internalError()``:

    This is available with ``webob.exc.HTTP*()``.

``handleException(exc_info)``:

    This is provided with a tool like ``paste.exceptions``.