[Web-SIG] wsgiref doc draft; reviews/patches wanted

[Joe Gregorio]

Phillip,

1. It's not really clear from the abstract 'what' this library
provides. You might want
   to consider moving the text from 1.1 up to the same level as the abstract.

2.  In section 1.1 you might want to consider dropping the sentence:
"Only authors
    of web servers and programming frameworks need to know every detail..."
    It doesn't offer any concrete information and just indirectly
     makes WSGI look complicated.

3. From the abstract:  "Having a standard interface makes it easy to use a
      WSGI-supporting application with a number of different web servers."

     is a little akward, how about:

    "Having a standard interface makes it easy to use an application
    that supports WSGI with a number of different web servers."

4. I believe the order of submodules presented is important and think that
   they should be listed with 'handlers' and 'simple_server' first:

    wsgiref.handlers - server/gateway base classes
    wsgiref.simple_server - a simple WSGI HTTP server
    wsgiref.util - WSGI environment utilities
    wsgiref.headers - WSGI response header tools
    wsgiref.validate - WSGI conformance checker

5. You might consider moving 'headers' into 'util'. Of course, you could
    go all the way in simplifying and move 'validate' in there too.

    wsgiref.handlers - server/gateway base classes
    wsgiref.simple_server - a simple WSGI HTTP server
    wsgiref.util - WSGI environment utilities

Besides those nits it looks very good and will be a fine
addition to the core library.

   -joe


On 6/6/06, Phillip J. Eby <pje at telecommunity.com> wrote:
> I've finished my draft for the wsgiref documentation (including stuff I
> swiped from AMK's draft; thanks AMK!), and am looking for comments before I
> add it to the stdlib documentation.
>
> Source: http://svn.eby-sarna.com/svnroot/wsgiref/docs
> PDF:    http://peak.telecommunity.com/wsgiref.pdf
> HTML:   http://peak.telecommunity.com/wsgiref_docs/
>
> My current plan is to make a hopefully-final release of the standalone
> version of wsgiref on PyPI, then clone that version for inclusion in the
> stdlib.
>
> The latest version of wsgiref in the eby-sarna SVN includes a new
> ``make_server()`` convenience function (addressing Titus' concerns about
> the constructor signatures while retaining backward compatibility) and it
> adds a ``wsgiref.validate`` module based on paste.lint.
>
> In addition to those two new features, tests were added for the new
> validate module and for WSGIServer.  The test suite and directory layout of
> the package were also simplified and consolidated to make merging to the
> stdlib easier.
>
> Feedback welcomed.
>
> _______________________________________________
> Web-SIG mailing list
> Web-SIG at python.org
> Web SIG: http://www.python.org/sigs/web-sig
> Unsubscribe: http://mail.python.org/mailman/options/web-sig/joe.gregorio%40gmail.com
>


-- 
Joe Gregorio        http://bitworking.org