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``

query/postvars:
    These are known as GET and POST in WSGIRequest.  These aliases are
    still available

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.

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):
    Not available; you have to use ``res.body += content``

flush() and tell():
    Also gone

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
    postvars

META:
    Is ``req.environ``

user:
    No equivalent (too connected to application model)

session:
    No equivalent

raw_post_data:
    Available with ``req.body``

__getitem__(key):
    You have to use ``req.params``

is_secure():
    No equivalent

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.queryvars 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() (+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 requests 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), 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.appication_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

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``

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

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

query_string:
    As ``req.environ['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:
    No equivalent

rfile:
    ``req.body``

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

check_timeout:
    No equivalent

collapse_body:
    No equivalent

cookie:
    Accessible through ``res.set_cookie(...)``, ``res.delete_cookie``,
    ``res.unset_cookie()``

finalize:
    No equivalent

header_list:
    As ``res.headerlist``

stream:
    No equivalent

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.queryvars`` or ``req.GET``

form:
    As ``req.postvars`` or ``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

redirect:
    Not available (response-related)

forward, wsgi_forward:
    Available with ``req.get_response(app)`` and
    ``req.call_application(app)``

res:
    No equivalent

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.queryvars`` or ``req.GET``
form:
    As ``req.postvars`` or ``req.POST``
values:
    As ``req.params``
files:
    In ``req.postvars``
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``:
    What this is, I don't know.

``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``.

``consumeBodyIter()``:
    This returns the iterable for the body, even if the body was a
    string.  Anytime you access ``res.app_iter`` you will get an
    iterable.  ``res.body`` and ``res.app_iter`` can be interchanged
    and accessed as many times as you want, unlike the Zope
    equivalents.

``setResult(result)``:
    You can achieve the same thing through ``res.body = result``, or
    ``res.app_iter = result``.  ``res.body`` accepts None, a unicode
    string (*if* you have set a charset) or a normal string.
    ``res.app_iter`` only accepts None and an interable.  You can't
    update all of a response with one call.

    Like in Zope, WebOb updates Content-Length.  Unlike Zope, it does
    not automatically calculate a charset.

