WebOb

Introduction

This document covers all the details of the Request and Response objects. It is written to be testable with doctest – this affects the flavor of the documentation, perhaps to its detriment. But it also means you can feel confident that the documentation is correct.

This is a somewhat different approach to reference documentation compared to the extracted documentation for the request and response.

Request

The primary object in WebOb is webob.Request, a wrapper around a WSGI environment.

The basic way you create a request object is simple enough:

>>> from webob import Request
>>> environ = {'wsgi.url_scheme': 'http', ...}  
>>> req = Request(environ)                      

(Note that the WSGI environment is a dictionary with a dozen required keys, so it’s a bit lengthly to show a complete example of what it would look like – usually your WSGI server will create it.)

The request object wraps the environment; it has very little internal state of its own. Instead attributes you access read and write to the environment dictionary.

You don’t have to understand the details of WSGI to use this library; this library handles those details for you. You also don’t have to use this exclusively of other libraries. If those other libraries also keep their state in the environment, multiple wrappers can coexist. Examples of libraries that can coexist include paste.wsgiwrappers.Request (used by Pylons) and yaro.Request.

The WSGI environment has a number of required variables. To make it easier to test and play around with, the Request class has a constructor that will fill in a minimal environment:

>>> req = Request.blank('/article?id=1')
>>> from pprint import pprint
>>> pprint(req.environ)
{'HTTP_HOST': 'localhost:80',
 'PATH_INFO': '/article',
 'QUERY_STRING': 'id=1',
 'REQUEST_METHOD': 'GET',
 'SCRIPT_NAME': '',
 'SERVER_NAME': 'localhost',
 'SERVER_PORT': '80',
 'SERVER_PROTOCOL': 'HTTP/1.0',
 'wsgi.errors': <open file '<stderr>', mode 'w' at ...>,
 'wsgi.input': <...IO... object at ...>,
 'wsgi.multiprocess': False,
 'wsgi.multithread': False,
 'wsgi.run_once': False,
 'wsgi.url_scheme': 'http',
 'wsgi.version': (1, 0)}

>>> hasattr(req.body_file, 'read')
True
>>> req.body
''
>>> req.method = 'PUT'
>>> req.body = 'test'
>>> hasattr(req.body_file, 'read')
True
>>> req.body
'test'

>>> req.method
'PUT'
>>> req.scheme
'http'
>>> req.script_name  # The base of the URL
''
>>> req.script_name = '/blog' # make it more interesting
>>> req.path_info    # The yet-to-be-consumed part of the URL
'/article'
>>> req.content_type # Content-Type of the request body
''
>>> print req.remote_user  # The authenticated user (there is none set)
None
>>> print req.remote_addr  # The remote IP
None
>>> req.host
'localhost:80'
>>> req.host_url
'http://localhost'
>>> req.application_url
'http://localhost/blog'
>>> req.path_url
'http://localhost/blog/article'
>>> req.url
'http://localhost/blog/article?id=1'
>>> req.path
'/blog/article'
>>> req.path_qs
'/blog/article?id=1'
>>> req.query_string
'id=1'

>>> req.relative_url('archive')
'http://localhost/blog/archive'

>>> req.path_info_peek() # Doesn't change request
'article'
>>> req.path_info_pop()  # Does change request!
'article'
>>> req.script_name
'/blog/article'
>>> req.path_info
''

>>> req.headers['Content-Type'] = 'application/x-www-urlencoded'
>>> sorted(req.headers.items())
[('Content-Length', '4'), ('Content-Type', 'application/x-www-urlencoded'), ('Host', 'localhost:80')]
>>> req.environ['CONTENT_TYPE']
'application/x-www-urlencoded'

>>> req = Request.blank('/test?check=a&check=b&name=Bob')
>>> req.GET
MultiDict([(u'check', u'a'), (u'check', u'b'), (u'name', u'Bob')])
>>> req.GET['check']
u'b'
>>> req.GET.getall('check')
[u'a', u'b']
>>> req.GET.items()
[(u'check', u'a'), (u'check', u'b'), (u'name', u'Bob')]

>>> req.POST
<NoVars: Not a form request>
>>> req.POST.items()  # NoVars can be read like a dict, but not written
[]
>>> req.method = 'POST'
>>> req.body = 'name=Joe&email=joe@example.com'
>>> req.POST
MultiDict([(u'name', u'Joe'), (u'email', u'joe@example.com')])
>>> req.POST['name']
u'Joe'

>>> req.params
NestedMultiDict([(u'check', u'a'), (u'check', u'b'), (u'name', u'Bob'), (u'name', u'Joe'), (u'email', u'joe@example.com')])
>>> req.params['name']
u'Bob'
>>> req.params.getall('name')
[u'Bob', u'Joe']
>>> for name, value in req.params.items():
...     print '%s: %r' % (name, value)
check: u'a'
check: u'b'
name: u'Bob'
name: u'Joe'
email: u'joe@example.com'

>>> req = Request.blank('/test?check=a&check=b&name=Bob')
>>> req.method = 'PUT'
>>> req.body = body = 'var1=value1&var2=value2&rep=1&rep=2'
>>> req.environ['CONTENT_LENGTH'] = str(len(req.body))
>>> req.environ['CONTENT_TYPE'] = 'application/x-www-form-urlencoded'
>>> req.GET
MultiDict([(u'check', u'a'), (u'check', u'b'), (u'name', u'Bob')])
>>> req.POST
MultiDict([(u'var1', u'value1'), (u'var2', u'value2'), (u'rep', u'1'), (u'rep', u'2')])

>>> req.charset = 'utf8'
>>> req.GET
MultiDict([(u'check', u'a'), (u'check', u'b'), (u'name', u'Bob')])

>>> req.headers['Cookie'] = 'test=value'
>>> req.cookies
MultiDict([(u'test', u'value')])

>>> 'text/html' in req.accept
True

>>> req.accept = 'text/html;q=0.5, application/xhtml+xml;q=1'
>>> req.accept
<MIMEAccept('text/html;q=0.5, application/xhtml+xml')>
>>> 'text/html' in req.accept
True

>>> req.accept.best_match(['text/html', 'application/xhtml+xml'])
'application/xhtml+xml'

>>> req.accept.best_matches()
['application/xhtml+xml', 'text/html']

>>> req.accept_language = 'es, pt-BR'
>>> req.accept_language.best_matches('en-US')
['es', 'pt-BR', 'en-US']
>>> req.accept_language.best_matches('es')
['es']

>>> server_token = 'opaque-token'
>>> server_token in req.if_none_match # You shouldn't return 304
False
>>> req.if_none_match = server_token
>>> req.if_none_match
<ETag opaque-token>
>>> server_token in req.if_none_match # You *should* return 304
True

>>> from webob import UTC
>>> from datetime import datetime
>>> req.if_modified_since = datetime(2006, 1, 1, 12, 0, tzinfo=UTC)
>>> req.headers['If-Modified-Since']
'Sun, 01 Jan 2006 12:00:00 GMT'
>>> server_modified = datetime(2005, 1, 1, 12, 0, tzinfo=UTC)
>>> req.if_modified_since and req.if_modified_since >= server_modified
True

>>> req.if_range
<Empty If-Range>
>>> req.if_range.match(etag='some-etag', last_modified=datetime(2005, 1, 1, 12, 0))
True
>>> req.if_range = 'opaque-etag'
>>> req.if_range.match(etag='other-etag')
False
>>> req.if_range.match(etag='opaque-etag')
True

>>> from webob import Response
>>> res = Response(etag='opaque-etag')
>>> req.if_range.match_response(res)
True

>>> req.range = 'bytes=0-100'
>>> req.range
<Range ranges=(0, 101)>
>>> cr = req.range.content_range(length=1000)
>>> cr.start, cr.stop, cr.length
(0, 101, 1000)

>>> server_token in req.if_match # No If-Match means everything is ok
True
>>> req.if_match = server_token
>>> server_token in req.if_match # Still OK
True
>>> req.if_match = 'other-token'
>>> # Not OK, should return 412 Precondition Failed:
>>> server_token in req.if_match
False

>>> req = Request.blank('/')
>>> def wsgi_app(environ, start_response):
...     start_response('200 OK', [('Content-type', 'text/plain')])
...     return ['Hi!']
>>> req.call_application(wsgi_app)
('200 OK', [('Content-type', 'text/plain')], ['Hi!'])

>>> res = req.get_response(wsgi_app)
>>> res
<Response ... 200 OK>
>>> res.status
'200 OK'
>>> res.headers
ResponseHeaders([('Content-type', 'text/plain')])
>>> res.body
'Hi!'

>>> req = Request.blank('/')
>>> req.some_attr = 'blah blah blah'
>>> new_req = Request(req.environ)
>>> new_req.some_attr
'blah blah blah'
>>> req.environ['webob.adhoc_attrs']
{'some_attr': 'blah blah blah'}

Response

The webob.Response object contains everything necessary to make a WSGI response. Instances of it are in fact WSGI applications, but it can also represent the result of calling a WSGI application (as noted in Calling WSGI Applications). It can also be a way of accumulating a response in your WSGI application.

A WSGI response is made up of a status (like 200 OK), a list of headers, and a body (or iterator that will produce a body).

>>> from webob import Response
>>> res = Response()
>>> res.status
'200 OK'
>>> res.headerlist
[('Content-Type', 'text/html; charset=UTF-8'), ('Content-Length', '0')]
>>> res.body
''

>>> res.status = 404
>>> res.status
'404 Not Found'
>>> res.status_code
404
>>> res.headerlist = [('Content-type', 'text/html')]
>>> res.body = 'test'
>>> print res
404 Not Found
Content-type: text/html
Content-Length: 4

test
>>> res.body = u"test"
Traceback (most recent call last):
    ...
TypeError: You cannot set Response.body to a unicode object (use Response.text)
>>> res.text = u"test"
Traceback (most recent call last):
    ...
AttributeError: You cannot access Response.text unless charset is set
>>> res.charset = 'utf8'
>>> res.text = u"test"
>>> res.body
'test'

>>> res.headers
ResponseHeaders([('Content-Type', 'text/html; charset=utf8'), ('Content-Length', '4')])

>>> res = Response(content_type='text/plain', charset=None)
>>> f = res.body_file
>>> f.write('hey')
>>> f.write(u'test')
Traceback (most recent call last):
  . . .
TypeError: You can only write unicode to Response if charset has been set
>>> f.encoding
>>> res.charset = 'utf8'
>>> f.encoding
'utf8'
>>> f.write(u'test')
>>> res.app_iter
['', 'hey', 'test']
>>> res.body
'heytest'

>>> res = Response()
>>> res.content_type = 'text/html'
>>> res.charset = 'utf8'
>>> res.content_type
'text/html'
>>> res.headers['content-type']
'text/html; charset=utf8'
>>> res.content_type = 'application/atom+xml'
>>> res.content_type_params
{'charset': 'utf8'}
>>> res.content_type_params = {'type': 'entry', 'charset': 'utf8'}
>>> res.headers['content-type']
'application/atom+xml; charset=utf8; type=entry'

>>> # Used with a redirect:
>>> res.location = 'http://localhost/foo'

>>> # Indicates that the server accepts Range requests:
>>> res.accept_ranges = 'bytes'

>>> # Used by caching proxies to tell the client how old the
>>> # response is:
>>> res.age = 120

>>> # Show what methods the client can do; typically used in
>>> # a 405 Method Not Allowed response:
>>> res.allow = ['GET', 'PUT']

>>> # Set the cache-control header:
>>> res.cache_control.max_age = 360
>>> res.cache_control.no_transform = True

>>> # Tell the browser to treat the response as an attachment:
>>> res.content_disposition = 'attachment; filename=foo.xml'

>>> # Used if you had gzipped the body:
>>> res.content_encoding = 'gzip'

>>> # What language(s) are in the content:
>>> res.content_language = ['en']

>>> # Seldom used header that tells the client where the content
>>> # is from:
>>> res.content_location = 'http://localhost/foo'

>>> # Seldom used header that gives a hash of the body:
>>> res.content_md5 = 'big-hash'

>>> # Means we are serving bytes 0-500 inclusive, out of 1000 bytes total:
>>> # you can also use the range setter shown earlier
>>> res.content_range = (0, 501, 1000)

>>> # The length of the content; set automatically if you set
>>> # res.body:
>>> res.content_length = 4

>>> # Used to indicate the current date as the server understands
>>> # it:
>>> res.date = datetime.now()

>>> # The etag:
>>> res.etag = 'opaque-token'
>>> # You can generate it from the body too:
>>> res.md5_etag()
>>> res.etag
'1B2M2Y8AsgTpgAmY7PhCfg'

>>> # When this page should expire from a cache (Cache-Control
>>> # often works better):
>>> import time
>>> res.expires = time.time() + 60*60 # 1 hour

>>> # When this was last modified, of course:
>>> res.last_modified = datetime(2007, 1, 1, 12, 0, tzinfo=UTC)

>>> # Used with 503 Service Unavailable to hint the client when to
>>> # try again:
>>> res.retry_after = 160

>>> # Indicate the server software:
>>> res.server = 'WebOb/1.0'

>>> # Give a list of headers that the cache should vary on:
>>> res.vary = ['Cookie']

>>> for name, value in res.headerlist:
...     print '%s: %s' % (name, value)
Content-Type: application/atom+xml; charset=utf8; type=entry
Location: http://localhost/foo
Accept-Ranges: bytes
Age: 120
Allow: GET, PUT
Cache-Control: max-age=360, no-transform
Content-Disposition: attachment; filename=foo.xml
Content-Encoding: gzip
Content-Language: en
Content-Location: http://localhost/foo
Content-MD5: big-hash
Content-Range: bytes 0-500/1000
Content-Length: 4
Date: ... GMT
ETag: ...
Expires: ... GMT
Last-Modified: Mon, 01 Jan 2007 12:00:00 GMT
Retry-After: 160
Server: WebOb/1.0
Vary: Cookie

>>> res = Response()
>>> res.cache_expires(10)
>>> res.headers['Cache-Control']
'max-age=10'
>>> res.cache_expires(0)
>>> res.headers['Cache-Control']
'max-age=0, must-revalidate, no-cache, no-store'
>>> res.headers['Expires']
'... GMT'

>>> from webob import *
>>> res = Response()
>>> res.cache_expires(2*day+4*hour)
>>> res.headers['Cache-Control']
'max-age=187200'

>>> res.set_cookie('key', 'value', max_age=360, path='/',
...                domain='example.org', secure=True)
>>> res.headers['Set-Cookie']
'key=value; Domain=example.org; Max-Age=360; Path=/; expires=... GMT; secure'
>>> # To delete a cookie previously set in the client:
>>> res.delete_cookie('bad_cookie')
>>> res.headers['Set-Cookie']
'bad_cookie=; Max-Age=0; Path=/; expires=... GMT'

>>> res.unset_cookie('key')
>>> res.unset_cookie('bad_cookie')
>>> print res.headers.get('Set-Cookie')
None

>>> req = Request.blank('/')
>>> status, headers, app_iter = req.call_application(res)

>>> def my_app(environ, start_response):
...     req = Request(environ)
...     res = Response()
...     res.content_type = 'text/plain'
...     parts = []
...     for name, value in sorted(req.environ.items()):
...         parts.append('%s: %r' % (name, value))
...     res.body = '\n'.join(parts)
...     return res(environ, start_response)
>>> req = Request.blank('/')
>>> res = req.get_response(my_app)
>>> print res
200 OK
Content-Type: text/plain; charset=UTF-8
Content-Length: ...

HTTP_HOST: 'localhost:80'
PATH_INFO: '/'
QUERY_STRING: ''
REQUEST_METHOD: 'GET'
SCRIPT_NAME: ''
SERVER_NAME: 'localhost'
SERVER_PORT: '80'
SERVER_PROTOCOL: 'HTTP/1.0'
wsgi.errors: <open file '<stderr>', mode 'w' at ...>
wsgi.input: <...IO... object at ...>
wsgi.multiprocess: False
wsgi.multithread: False
wsgi.run_once: False
wsgi.url_scheme: 'http'
wsgi.version: (1, 0)

Exceptions

In addition to Request and Response objects, there are a set of Python exceptions for different HTTP responses (3xx, 4xx, 5xx codes).

These provide a simple way to provide these non-200 response. A very simple body is provided.

>>> from webob.exc import *
>>> exc = HTTPTemporaryRedirect(location='foo')
>>> req = Request.blank('/path/to/something')
>>> print str(req.get_response(exc)).strip()
307 Temporary Redirect
Location: http://localhost/path/to/foo
Content-Length: 126
Content-Type: text/plain; charset=UTF-8

307 Temporary Redirect

The resource has been moved to http://localhost/path/to/foo; you should be redirected automatically.

Note that only if there’s an Accept: text/html header in the request will an HTML response be given:

>>> req.accept += 'text/html'
>>> print str(req.get_response(exc)).strip()
307 Temporary Redirect
Location: http://localhost/path/to/foo
Content-Length: 270
Content-Type: text/html; charset=UTF-8

<html>
 <head>
  <title>307 Temporary Redirect</title>
 </head>
 <body>
  <h1>307 Temporary Redirect</h1>
  The resource has been moved to <a href="http://localhost/path/to/foo">http://localhost/path/to/foo</a>;
you should be redirected automatically.


 </body>
</html>

This is taken from paste.httpexceptions, and if you have Paste installed then these exceptions will be subclasses of the Paste exceptions.

>>> class AppResponse(Response):
...     default_content_type = 'text/html'
...     default_conditional_response = True
>>> res = AppResponse(body='0123456789',
...                   last_modified=datetime(2005, 1, 1, 12, 0, tzinfo=UTC))
>>> req = Request.blank('/')
>>> req.if_modified_since = datetime(2006, 1, 1, 12, 0, tzinfo=UTC)
>>> req.get_response(res)
<Response ... 304 Not Modified>
>>> del req.if_modified_since
>>> res.etag = 'opaque-tag'
>>> req.if_none_match = 'opaque-tag'
>>> req.get_response(res)
<Response ... 304 Not Modified>

>>> req.if_none_match = '*'
>>> 'x' in req.if_none_match
True
>>> req.if_none_match = req.if_none_match
>>> 'x' in req.if_none_match
True
>>> req.if_none_match = None
>>> 'x' in req.if_none_match
False
>>> req.if_match = None
>>> 'x' in req.if_match
True
>>> req.if_match = req.if_match
>>> 'x' in req.if_match
True
>>> req.headers.get('If-Match')
'*'

>>> del req.if_none_match

>>> req.range = (1, 5)
>>> result = req.get_response(res)
>>> result.headers['content-range']
'bytes 1-4/10'
>>> result.body
'1234'

Request

class webob.request.BaseRequest(environ, charset=None, unicode_errors=None, decode_param_names=None, **kw)

GET

Return a MultiDict containing all the variables from the QUERY_STRING.

POST

Return a MultiDict containing all the variables from a form request. Returns an empty dict-like object for non-form requests.

Form requests are typically POST requests, however PUT & PATCH requests with an appropriate Content-Type are also supported.

ResponseClass

alias of Response

accept

Gets and sets the Accept header (HTTP spec section 14.1).

accept_charset

Gets and sets the Accept-Charset header (HTTP spec section 14.2).

accept_encoding

Gets and sets the Accept-Encoding header (HTTP spec section 14.3).

accept_language

Gets and sets the Accept-Language header (HTTP spec section 14.4).

application_url

The URL including SCRIPT_NAME (no PATH_INFO or query string)

as_bytes(skip_body=False)

Return HTTP bytes representing this request. If skip_body is True, exclude the body. If skip_body is an integer larger than one, skip body only if its length is bigger than that number.

authorization

Gets and sets the Authorization header (HTTP spec section 14.8). Converts it using parse_auth and serialize_auth.

classmethod blank(path, environ=None, base_url=None, headers=None, POST=None, **kw)

Create a blank request environ (and Request wrapper) with the given path (path should be urlencoded), and any keys from environ.

The path will become path_info, with any query string split off and used.

All necessary keys will be added to the environ, but the values you pass in will take precedence. If you pass in base_url then wsgi.url_scheme, HTTP_HOST, and SCRIPT_NAME will be filled in from that value.

Any extra keyword will be passed to __init__.

body

Return the content of the request body.

body_file

Input stream of the request (wsgi.input). Setting this property resets the content_length and seekable flag (unlike setting req.body_file_raw).

body_file_raw

Gets and sets the wsgi.input key in the environment.

body_file_seekable

Get the body of the request (wsgi.input) as a seekable file-like object. Middleware and routing applications should use this attribute over .body_file.

If you access this value, CONTENT_LENGTH will also be updated.

cache_control

Get/set/modify the Cache-Control header (HTTP spec section 14.9)

call_application(application, catch_exc_info=False)

Call the given WSGI application, returning (status_string, headerlist, app_iter)

Be sure to call app_iter.close() if it’s there.

If catch_exc_info is true, then returns (status_string, headerlist, app_iter, exc_info), where the fourth item may be None, but won’t be if there was an exception. If you don’t do this and there was an exception, the exception will be raised directly.

client_addr

The effective client IP address as a string. If the HTTP_X_FORWARDED_FOR header exists in the WSGI environ, this attribute returns the client IP address present in that header (e.g. if the header value is 192.168.1.1, 192.168.1.2, the value will be 192.168.1.1). If no HTTP_X_FORWARDED_FOR header is present in the environ at all, this attribute will return the value of the REMOTE_ADDR header. If the REMOTE_ADDR header is unset, this attribute will return the value None.

Warning

It is possible for user agents to put someone else’s IP or just any string in HTTP_X_FORWARDED_FOR as it is a normal HTTP header. Forward proxies can also provide incorrect values (private IP addresses etc). You cannot “blindly” trust the result of this method to provide you with valid data unless you’re certain that HTTP_X_FORWARDED_FOR has the correct values. The WSGI server must be behind a trusted proxy for this to be true.

content_length

Gets and sets the Content-Length header (HTTP spec section 14.13). Converts it using int.

content_type

Return the content type, but leaving off any parameters (like charset, but also things like the type in application/atom+xml; type=entry)

If you set this property, you can include parameters, or if you don’t include any parameters in the value then existing parameters will be preserved.

cookies

Return a dictionary of cookies as found in the request.

copy()

Copy the request and environment object.

This only does a shallow copy, except of wsgi.input

copy_body()

Copies the body, in cases where it might be shared with another request object and that is not desired.

This copies the body in-place, either into a BytesIO object or a temporary file.

copy_get()

Copies the request and environment object, but turning this request into a GET along the way. If this was a POST request (or any other verb) then it becomes GET, and the request body is thrown away.

date

Gets and sets the Date header (HTTP spec section 14.8). Converts it using HTTP date.

domain

Returns the domain portion of the host value. Equivalent to:

domain = request.host
if ':' in domain:
    domain = domain.split(':', 1)[0]

This will be equivalent to the domain portion of the HTTP_HOST value in the environment if it exists, or the SERVER_NAME value in the environment if it doesn’t. For example, if the environment contains an HTTP_HOST value of foo.example.com:8000, request.domain will return foo.example.com.

Note that this value cannot be set on the request. To set the host value use webob.request.Request.host() instead.

classmethod from_bytes(b)

Create a request from HTTP bytes data. If the bytes contain extra data after the request, raise a ValueError.

classmethod from_file(fp)

Read a request from a file-like object (it must implement .read(size) and .readline()).

It will read up to the end of the request, not the end of the file (unless the request is a POST or PUT and has no Content-Length, in that case, the entire file is read).

This reads the request as represented by str(req); it may not read every valid HTTP request properly.

get_response(application=None, catch_exc_info=False)

Like .call_application(application), except returns a response object with .status, .headers, and .body attributes.

This will use self.ResponseClass to figure out the class of the response object to return.

If application is not given, this will send the request to self.make_default_send_app()

headers

All the request headers as a case-insensitive dictionary-like object.

host

Host name provided in HTTP_HOST, with fall-back to SERVER_NAME

host_port

The effective server port number as a string. If the HTTP_HOST header exists in the WSGI environ, this attribute returns the port number present in that header. If the HTTP_HOST header exists but contains no explicit port number: if the WSGI url scheme is “https” , this attribute returns “443”, if the WSGI url scheme is “http”, this attribute returns “80” . If no HTTP_HOST header is present in the environ at all, this attribute will return the value of the SERVER_PORT header (which is guaranteed to be present).

host_url

The URL through the host (no path)

http_version

Gets and sets the SERVER_PROTOCOL key in the environment.

if_match

Gets and sets the If-Match header (HTTP spec section 14.24). Converts it as a Etag.

if_modified_since

Gets and sets the If-Modified-Since header (HTTP spec section 14.25). Converts it using HTTP date.

if_none_match

Gets and sets the If-None-Match header (HTTP spec section 14.26). Converts it as a Etag.

if_range

Gets and sets the If-Range header (HTTP spec section 14.27). Converts it using IfRange object.

if_unmodified_since

Gets and sets the If-Unmodified-Since header (HTTP spec section 14.28). Converts it using HTTP date.

is_body_readable

webob.is_body_readable is a flag that tells us that we can read the input stream even though CONTENT_LENGTH is missing. This allows FakeCGIBody to work and can be used by servers to support chunked encoding in requests. For background see https://bitbucket.org/ianb/webob/issue/6

is_body_seekable

Gets and sets the webob.is_body_seekable key in the environment.

is_xhr

Is X-Requested-With header present and equal to XMLHttpRequest?

Note: this isn’t set by every XMLHttpRequest request, it is only set if you are using a Javascript library that sets it (or you set the header yourself manually). Currently Prototype and jQuery are known to set this header.

json

Access the body of the request as JSON

json_body

Access the body of the request as JSON

make_body_seekable()

This forces environ['wsgi.input'] to be seekable. That means that, the content is copied into a BytesIO or temporary file and flagged as seekable, so that it will not be unnecessarily copied again.

After calling this method the .body_file is always seeked to the start of file and .content_length is not None.

The choice to copy to BytesIO is made from self.request_body_tempfile_limit

make_tempfile()

Create a tempfile to store big request body. This API is not stable yet. A ‘size’ argument might be added.

max_forwards

Gets and sets the Max-Forwards header (HTTP spec section 14.31). Converts it using int.

method

Gets and sets the REQUEST_METHOD key in the environment.

params

A dictionary-like object containing both the parameters from the query string and request body.

path

The path of the request, without host or query string

path_info

Gets and sets the PATH_INFO key in the environment.

path_info_peek()

Returns the next segment on PATH_INFO, or None if there is no next segment. Doesn’t modify the environment.

path_info_pop(pattern=None)

‘Pops’ off the next segment of PATH_INFO, pushing it onto SCRIPT_NAME, and returning the popped segment. Returns None if there is nothing left on PATH_INFO.

Does not return '' when there’s an empty segment (like /path//path); these segments are just ignored.

Optional pattern argument is a regexp to match the return value before returning. If there is no match, no changes are made to the request and None is returned.

path_qs

The path of the request, without host but with query string

path_url

The URL including SCRIPT_NAME and PATH_INFO, but not QUERY_STRING

pragma

Gets and sets the Pragma header (HTTP spec section 14.32).

query_string

Gets and sets the QUERY_STRING key in the environment.

range

Gets and sets the Range header (HTTP spec section 14.35). Converts it using Range object.

referer

Gets and sets the Referer header (HTTP spec section 14.36).

referrer

Gets and sets the Referer header (HTTP spec section 14.36).

relative_url(other_url, to_application=False)

Resolve other_url relative to the request URL.

If to_application is True, then resolve it relative to the URL with only SCRIPT_NAME

remote_addr

Gets and sets the REMOTE_ADDR key in the environment.

remote_user

Gets and sets the REMOTE_USER key in the environment.

remove_conditional_headers(remove_encoding=True, remove_range=True, remove_match=True, remove_modified=True)

Remove headers that make the request conditional.

These headers can cause the response to be 304 Not Modified, which in some cases you may not want to be possible.

This does not remove headers like If-Match, which are used for conflict detection.

scheme

Gets and sets the wsgi.url_scheme key in the environment.

script_name

Gets and sets the SCRIPT_NAME key in the environment.

send(application=None, catch_exc_info=False)

Like .call_application(application), except returns a response object with .status, .headers, and .body attributes.

This will use self.ResponseClass to figure out the class of the response object to return.

If application is not given, this will send the request to self.make_default_send_app()

server_name

Gets and sets the SERVER_NAME key in the environment.

server_port

Gets and sets the SERVER_PORT key in the environment. Converts it using int.

str_GET

<Deprecated attribute None>

str_POST

<Deprecated attribute None>

str_cookies

<Deprecated attribute None>

str_params

<Deprecated attribute None>

text

Get/set the text value of the body

upath_info

Gets and sets the PATH_INFO key in the environment.

url

The full request URL, including QUERY_STRING

url_encoding

Gets and sets the webob.url_encoding key in the environment.

urlargs

Return any positional variables matched in the URL.

Takes values from environ['wsgiorg.routing_args']. Systems like routes set this value.

urlvars

Return any named variables matched in the URL.

Takes values from environ['wsgiorg.routing_args']. Systems like routes set this value.

uscript_name

Gets and sets the SCRIPT_NAME key in the environment.

user_agent

Gets and sets the User-Agent header (HTTP spec section 14.43).

Response

class webob.response.Response(body=None, status=None, headerlist=None, app_iter=None, content_type=None, conditional_response=None, **kw)

Represents a WSGI response

accept_ranges

Gets and sets the Accept-Ranges header (HTTP spec section 14.5).

age

Gets and sets the Age header (HTTP spec section 14.6). Converts it using int.

allow

Gets and sets the Allow header (HTTP spec section 14.7). Converts it using list.

app_iter

Returns the app_iter of the response.

If body was set, this will create an app_iter from that body (a single-item list)

app_iter_range(start, stop)

Return a new app_iter built from the response app_iter, that serves up only the given start:stop range.

body

The body of the response, as a str. This will read in the entire app_iter if necessary.

body_file

A file-like object that can be used to write to the body. If you passed in a list app_iter, that app_iter will be modified by writes.

cache_control

Get/set/modify the Cache-Control header (HTTP spec section 14.9)

charset

Get/set the charset (in the Content-Type)

conditional_response_app(environ, start_response)

Like the normal __call__ interface, but checks conditional headers:

• If-Modified-Since (304 Not Modified; only on GET, HEAD)
• If-None-Match (304 Not Modified; only on GET, HEAD)
• Range (406 Partial Content; only on GET, HEAD)

content_disposition

Gets and sets the Content-Disposition header (HTTP spec section 19.5.1).

content_encoding

Gets and sets the Content-Encoding header (HTTP spec section 14.11).

content_language

Gets and sets the Content-Language header (HTTP spec section 14.12). Converts it using list.

content_length

Gets and sets the Content-Length header (HTTP spec section 14.17). Converts it using int.

content_location

Gets and sets the Content-Location header (HTTP spec section 14.14).

content_md5

Gets and sets the Content-MD5 header (HTTP spec section 14.14).

content_range

Gets and sets the Content-Range header (HTTP spec section 14.16). Converts it using ContentRange object.

content_type

Get/set the Content-Type header (or None), without the charset or any parameters.

If you include parameters (or ; at all) when setting the content_type, any existing parameters will be deleted; otherwise they will be preserved.

content_type_params

A dictionary of all the parameters in the content type.

(This is not a view, set to change, modifications of the dict would not be applied otherwise)

copy()

Makes a copy of the response

date

Gets and sets the Date header (HTTP spec section 14.18). Converts it using HTTP date.

delete_cookie(key, path='/', domain=None)

Delete a cookie from the client. Note that path and domain must match how the cookie was originally set.

This sets the cookie to the empty string, and max_age=0 so that it should expire immediately.

encode_content(encoding='gzip', lazy=False)

Encode the content with the given encoding (only gzip and identity are supported).

etag

Gets and sets the ETag header (HTTP spec section 14.19). Converts it using Entity tag.

expires

Gets and sets the Expires header (HTTP spec section 14.21). Converts it using HTTP date.

classmethod from_file(fp)

Reads a response from a file-like object (it must implement .read(size) and .readline()).

It will read up to the end of the response, not the end of the file.

This reads the response as represented by str(resp); it may not read every valid HTTP response properly. Responses must have a Content-Length

headerlist

The list of response headers

headers

The headers in a dictionary-like object

json

Access the body of the response as JSON

json_body

Access the body of the response as JSON

last_modified

Gets and sets the Last-Modified header (HTTP spec section 14.29). Converts it using HTTP date.

location

Gets and sets the Location header (HTTP spec section 14.30).

md5_etag(body=None, set_content_md5=False)

Generate an etag for the response object using an MD5 hash of the body (the body parameter, or self.body if not given)

Sets self.etag If set_content_md5 is True sets self.content_md5 as well

merge_cookies(resp)

Merge the cookies that were set on this response with the given resp object (which can be any WSGI application).

If the resp is a webob.Response object, then the other object will be modified in-place.

pragma

Gets and sets the Pragma header (HTTP spec section 14.32).

retry_after

Gets and sets the Retry-After header (HTTP spec section 14.37). Converts it using HTTP date or delta seconds.

server

Gets and sets the Server header (HTTP spec section 14.38).

set_cookie(key, value='', max_age=None, path='/', domain=None, secure=False, httponly=False, comment=None, expires=None, overwrite=False)

Set (add) a cookie for the response.

Arguments are:

key

The cookie name.

value

The cookie value, which should be a string or None. If value is None, it’s equivalent to calling the webob.response.Response.unset_cookie() method for this cookie key (it effectively deletes the cookie on the client).

max_age

An integer representing a number of seconds or None. If this value is an integer, it is used as the Max-Age of the generated cookie. If expires is not passed and this value is an integer, the max_age value will also influence the Expires value of the cookie (Expires will be set to now + max_age). If this value is None, the cookie will not have a Max-Age value (unless expires is also sent).

path

A string representing the cookie Path value. It defaults to /.

domain

A string representing the cookie Domain, or None. If domain is None, no Domain value will be sent in the cookie.

secure

A boolean. If it’s True, the secure flag will be sent in the cookie, if it’s False, the secure flag will not be sent in the cookie.

httponly

A boolean. If it’s True, the HttpOnly flag will be sent in the cookie, if it’s False, the HttpOnly flag will not be sent in the cookie.

comment

A string representing the cookie Comment value, or None. If comment is None, no Comment value will be sent in the cookie.

expires

A datetime.timedelta object representing an amount of time or the value None. A non-None value is used to generate the Expires value of the generated cookie. If max_age is not passed, but this value is not None, it will influence the Max-Age header (Max-Age will be ‘expires_value - datetime.utcnow()’). If this value is None, the Expires cookie value will be unset (unless max_age is also passed).

overwrite

If this key is True, before setting the cookie, unset any existing cookie.

status

The status string

status_code

The status as an integer

status_int

The status as an integer

text

Get/set the text value of the body (using the charset of the Content-Type)

ubody

Deprecated alias for .text

unicode_body

Deprecated alias for .text

unset_cookie(key, strict=True)

Unset a cookie with the given name (remove it from the response).

vary

Gets and sets the Vary header (HTTP spec section 14.44). Converts it using list.

www_authenticate

Gets and sets the WWW-Authenticate header (HTTP spec section 14.47). Converts it using parse_auth and serialize_auth.

class webob.response.AppIterRange(app_iter, start, stop)

Wraps an app_iter, returning just a range of bytes

Headers

value1; q=0.5, value2; q=0

Misc Functions and Internals

webob.html_escape(s)

HTML-escape a string or object

This converts any non-string objects passed into it to strings (actually, using unicode()). All values returned are non-unicode strings (using &#num; entities for all non-ASCII characters).

None is treated specially, and returns the empty string.

class webob.headers.ResponseHeaders(*args, **kw)

Dictionary view on the response headerlist. Keys are normalized for case and whitespace.

class webob.headers.EnvironHeaders(environ)

An object that represents the headers as present in a WSGI environment.

This object is a wrapper (with no internal state) for a WSGI request object, representing the CGI-style HTTP_* keys as a dictionary. Because a CGI environment can only hold one value for each key, this dictionary is single-valued (unlike outgoing headers).

Gives a multi-value dictionary object (MultiDict) plus several wrappers

class webob.multidict.MultiDict(*args, **kw)

An ordered dictionary that can have multiple values for each key. Adds the methods getall, getone, mixed and extend and add to the normal dictionary interface.

add(key, value)

Add the key and value, not overwriting any previous value.

dict_of_lists()

Returns a dictionary where each key is associated with a list of values.

classmethod from_fieldstorage(fs)

Create a dict from a cgi.FieldStorage instance

getall(key)

Return a list of all values matching the key (may be an empty list)

getone(key)

Get one value matching the key, raising a KeyError if multiple values were found.

mixed()

Returns a dictionary where the values are either single values, or a list of values when a key/value appears more than once in this dictionary. This is similar to the kind of dictionary often used to represent the variables in a web request.

classmethod view_list(lst)

Create a dict that is a view on the given list

class webob.multidict.NestedMultiDict(*dicts)

Wraps several MultiDict objects, treating it as one large MultiDict

class webob.multidict.NoVars(reason=None)

Represents no variables; used when no variables are applicable.

This is read-only

class webob.cachecontrol.UpdateDict

Dict that has a callback on all updates

Decorator

class webob.dec.wsgify(func=None, RequestClass=None, args=(), kwargs=None, middleware_wraps=None)

Turns a request-taking, response-returning function into a WSGI app

You can use this like:

@wsgify
def myfunc(req):
    return webob.Response('hey there')

With that myfunc will be a WSGI application, callable like app_iter = myfunc(environ, start_response). You can also call it like normal, e.g., resp = myfunc(req). (You can also wrap methods, like def myfunc(self, req).)

If you raise exceptions from webob.exc they will be turned into WSGI responses.

There are also several parameters you can use to customize the decorator. Most notably, you can use a webob.Request subclass, like:

class MyRequest(webob.Request):
    @property
    def is_local(self):
        return self.remote_addr == '127.0.0.1'
@wsgify(RequestClass=MyRequest)
def myfunc(req):
    if req.is_local:
        return Response('hi!')
    else:
        raise webob.exc.HTTPForbidden

Another customization you can add is to add args (positional arguments) or kwargs (of course, keyword arguments). While generally not that useful, you can use this to create multiple WSGI apps from one function, like:

import simplejson
def serve_json(req, json_obj):
    return Response(json.dumps(json_obj),
                    content_type='application/json')

serve_ob1 = wsgify(serve_json, args=(ob1,))
serve_ob2 = wsgify(serve_json, args=(ob2,))

You can return several things from a function:

• A webob.Response object (or subclass)
• Any WSGI application
• None, and then req.response will be used (a pre-instantiated Response object)
• A string, which will be written to req.response and then that response will be used.
• Raise an exception from webob.exc

Also see wsgify.middleware() for a way to make middleware.

You can also subclass this decorator; the most useful things to do in a subclass would be to change RequestClass or override call_func (e.g., to add req.urlvars as keyword arguments to the function).

RequestClass

alias of Request

call_func(req, *args, **kwargs)

Call the wrapped function; override this in a subclass to change how the function is called.

clone(func=None, **kw)

Creates a copy/clone of this object, but with some parameters rebound

get(url, **kw)

Run a GET request on this application, returning a Response.

This creates a request object using the given URL, and any other keyword arguments are set on the request object (e.g., last_modified=datetime.now()).

resp = myapp.get('/article?id=10')

classmethod middleware(middle_func=None, app=None, **kw)

Creates middleware

Use this like:

@wsgify.middleware
def restrict_ip(req, app, ips):
    if req.remote_addr not in ips:
        raise webob.exc.HTTPForbidden('Bad IP: %s' % req.remote_addr)
    return app

@wsgify
def app(req):
    return 'hi'

wrapped = restrict_ip(app, ips=['127.0.0.1'])

Or if you want to write output-rewriting middleware:

@wsgify.middleware
def all_caps(req, app):
    resp = req.get_response(app)
    resp.body = resp.body.upper()
    return resp

wrapped = all_caps(app)

Note that you must call req.get_response(app) to get a WebOb response object. If you are not modifying the output, you can just return the app.

As you can see, this method doesn’t actually create an application, but creates “middleware” that can be bound to an application, along with “configuration” (that is, any other keyword arguments you pass when binding the application).

post(url, POST=None, **kw)

Run a POST request on this application, returning a Response.

The second argument (POST) can be the request body (a string), or a dictionary or list of two-tuples, that give the POST body.

resp = myapp.post('/article/new',
                  dict(title='My Day',
                       content='I ate a sandwich'))

request(url, **kw)

Run a request on this application, returning a Response.

This can be used for DELETE, PUT, etc requests. E.g.:

resp = myapp.request('/article/1', method='PUT', body='New article')

Usage notes

The HTTPException class is complicated by 4 factors:

1. The content given to the exception may either be plain-text or as html-text.
2. The template may want to have string-substitutions taken from the current environ or values from incoming headers. This is especially troublesome due to case sensitivity.
3. The final output may either be text/plain or text/html mime-type as requested by the client application.
4. Each exception has a default explanation, but those who raise exceptions may want to provide additional detail.

Subclass attributes and call parameters are designed to provide an easier path through the complications.

Attributes:

code

the HTTP status code for the exception

title

remainder of the status line (stuff after the code)

explanation

a plain-text explanation of the error message that is not subject to environment or header substitutions; it is accessible in the template via %(explanation)s

detail

a plain-text message customization that is not subject to environment or header substitutions; accessible in the template via %(detail)s

body_template

a content fragment (in HTML) used for environment and header substitution; the default template includes both the explanation and further detail provided in the message

Parameters:

detail

a plain-text override of the default detail

headers

a list of (k,v) header pairs

comment

a plain-text additional information which is usually stripped/hidden for end-users

body_template

a string.Template object containing a content fragment in HTML that frames the explanation and further detail

To override the template (which is HTML content) or the plain-text explanation, one must subclass the given exception; or customize it after it has been created. This particular breakdown of a message into explanation, detail and template allows both the creation of plain-text and html messages for various clients as well as error-free substitution of environment variables and headers.

The subclasses of _HTTPMove (HTTPMultipleChoices, HTTPMovedPermanently, HTTPFound, HTTPSeeOther, HTTPUseProxy and HTTPTemporaryRedirect) are redirections that require a Location field. Reflecting this, these subclasses have two additional keyword arguments: location and add_slash.

Parameters:

location

to set the location immediately

add_slash

set to True to redirect to the same URL as the request, except with a / appended

Relative URLs in the location will be resolved to absolute.

References:

HTTP Exceptions

exception webob.exc.HTTPException(message, wsgi_response)

exception webob.exc.WSGIHTTPException(detail=None, headers=None, comment=None, body_template=None, **kw)

exception webob.exc.HTTPError(detail=None, headers=None, comment=None, body_template=None, **kw)

base class for status codes in the 400’s and 500’s

This is an exception which indicates that an error has occurred, and that any work in progress should not be committed. These are typically results in the 400’s and 500’s.

exception webob.exc.HTTPRedirection(detail=None, headers=None, comment=None, body_template=None, **kw)

base class for 300’s status code (redirections)

This is an abstract base class for 3xx redirection. It indicates that further action needs to be taken by the user agent in order to fulfill the request. It does not necessarly signal an error condition.

exception webob.exc.HTTPOk(detail=None, headers=None, comment=None, body_template=None, **kw)

Base class for the 200’s status code (successful responses)

code: 200, title: OK

exception webob.exc.HTTPCreated(detail=None, headers=None, comment=None, body_template=None, **kw)

subclass of HTTPOk

This indicates that request has been fulfilled and resulted in a new resource being created.

code: 201, title: Created

exception webob.exc.HTTPAccepted(detail=None, headers=None, comment=None, body_template=None, **kw)

subclass of HTTPOk

This indicates that the request has been accepted for processing, but the processing has not been completed.

code: 202, title: Accepted

exception webob.exc.HTTPNonAuthoritativeInformation(detail=None, headers=None, comment=None, body_template=None, **kw)

subclass of HTTPOk

This indicates that the returned metainformation in the entity-header is not the definitive set as available from the origin server, but is gathered from a local or a third-party copy.

code: 203, title: Non-Authoritative Information

exception webob.exc.HTTPNoContent(detail=None, headers=None, comment=None, body_template=None, **kw)

subclass of HTTPOk

This indicates that the server has fulfilled the request but does not need to return an entity-body, and might want to return updated metainformation.

code: 204, title: No Content

exception webob.exc.HTTPResetContent(detail=None, headers=None, comment=None, body_template=None, **kw)

subclass of HTTPOk

This indicates that the the server has fulfilled the request and the user agent SHOULD reset the document view which caused the request to be sent.

code: 205, title: Reset Content

exception webob.exc.HTTPPartialContent(detail=None, headers=None, comment=None, body_template=None, **kw)

subclass of HTTPOk

This indicates that the server has fulfilled the partial GET request for the resource.

code: 206, title: Partial Content

exception webob.exc._HTTPMove(detail=None, headers=None, comment=None, body_template=None, location=None, add_slash=False)

redirections which require a Location field

Since a ‘Location’ header is a required attribute of 301, 302, 303, 305 and 307 (but not 304), this base class provides the mechanics to make this easy.

You can provide a location keyword argument to set the location immediately. You may also give add_slash=True if you want to redirect to the same URL as the request, except with a / added to the end.

Relative URLs in the location will be resolved to absolute.

exception webob.exc.HTTPMultipleChoices(detail=None, headers=None, comment=None, body_template=None, location=None, add_slash=False)

subclass of _HTTPMove

This indicates that the requested resource corresponds to any one of a set of representations, each with its own specific location, and agent-driven negotiation information is being provided so that the user can select a preferred representation and redirect its request to that location.

code: 300, title: Multiple Choices

exception webob.exc.HTTPMovedPermanently(detail=None, headers=None, comment=None, body_template=None, location=None, add_slash=False)

subclass of _HTTPMove

This indicates that the requested resource has been assigned a new permanent URI and any future references to this resource SHOULD use one of the returned URIs.

code: 301, title: Moved Permanently

exception webob.exc.HTTPFound(detail=None, headers=None, comment=None, body_template=None, location=None, add_slash=False)

subclass of _HTTPMove

This indicates that the requested resource resides temporarily under a different URI.

code: 302, title: Found

exception webob.exc.HTTPSeeOther(detail=None, headers=None, comment=None, body_template=None, location=None, add_slash=False)

subclass of _HTTPMove

This indicates that the response to the request can be found under a different URI and SHOULD be retrieved using a GET method on that resource.

code: 303, title: See Other

exception webob.exc.HTTPNotModified(detail=None, headers=None, comment=None, body_template=None, **kw)

subclass of HTTPRedirection

This indicates that if the client has performed a conditional GET request and access is allowed, but the document has not been modified, the server SHOULD respond with this status code.

code: 304, title: Not Modified

exception webob.exc.HTTPUseProxy(detail=None, headers=None, comment=None, body_template=None, location=None, add_slash=False)

subclass of _HTTPMove

This indicates that the requested resource MUST be accessed through the proxy given by the Location field.

code: 305, title: Use Proxy

exception webob.exc.HTTPTemporaryRedirect(detail=None, headers=None, comment=None, body_template=None, location=None, add_slash=False)

subclass of _HTTPMove

This indicates that the requested resource resides temporarily under a different URI.

code: 307, title: Temporary Redirect

exception webob.exc.HTTPClientError(detail=None, headers=None, comment=None, body_template=None, **kw)

base class for the 400’s, where the client is in error

This is an error condition in which the client is presumed to be in-error. This is an expected problem, and thus is not considered a bug. A server-side traceback is not warranted. Unless specialized, this is a ‘400 Bad Request’

code: 400, title: Bad Request

exception webob.exc.HTTPBadRequest(detail=None, headers=None, comment=None, body_template=None, **kw)

exception webob.exc.HTTPUnauthorized(detail=None, headers=None, comment=None, body_template=None, **kw)

subclass of HTTPClientError

This indicates that the request requires user authentication.

code: 401, title: Unauthorized

exception webob.exc.HTTPPaymentRequired(detail=None, headers=None, comment=None, body_template=None, **kw)

subclass of HTTPClientError

code: 402, title: Payment Required

exception webob.exc.HTTPForbidden(detail=None, headers=None, comment=None, body_template=None, **kw)

subclass of HTTPClientError

This indicates that the server understood the request, but is refusing to fulfill it.

code: 403, title: Forbidden

exception webob.exc.HTTPNotFound(detail=None, headers=None, comment=None, body_template=None, **kw)

subclass of HTTPClientError

This indicates that the server did not find anything matching the Request-URI.

code: 404, title: Not Found

exception webob.exc.HTTPMethodNotAllowed(detail=None, headers=None, comment=None, body_template=None, **kw)

subclass of HTTPClientError

This indicates that the method specified in the Request-Line is not allowed for the resource identified by the Request-URI.

code: 405, title: Method Not Allowed

exception webob.exc.HTTPNotAcceptable(detail=None, headers=None, comment=None, body_template=None, **kw)

subclass of HTTPClientError

This indicates the resource identified by the request is only capable of generating response entities which have content characteristics not acceptable according to the accept headers sent in the request.

code: 406, title: Not Acceptable

exception webob.exc.HTTPProxyAuthenticationRequired(detail=None, headers=None, comment=None, body_template=None, **kw)

subclass of HTTPClientError

This is similar to 401, but indicates that the client must first authenticate itself with the proxy.

code: 407, title: Proxy Authentication Required

exception webob.exc.HTTPRequestTimeout(detail=None, headers=None, comment=None, body_template=None, **kw)

subclass of HTTPClientError

This indicates that the client did not produce a request within the time that the server was prepared to wait.

code: 408, title: Request Timeout

exception webob.exc.HTTPConflict(detail=None, headers=None, comment=None, body_template=None, **kw)

subclass of HTTPClientError

This indicates that the request could not be completed due to a conflict with the current state of the resource.

code: 409, title: Conflict

exception webob.exc.HTTPGone(detail=None, headers=None, comment=None, body_template=None, **kw)

subclass of HTTPClientError

This indicates that the requested resource is no longer available at the server and no forwarding address is known.

code: 410, title: Gone

exception webob.exc.HTTPLengthRequired(detail=None, headers=None, comment=None, body_template=None, **kw)

subclass of HTTPClientError

This indicates that the the server refuses to accept the request without a defined Content-Length.

code: 411, title: Length Required

exception webob.exc.HTTPPreconditionFailed(detail=None, headers=None, comment=None, body_template=None, **kw)

subclass of HTTPClientError

This indicates that the precondition given in one or more of the request-header fields evaluated to false when it was tested on the server.

code: 412, title: Precondition Failed

exception webob.exc.HTTPRequestEntityTooLarge(detail=None, headers=None, comment=None, body_template=None, **kw)

subclass of HTTPClientError

This indicates that the server is refusing to process a request because the request entity is larger than the server is willing or able to process.

code: 413, title: Request Entity Too Large

exception webob.exc.HTTPRequestURITooLong(detail=None, headers=None, comment=None, body_template=None, **kw)

subclass of HTTPClientError

This indicates that the server is refusing to service the request because the Request-URI is longer than the server is willing to interpret.

code: 414, title: Request-URI Too Long

exception webob.exc.HTTPUnsupportedMediaType(detail=None, headers=None, comment=None, body_template=None, **kw)

subclass of HTTPClientError

This indicates that the server is refusing to service the request because the entity of the request is in a format not supported by the requested resource for the requested method.

code: 415, title: Unsupported Media Type

exception webob.exc.HTTPRequestRangeNotSatisfiable(detail=None, headers=None, comment=None, body_template=None, **kw)

subclass of HTTPClientError

The server SHOULD return a response with this status code if a request included a Range request-header field, and none of the range-specifier values in this field overlap the current extent of the selected resource, and the request did not include an If-Range request-header field.

code: 416, title: Request Range Not Satisfiable

exception webob.exc.HTTPExpectationFailed(detail=None, headers=None, comment=None, body_template=None, **kw)

subclass of HTTPClientError

This indidcates that the expectation given in an Expect request-header field could not be met by this server.

code: 417, title: Expectation Failed

exception webob.exc.HTTPUnprocessableEntity(detail=None, headers=None, comment=None, body_template=None, **kw)

subclass of HTTPClientError

This indicates that the server is unable to process the contained instructions.

code: 422, title: Unprocessable Entity

exception webob.exc.HTTPLocked(detail=None, headers=None, comment=None, body_template=None, **kw)

subclass of HTTPClientError

This indicates that the resource is locked.

code: 423, title: Locked

exception webob.exc.HTTPFailedDependency(detail=None, headers=None, comment=None, body_template=None, **kw)

subclass of HTTPClientError

This indicates that the method could not be performed because the requested action depended on another action and that action failed.

code: 424, title: Failed Dependency

exception webob.exc.HTTPPreconditionRequired(detail=None, headers=None, comment=None, body_template=None, **kw)

subclass of HTTPClientError

This indicates that the origin server requires the request to be conditional. From RFC 6585, “Additional HTTP Status Codes”.

code: 428, title: Precondition Required

exception webob.exc.HTTPTooManyRequests(detail=None, headers=None, comment=None, body_template=None, **kw)

subclass of HTTPClientError

This indicates that the client has sent too many requests in a given amount of time. Useful for rate limiting.

From RFC 6585, “Additional HTTP Status Codes”.

code: 429, title: Too Many Requests

exception webob.exc.HTTPRequestHeaderFieldsTooLarge(detail=None, headers=None, comment=None, body_template=None, **kw)

subclass of HTTPClientError

This indicates that the server is unwilling to process the request because its header fields are too large. The request may be resubmitted after reducing the size of the request header fields.

From RFC 6585, “Additional HTTP Status Codes”.

code: 431, title: Request Header Fields Too Large

exception webob.exc.HTTPUnavailableForLegalReasons(detail=None, headers=None, comment=None, body_template=None, **kw)

subclass of HTTPClientError

This indicates that the server is unable to process the request because of legal reasons, e.g. censorship or government-mandated blocked access.

From the draft “A New HTTP Status Code for Legally-restricted Resources” by Tim Bray:

http://tools.ietf.org/html/draft-tbray-http-legally-restricted-status-00

code: 451, title: Unavailable For Legal Reasons

exception webob.exc.HTTPServerError(detail=None, headers=None, comment=None, body_template=None, **kw)

base class for the 500’s, where the server is in-error

This is an error condition in which the server is presumed to be in-error. This is usually unexpected, and thus requires a traceback; ideally, opening a support ticket for the customer. Unless specialized, this is a ‘500 Internal Server Error’

exception webob.exc.HTTPInternalServerError(detail=None, headers=None, comment=None, body_template=None, **kw)

exception webob.exc.HTTPNotImplemented(detail=None, headers=None, comment=None, body_template=None, **kw)

subclass of HTTPServerError

This indicates that the server does not support the functionality required to fulfill the request.

code: 501, title: Not Implemented

exception webob.exc.HTTPBadGateway(detail=None, headers=None, comment=None, body_template=None, **kw)

subclass of HTTPServerError

This indicates that the server, while acting as a gateway or proxy, received an invalid response from the upstream server it accessed in attempting to fulfill the request.

code: 502, title: Bad Gateway

exception webob.exc.HTTPServiceUnavailable(detail=None, headers=None, comment=None, body_template=None, **kw)

subclass of HTTPServerError

This indicates that the server is currently unable to handle the request due to a temporary overloading or maintenance of the server.

code: 503, title: Service Unavailable

exception webob.exc.HTTPGatewayTimeout(detail=None, headers=None, comment=None, body_template=None, **kw)

subclass of HTTPServerError

This indicates that the server, while acting as a gateway or proxy, did not receive a timely response from the upstream server specified by the URI (e.g. HTTP, FTP, LDAP) or some other auxiliary server (e.g. DNS) it needed to access in attempting to complete the request.

code: 504, title: Gateway Timeout

exception webob.exc.HTTPVersionNotSupported(detail=None, headers=None, comment=None, body_template=None, **kw)

subclass of HTTPServerError

This indicates that the server does not support, or refuses to support, the HTTP protocol version that was used in the request message.

code: 505, title: HTTP Version Not Supported

exception webob.exc.HTTPInsufficientStorage(detail=None, headers=None, comment=None, body_template=None, **kw)

subclass of HTTPServerError

This indicates that the server does not have enough space to save the resource.

code: 507, title: Insufficient Storage

exception webob.exc.HTTPNetworkAuthenticationRequired(detail=None, headers=None, comment=None, body_template=None, **kw)

subclass of HTTPServerError

This indicates that the client needs to authenticate to gain network access. From RFC 6585, “Additional HTTP Status Codes”.

code: 511, title: Network Authentication Required

exception webob.exc.HTTPExceptionMiddleware(application)

Middleware that catches exceptions in the sub-application. This does not catch exceptions in the app_iter; only during the initial calling of the application.

This should be put very close to applications that might raise these exceptions. This should not be applied globally; letting expected exceptions raise through the WSGI stack is dangerous.

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

Django

This is a quick summary from reading the Django documentation.

CherryPy/TurboGears

The CherryPy request object is also used by TurboGears 1.x.

Yaro

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.

Werkzeug

An offshoot of Pocoo, this library is based around WSGI, similar to Paste and Yaro.

This is taken from the wrapper documentation.

Zope 3

From the Zope 3 interfaces for the Request and Response.

mod_python

Some key attributes from the mod_python request object.

from webob.exc import HTTPTemporaryRedirect
exc = HTTPTemporaryRedirect(location=url)
return exc(environ, start_response)

res = req.ResponseClass()
res.content_type = 'application/x-csv'
res.headers.add('Content-Disposition', 'attachment;filename=somefile.csv')
return res(environ, start_response)

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

PHP

PHP does not have anything really resembling a request and response object. Instead these are encoded in a set of global objects for the request and functions for the response.