[Web-SIG] WebOb

[Ian Bicking]

Guido van Rossum wrote:
> 2007/10/22, Ian Bicking <ianb at colorstudy.com>:
>>> 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 :-/
> 
> Personally, I find doctest a great tool for writing tests in certain
> situations; not so great for writing docs though.

Yeah... I really like it in a lot of ways, but I'm not quite sure what 
the right balance is.  Untested documentation is also very unfortunate; 
too much potential for drift.

>> 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
> 
> Hm, these are mostly alphabetical listings of individual methods and
> properties. I'm still hoping for something that I can read from top to
> bottom in 10 minutes and get an idea of what this is and how to use
> it.

I redid the front page to make it more brief: http://pythonpaste.org/webob/

I stopped with the example, because I couldn't think of a good example. 
  Maybe a different evening.  Suggestions of course welcome.

>> For realistic use cases, some kind of infrastructure is necessary.
> 
> How realistic are we talking? I'm thinking of something that I can
> test by pointing my browser to localhost:8080 or similar. For CGI
> scripts, the standard library's CGIHTTPServer would suffice. How hard
> is it to create something similar for WSGI or for webob?

Well, some kind of WSGI adapter; the wsgiref one is fine.  The file 
example I guess is boring, because without some kind of dispatch you can 
only serve up one file.  A most boring server.

Wiki is a common example, but a little too common at this point.  WebOb 
doesn't offer anything for HTML either, so it would be a somewhat 
unsatisfying example anyway I suspect.

-- 
Ian Bicking : ianb at colorstudy.com : http://blog.ianbicking.org