This document points out some of the API differences between the
Request and Response object, and the objects in other systems.
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).
- 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.
- 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.
This is a quick summary from reading the Django documentation.
- 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 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.
- Constructor:
- Somewhat different. WebOb takes any keyword arguments as
attribute assignments. Django only takes a couple arguments. The
mimetype argument is content_type, and content_type is
the entire Content-Type header (including charset).
- 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
- flush(), tell():
- Not available
- content:
- Use res.body for the str value, res.unicode_body for
the unicode value
These are generally like webob.exc objects.
HttpResponseNotModified is HTTPNotModified; this naming
translation generally works.
The CherryPy request object is also used by
TurboGears 1.x.
- 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
From information from the wiki.
- 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 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.
- 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.
Probably not that many people know about this library, which is a
offshoot of Pocoo, 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.
- 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:
- In res.body (settable as res.body or res.app_iter)
- status:
- In res.status_int
- mimetype:
- In res.content_type
From the Zope 3 interfaces for the Request
and Response.
- 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.
- 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.
Some key attributes from the mod_python
request object.
- req.uri:
- In req.path.
- req.user:
- In req.remote_user.
- req.get_remote_host():
- In req.environ['REMOTE_ADDR'] or req.remote_addr.
- req.headers_in.get('referer'):
- In req.headers.get('referer') or req.referer (same pattern
for other request headers, presumably).
util.redirect or req.status = apache.HTTP_MOVED_TEMPORARILY:
from webob.exc import HTTPTemporaryRedirect
exc = HTTPTemporaryRedirect(location=url)
return exc(environ, start_response)
req.content_type = "application/x-csv" and
req.headers_out.add('Content-Disposition', 'attachment;filename=somefile.csv'):
res = req.ResponseClass()
res.content_type = 'application/x-csv'
res.headers.add('Content-Disposition', 'attachment;filename=somefile.csv')
return res(environ, start_response)
The Google App Engine `webapp <>`_ framework uses the WebOb Request
object, but does not use its Response object.
The constructor for webapp.Response does not take any arguments.
The response is created by the framework, so you don’t use it like
return Response(...), instead you use self.response. Also the
response object automatically has Cache-Control: no-cache set,
while the WebOb response does not set any cache headers.
- resp.set_status(code, message=None):
- This is handled by setting the resp.status attribute.
- resp.clear():
- You’d do resp.body = ""
- resp.wsgi_write(start_response):
- This writes the response using the start_response callback,
and using the start_response writer. The WebOb response
object is called as a WSGI app (resp(environ, start_response))
to do the equivalent.
- resp.out.write(text):
- This writes to an internal StringIO instance of the response.
This uses the ability of the standard StringIO object to hold
either unicode or str text, and so long as you are always
consistent it will encode your content (but it does not respect
your preferred encoding, it always uses UTF-8). The WebOb method
resp.write(text) is basically equivalent, and also accepts
unicode (using resp.charset for the encoding). You can also
write to resp.body_file, but it does not allow unicode.
Besides exposing a .headers attribute (based on
wsgiref.headers.Headers)
there is no other API for the webapp response object. This means the
response lacks:
- A usefully readable body or status.
- A useful constructor that makes it easy to treat responses like
objects.
- Providing a non-string app_iter for the body (like a generator).
- Parsing of the Content-Type charset.
- Getter/setters for parsed forms of headers, specifically
cache_control and last_modified.
- The cache_expires method
- set_cookie, delete_cookie, and unset_cookie. Instead
you have to simply manually set the Set-Cookie header.
- encode_content and decode_content for handling gzip encoding.
- md5_etag() for generating an etag from the body.
- Conditional responses that will return 304 based on the response and
request headers.
- The ability to serve Range request automatically.