rest25/library/wsgiref.rst => rest262/library/wsgiref.rst
n1- 
2:mod:`wsgiref` --- WSGI Utilities and Reference Implementation
3==============================================================
4
5.. module:: wsgiref
n6-   :synopsis: WSGI Utilities and Reference Implementation
n5+   :synopsis: WSGI Utilities and Reference Implementation.
7.. moduleauthor:: Phillip J. Eby <pje@telecommunity.com>
8.. sectionauthor:: Phillip J. Eby <pje@telecommunity.com>
9
10
11.. versionadded:: 2.5
12
13The Web Server Gateway Interface (WSGI) is a standard interface between web
14server software and web applications written in Python. Having a standard
22
23:mod:`wsgiref` is a reference implementation of the WSGI specification that can
24be used to add WSGI support to a web server or framework.  It provides utilities
25for manipulating WSGI environment variables and response headers, base classes
26for implementing WSGI servers, a demo HTTP server that serves WSGI applications,
27and a validation tool that checks WSGI servers and applications for conformance
28to the WSGI specification (:pep:`333`).
29
n29+See http://www.wsgi.org for more information about WSGI, and links to tutorials
30+and other resources.
31+ 
30-.. % XXX If you're just trying to write a web application...
32+.. XXX If you're just trying to write a web application...
31-.. % XXX should create a URL on python.org to point people to.
32
33
34:mod:`wsgiref.util` -- WSGI environment utilities
35-------------------------------------------------
36
37.. module:: wsgiref.util
n39+   :synopsis: WSGI environment utilities.
38
39
40This module provides a variety of utility functions for working with WSGI
41environments.  A WSGI environment is a dictionary containing HTTP request
42variables as described in :pep:`333`.  All of the functions taking an *environ*
43parameter expect a WSGI-compliant dictionary to be supplied; please see
44:pep:`333` for a detailed specification.
45
107   ``PATH_INFO``, and all of the :pep:`333`\ -defined ``wsgi.*`` variables.  It
108   only supplies default values, and does not replace any existing settings for
109   these variables.
110
111   This routine is intended to make it easier for unit tests of WSGI servers and
112   applications to set up dummy environments.  It should NOT be used by actual WSGI
113   servers or applications, since the data is fake!
114
n117+   Example usage::
118+ 
119+      from wsgiref.util import setup_testing_defaults
120+      from wsgiref.simple_server import make_server
121+ 
122+      # A relatively simple WSGI application. It's going to print out the
123+      # environment dictionary after being updated by setup_testing_defaults
124+      def simple_app(environ, start_response):
125+          setup_testing_defaults(environ)
126+ 
127+          status = '200 OK'
128+          headers = [('Content-type', 'text/plain')]
129+ 
130+          start_response(status, headers)
131+ 
132+          ret = ["%s: %s\n" % (key, value)
133+                 for key, value in environ.iteritems()]
134+          return ret
135+ 
136+      httpd = make_server('', 8000, simple_app)
137+      print "Serving on port 8000..."
138+      httpd.serve_forever()
139+ 
140+ 
115In addition to the environment functions above, the :mod:`wsgiref.util` module
116also provides these miscellaneous utilities:
117
118
119.. function:: is_hop_by_hop(header_name)
120
121   Return true if 'header_name' is an HTTP/1.1 "Hop-by-Hop" header, as defined by
122   :rfc:`2616`.
123
124
125.. class:: FileWrapper(filelike [, blksize=8192])
126
n127-   A wrapper to convert a file-like object to an iterator.  The resulting objects
n153+   A wrapper to convert a file-like object to an :term:`iterator`.  The resulting objects
128   support both :meth:`__getitem__` and :meth:`__iter__` iteration styles, for
129   compatibility with Python 2.1 and Jython. As the object is iterated over, the
130   optional *blksize* parameter will be repeatedly passed to the *filelike*
131   object's :meth:`read` method to obtain strings to yield.  When :meth:`read`
132   returns an empty string, iteration is ended and is not resumable.
133
134   If *filelike* has a :meth:`close` method, the returned object will also have a
135   :meth:`close` method, and it will invoke the *filelike* object's :meth:`close`
136   method when called.
137
n164+   Example usage::
165+ 
166+      from StringIO import StringIO
167+      from wsgiref.util import FileWrapper
168+ 
169+      # We're using a StringIO-buffer for as the file-like object
170+      filelike = StringIO("This is an example file-like object"*10)
171+      wrapper = FileWrapper(filelike, blksize=5)
172+ 
173+      for chunk in wrapper:
174+          print chunk
175+ 
176+ 
138
139:mod:`wsgiref.headers` -- WSGI response header tools
140----------------------------------------------------
141
142.. module:: wsgiref.headers
n182+   :synopsis: WSGI response header tools.
143
144
145This module provides a single class, :class:`Headers`, for convenient
146manipulation of WSGI response headers using a mapping-like interface.
147
148
149.. class:: Headers(headers)
150
214
215         Content-Disposition: attachment; filename="bud.gif"
216
217
218:mod:`wsgiref.simple_server` -- a simple WSGI HTTP server
219---------------------------------------------------------
220
221.. module:: wsgiref.simple_server
n262+   :synopsis: A simple WSGI HTTP server.
222
223
224This module implements a simple HTTP server (based on :mod:`BaseHTTPServer`)
225that serves WSGI applications.  Each server instance serves a single WSGI
226application on a given host and port.  If you want to serve multiple
227applications on a single host and port, you should create a WSGI application
228that parses ``PATH_INFO`` to select which application to invoke for each
229request.  (E.g., using the :func:`shift_path_info` function from
230:mod:`wsgiref.util`.)
231
232
n233-.. function:: make_server(host, port, app [, server_class=:class:`WSGIServer` [, handler_class=:class:`WSGIRequestHandler`]])
n274+.. function:: make_server(host, port, app [, server_class=WSGIServer [, handler_class=WSGIRequestHandler]])
234
235   Create a new WSGI server listening on *host* and *port*, accepting connections
236   for *app*.  The return value is an instance of the supplied *server_class*, and
237   will process requests using the specified *handler_class*.  *app* must be a WSGI
238   application object, as defined by :pep:`333`.
239
240   Example usage::
241
243
244      httpd = make_server('', 8000, demo_app)
245      print "Serving HTTP on port 8000..."
246
247      # Respond to requests until process is killed
248      httpd.serve_forever()
249
250      # Alternative: serve one request, then exit
n251-      ##httpd.handle_request()
n292+      httpd.handle_request()
252
253
254.. function:: demo_app(environ, start_response)
255
256   This function is a small but complete WSGI application that returns a text page
257   containing the message "Hello world!" and a list of the key/value pairs provided
258   in the *environ* parameter.  It's useful for verifying that a WSGI server (such
259   as :mod:`wsgiref.simple_server`) is able to run a simple WSGI application
320
321   .. method:: WSGIRequestHandler.handle()
322
323      Process the HTTP request.  The default implementation creates a handler instance
324      using a :mod:`wsgiref.handlers` class to implement the actual WSGI application
325      interface.
326
327
n328-:mod:`wsgiref.validate` -- WSGI conformance checker
n369+:mod:`wsgiref.validate` --- WSGI conformance checker
329----------------------------------------------------
370+----------------------------------------------------
330
331.. module:: wsgiref.validate
n373+   :synopsis: WSGI conformance checker.
332
333
334When creating new WSGI application objects, frameworks, servers, or middleware,
335it can be useful to validate the new code's conformance using
336:mod:`wsgiref.validate`.  This module provides a function that creates WSGI
337application objects that validate communications between a WSGI server or
338gateway and a WSGI application object, to check both sides for protocol
339conformance.
363
364   This wrapper may also generate output using the :mod:`warnings` module to
365   indicate behaviors that are questionable but which may not actually be
366   prohibited by :pep:`333`.  Unless they are suppressed using Python command-line
367   options or the :mod:`warnings` API, any such warnings will be written to
368   ``sys.stderr`` (*not* ``wsgi.errors``, unless they happen to be the same
369   object).
370
n413+   Example usage::
414+ 
415+      from wsgiref.validate import validator
416+      from wsgiref.simple_server import make_server
417+ 
418+      # Our callable object which is intentionally not compliant to the
419+      # standard, so the validator is going to break
420+      def simple_app(environ, start_response):
421+          status = '200 OK' # HTTP Status
422+          headers = [('Content-type', 'text/plain')] # HTTP Headers
423+          start_response(status, headers)
424+ 
425+          # This is going to break because we need to return a list, and
426+          # the validator is going to inform us
427+          return "Hello World"
428+ 
429+      # This is the application wrapped in a validator
430+      validator_app = validator(simple_app)
431+ 
432+      httpd = make_server('', 8000, validator_app)
433+      print "Listening on port 8000...."
434+      httpd.serve_forever()
435+ 
371
372:mod:`wsgiref.handlers` -- server/gateway base classes
373------------------------------------------------------
374
375.. module:: wsgiref.handlers
n441+   :synopsis: WSGI server/gateway base classes.
376
377
378This module provides base handler classes for implementing WSGI servers and
379gateways.  These base classes handle most of the work of communicating with a
380WSGI application, as long as they are given a CGI-like environment, along with
381input, output, and error streams.
382
383
628      :class:`BaseCGIHandler` and :class:`CGIHandler`.
629
630
631   .. attribute:: BaseHandler.http_version
632
633      If :attr:`origin_server` is true, this string attribute is used to set the HTTP
634      version of the response set to the client.  It defaults to ``"1.0"``.
635
t702+ 
703+Examples
704+--------
705+ 
706+This is a working "Hello World" WSGI application::
707+ 
708+   from wsgiref.simple_server import make_server
709+ 
710+   # Every WSGI application must have an application object - a callable
711+   # object that accepts two arguments. For that purpose, we're going to
712+   # use a function (note that you're not limited to a function, you can
713+   # use a class for example). The first argument passed to the function
714+   # is a dictionary containing CGI-style envrironment variables and the
715+   # second variable is the callable object (see PEP333)
716+   def hello_world_app(environ, start_response):
717+       status = '200 OK' # HTTP Status
718+       headers = [('Content-type', 'text/plain')] # HTTP Headers
719+       start_response(status, headers)
720+ 
721+       # The returned object is going to be printed
722+       return ["Hello World"]
723+ 
724+   httpd = make_server('', 8000, hello_world_app)
725+   print "Serving on port 8000..."
726+ 
727+   # Serve until process is killed
728+   httpd.serve_forever()
Legends
Colors
 Added 
Changed
Deleted
Links
(f)irst change
(n)ext change
(t)op