[Web-SIG] WebOb

[Ian Bicking]

Guido van Rossum wrote:
>> Anyway, I'd be interested in feedback.  We've talked a little about a
>> shared request object -- only a little, and I don't know if it is really
>> a realistic goal to even try.  But I think this request object is a
>> considerably higher quality than any other request objects out there.
>> The response object provides a nice symmetry, as well as facilitating
>> testing.  And it's also a very nice response object.
> 
> I may be totally behind the times here, but I've always found it odd
> to have separate request and response objects -- the functionalities
> or APIs don't really overlap, so why not have a single object? I'm
> really asking to be educated; I severely hope there's a better reason
> than "Java did it this way". :-)

There are several headers that exist in both the request and the 
response.  For instance, Content-Type, Content-Length, and 
Cache-Control.  Additionally, a lot of headers aren't immediately 
obvious -- is Location a request or response header?  Well, response, 
but if all the headers are mixed together it takes a bit of thought to 
realize that.

The WebOb request and response are mostly representations of the HTTP 
messages, and there's two distinct messages which look very similar, 
which makes them hard to mix into one object.

>> They are both fairly reasonable to subclass, if there are minor naming
>> issues (if there's really missing features, I'd like to add them
>> directly -- though for the response object in particular it's likely
>> you'll want to subclass to give application defaults, like a default
>> content type).
>>
>> It's based strictly on WSGI, with the request object an almost-stateless
>> wrapper around a WSGI environment, and the response object a WSGI
>> application that contains mutable status/headers/app_iter.
>>
>> Almost all the defined HTTP headers are available as attributes on the
>> request and/or response.  I try to parse these in as sensible a way as
>> possible, e.g., req.if_modified_since is a datetime object (of course
>> unparsed access is also available).  Several objects like
>> response.cache_control are a bit more complex, since there's no data
>> structure that exactly represents them.  I've tried to make them as easy
>> to use as possible for realistic web tasks.
> 
> I'm interesting in something that's as lightweight as possible. Are
> there things that take a reasonable time to parse that could be put
> off until first use? Perhaps using properties to keep the simplest
> possible API (or perhaps not to emphasize the cost of first use)?

Almost everything is a property.  This is in part because state is kept 
in the native WSGI forms (environ, status, headers, app_iter), so 
everything is calculated off of these.  It also makes instantiation 
relatively light.  Even the request body is left alone until 
request.POST is accessed.

>> I'm very interested to get any feedback, especially right now when there
>> are no backward compatibility concerns.  Right now no critique is too
>> large or small.
>>
>> It's in svn at:
>>    http://svn.pythonpaste.org/Paste/WebOb/trunk
>>
>> And there are fairly complete docs at:
>>    http://pythonpaste.org/webob/
> 
> I briefly looked at the tutorial and was put off a little by the
> interactive prompt style of the examples; that seems so unrealistic
> that I wonder if it wouldn't be better to just say "put this in a file
> and run it like this"?

The side effect of doctesting is that docs sometimes look weird :-/

I'm not sure what form the docs should take.  I'm open to suggestions. 
The extracted docs are actually reasonable as a reference, I think:

http://pythonpaste.org/webob/class-webob.Request.html
http://pythonpaste.org/webob/class-webob.Response.html

For realistic use cases, some kind of infrastructure is necessary.  I 
suppose a simple example using the wsgiref server and a plain WSGI app 
would suffice.  Even a very small framework (e.g., 
http://svn.pythonpaste.org/Paste/apps/FlatAtomPub/trunk/flatatompub/dec.py) 
improves that considerably, but probably isn't worth introducing.

>> A quick summary of differences in the API and some other
>> request/response objects out there:
>>    http://pythonpaste.org/webob/differences.html
>> I'd include more frameworks, if you can point me to their
>> request/response API documentation (e.g., I looked but couldn't find any
>> for Zope 3).
> 
> I'm not too familiar with other frameworks (having always hacked my
> own, as it's so easy :-). Any chance of a summary that's not a
> tutorial nor a reference?

Did you look at the file serving example? 
http://pythonpaste.org/webob/file-example.html

I suppose a quick summary would also be possible, covering just the most 
important attributes and with a quick listing of others (like all the 
properties for the individual HTTP headers).


-- 
Ian Bicking : ianb at colorstudy.com : http://blog.ianbicking.org
             : Write code, do good : http://topp.openplans.org/careers