MCL/sf/adapt/qemu: comparison symbian-qemu-0.9.1-12/python-2.6.1/Doc/library/wsgiref.rst

equal deleted inserted replaced

-:ffa851df0825
+:2fb8b9db1c86
+:mod:`wsgiref` --- WSGI Utilities and Reference Implementation
+==============================================================
+.. module:: wsgiref
+:synopsis: WSGI Utilities and Reference Implementation.
+.. moduleauthor:: Phillip J. Eby <pje@telecommunity.com>
+.. sectionauthor:: Phillip J. Eby <pje@telecommunity.com>
+.. versionadded:: 2.5
+The Web Server Gateway Interface (WSGI) is a standard interface between web
+server software and web applications written in Python. Having a standard
+interface makes it easy to use an application that supports WSGI with a number
+of different web servers.
+Only authors of web servers and programming frameworks need to know every detail
+and corner case of the WSGI design.  You don't need to understand every detail
+of WSGI just to install a WSGI application or to write a web application using
+an existing framework.
+:mod:`wsgiref` is a reference implementation of the WSGI specification that can
+be used to add WSGI support to a web server or framework.  It provides utilities
+for manipulating WSGI environment variables and response headers, base classes
+for implementing WSGI servers, a demo HTTP server that serves WSGI applications,
+and a validation tool that checks WSGI servers and applications for conformance
+to the WSGI specification (:pep:`333`).
+See http://www.wsgi.org for more information about WSGI, and links to tutorials
+and other resources.
+.. XXX If you're just trying to write a web application...
+:mod:`wsgiref.util` -- WSGI environment utilities
+-------------------------------------------------
+.. module:: wsgiref.util
+:synopsis: WSGI environment utilities.
+This module provides a variety of utility functions for working with WSGI
+environments.  A WSGI environment is a dictionary containing HTTP request
+variables as described in :pep:`333`.  All of the functions taking an *environ*
+parameter expect a WSGI-compliant dictionary to be supplied; please see
+:pep:`333` for a detailed specification.
+.. function:: guess_scheme(environ)
+Return a guess for whether ``wsgi.url_scheme`` should be "http" or "https", by
+checking for a ``HTTPS`` environment variable in the *environ* dictionary.  The
+return value is a string.
+This function is useful when creating a gateway that wraps CGI or a CGI-like
+protocol such as FastCGI.  Typically, servers providing such protocols will
+include a ``HTTPS`` variable with a value of "1" "yes", or "on" when a request
+is received via SSL.  So, this function returns "https" if such a value is
+found, and "http" otherwise.
+.. function:: request_uri(environ [, include_query=1])
+Return the full request URI, optionally including the query string, using the
+algorithm found in the "URL Reconstruction" section of :pep:`333`.  If
+*include_query* is false, the query string is not included in the resulting URI.
+.. function:: application_uri(environ)
+Similar to :func:`request_uri`, except that the ``PATH_INFO`` and
+``QUERY_STRING`` variables are ignored.  The result is the base URI of the
+application object addressed by the request.
+.. function:: shift_path_info(environ)
+Shift a single name from ``PATH_INFO`` to ``SCRIPT_NAME`` and return the name.
+The *environ* dictionary is *modified* in-place; use a copy if you need to keep
+the original ``PATH_INFO`` or ``SCRIPT_NAME`` intact.
+If there are no remaining path segments in ``PATH_INFO``, ``None`` is returned.
+Typically, this routine is used to process each portion of a request URI path,
+for example to treat the path as a series of dictionary keys. This routine
+modifies the passed-in environment to make it suitable for invoking another WSGI
+application that is located at the target URI. For example, if there is a WSGI
+application at ``/foo``, and the request URI path is ``/foo/bar/baz``, and the
+WSGI application at ``/foo`` calls :func:`shift_path_info`, it will receive the
+string "bar", and the environment will be updated to be suitable for passing to
+a WSGI application at ``/foo/bar``.  That is, ``SCRIPT_NAME`` will change from
+``/foo`` to ``/foo/bar``, and ``PATH_INFO`` will change from ``/bar/baz`` to
+``/baz``.
+When ``PATH_INFO`` is just a "/", this routine returns an empty string and
+appends a trailing slash to ``SCRIPT_NAME``, even though empty path segments are
+normally ignored, and ``SCRIPT_NAME`` doesn't normally end in a slash.  This is
+intentional behavior, to ensure that an application can tell the difference
+between URIs ending in ``/x`` from ones ending in ``/x/`` when using this
+routine to do object traversal.
+.. function:: setup_testing_defaults(environ)
+Update *environ* with trivial defaults for testing purposes.
+This routine adds various parameters required for WSGI, including ``HTTP_HOST``,
+``SERVER_NAME``, ``SERVER_PORT``, ``REQUEST_METHOD``, ``SCRIPT_NAME``,
+``PATH_INFO``, and all of the :pep:`333`\ -defined ``wsgi.*`` variables.  It
+only supplies default values, and does not replace any existing settings for
+these variables.
+This routine is intended to make it easier for unit tests of WSGI servers and
+applications to set up dummy environments.  It should NOT be used by actual WSGI
+servers or applications, since the data is fake!
+Example usage::
+from wsgiref.util import setup_testing_defaults
+from wsgiref.simple_server import make_server
+# A relatively simple WSGI application. It's going to print out the
+# environment dictionary after being updated by setup_testing_defaults
+def simple_app(environ, start_response):
+setup_testing_defaults(environ)
+status = '200 OK'
+headers = [('Content-type', 'text/plain')]
+start_response(status, headers)
+ret = ["%s: %s\n" % (key, value)
+for key, value in environ.iteritems()]
+return ret
+httpd = make_server('', 8000, simple_app)
+print "Serving on port 8000..."
+httpd.serve_forever()
+In addition to the environment functions above, the :mod:`wsgiref.util` module
+also provides these miscellaneous utilities:
+.. function:: is_hop_by_hop(header_name)
+Return true if 'header_name' is an HTTP/1.1 "Hop-by-Hop" header, as defined by
+:rfc:`2616`.
+.. class:: FileWrapper(filelike [, blksize=8192])
+A wrapper to convert a file-like object to an :term:`iterator`.  The resulting objects
+support both :meth:`__getitem__` and :meth:`__iter__` iteration styles, for
+compatibility with Python 2.1 and Jython. As the object is iterated over, the
+optional *blksize* parameter will be repeatedly passed to the *filelike*
+object's :meth:`read` method to obtain strings to yield.  When :meth:`read`
+returns an empty string, iteration is ended and is not resumable.
+If *filelike* has a :meth:`close` method, the returned object will also have a
+:meth:`close` method, and it will invoke the *filelike* object's :meth:`close`
+method when called.
+Example usage::
+from StringIO import StringIO
+from wsgiref.util import FileWrapper
+# We're using a StringIO-buffer for as the file-like object
+filelike = StringIO("This is an example file-like object"*10)
+wrapper = FileWrapper(filelike, blksize=5)
+for chunk in wrapper:
+print chunk
+:mod:`wsgiref.headers` -- WSGI response header tools
+----------------------------------------------------
+.. module:: wsgiref.headers
+:synopsis: WSGI response header tools.
+This module provides a single class, :class:`Headers`, for convenient
+manipulation of WSGI response headers using a mapping-like interface.
+.. class:: Headers(headers)
+Create a mapping-like object wrapping *headers*, which must be a list of header
+name/value tuples as described in :pep:`333`.  Any changes made to the new
+:class:`Headers` object will directly update the *headers* list it was created
+with.
+:class:`Headers` objects support typical mapping operations including
+:meth:`__getitem__`, :meth:`get`, :meth:`__setitem__`, :meth:`setdefault`,
+:meth:`__delitem__`, :meth:`__contains__` and :meth:`has_key`.  For each of
+these methods, the key is the header name (treated case-insensitively), and the
+value is the first value associated with that header name.  Setting a header
+deletes any existing values for that header, then adds a new value at the end of
+the wrapped header list.  Headers' existing order is generally maintained, with
+new headers added to the end of the wrapped list.
+Unlike a dictionary, :class:`Headers` objects do not raise an error when you try
+to get or delete a key that isn't in the wrapped header list. Getting a
+nonexistent header just returns ``None``, and deleting a nonexistent header does
+nothing.
+:class:`Headers` objects also support :meth:`keys`, :meth:`values`, and
+:meth:`items` methods.  The lists returned by :meth:`keys` and :meth:`items` can
+include the same key more than once if there is a multi-valued header.  The
+``len()`` of a :class:`Headers` object is the same as the length of its
+:meth:`items`, which is the same as the length of the wrapped header list.  In
+fact, the :meth:`items` method just returns a copy of the wrapped header list.
+Calling ``str()`` on a :class:`Headers` object returns a formatted string
+suitable for transmission as HTTP response headers.  Each header is placed on a
+line with its value, separated by a colon and a space. Each line is terminated
+by a carriage return and line feed, and the string is terminated with a blank
+line.
+In addition to their mapping interface and formatting features, :class:`Headers`
+objects also have the following methods for querying and adding multi-valued
+headers, and for adding headers with MIME parameters:
+.. method:: Headers.get_all(name)
+Return a list of all the values for the named header.
+The returned list will be sorted in the order they appeared in the original
+header list or were added to this instance, and may contain duplicates.  Any
+fields deleted and re-inserted are always appended to the header list.  If no
+fields exist with the given name, returns an empty list.
+.. method:: Headers.add_header(name, value, **_params)
+Add a (possibly multi-valued) header, with optional MIME parameters specified
+via keyword arguments.
+*name* is the header field to add.  Keyword arguments can be used to set MIME
+parameters for the header field.  Each parameter must be a string or ``None``.
+Underscores in parameter names are converted to dashes, since dashes are illegal
+in Python identifiers, but many MIME parameter names include dashes.  If the
+parameter value is a string, it is added to the header value parameters in the
+form ``name="value"``. If it is ``None``, only the parameter name is added.
+(This is used for MIME parameters without a value.)  Example usage::
+h.add_header('content-disposition', 'attachment', filename='bud.gif')
+The above will add a header that looks like this::
+Content-Disposition: attachment; filename="bud.gif"
+:mod:`wsgiref.simple_server` -- a simple WSGI HTTP server
+---------------------------------------------------------
+.. module:: wsgiref.simple_server
+:synopsis: A simple WSGI HTTP server.
+This module implements a simple HTTP server (based on :mod:`BaseHTTPServer`)
+that serves WSGI applications.  Each server instance serves a single WSGI
+application on a given host and port.  If you want to serve multiple
+applications on a single host and port, you should create a WSGI application
+that parses ``PATH_INFO`` to select which application to invoke for each
+request.  (E.g., using the :func:`shift_path_info` function from
+:mod:`wsgiref.util`.)
+.. function:: make_server(host, port, app [, server_class=WSGIServer [, handler_class=WSGIRequestHandler]])
+Create a new WSGI server listening on *host* and *port*, accepting connections
+for *app*.  The return value is an instance of the supplied *server_class*, and
+will process requests using the specified *handler_class*.  *app* must be a WSGI
+application object, as defined by :pep:`333`.
+Example usage::
+from wsgiref.simple_server import make_server, demo_app
+httpd = make_server('', 8000, demo_app)
+print "Serving HTTP on port 8000..."
+# Respond to requests until process is killed
+httpd.serve_forever()
+# Alternative: serve one request, then exit
+httpd.handle_request()
+.. function:: demo_app(environ, start_response)
+This function is a small but complete WSGI application that returns a text page
+containing the message "Hello world!" and a list of the key/value pairs provided
+in the *environ* parameter.  It's useful for verifying that a WSGI server (such
+as :mod:`wsgiref.simple_server`) is able to run a simple WSGI application
+correctly.
+.. class:: WSGIServer(server_address, RequestHandlerClass)
+Create a :class:`WSGIServer` instance.  *server_address* should be a
+``(host,port)`` tuple, and *RequestHandlerClass* should be the subclass of
+:class:`BaseHTTPServer.BaseHTTPRequestHandler` that will be used to process
+requests.
+You do not normally need to call this constructor, as the :func:`make_server`
+function can handle all the details for you.
+:class:`WSGIServer` is a subclass of :class:`BaseHTTPServer.HTTPServer`, so all
+of its methods (such as :meth:`serve_forever` and :meth:`handle_request`) are
+available. :class:`WSGIServer` also provides these WSGI-specific methods:
+.. method:: WSGIServer.set_app(application)
+Sets the callable *application* as the WSGI application that will receive
+requests.
+.. method:: WSGIServer.get_app()
+Returns the currently-set application callable.
+Normally, however, you do not need to use these additional methods, as
+:meth:`set_app` is normally called by :func:`make_server`, and the
+:meth:`get_app` exists mainly for the benefit of request handler instances.
+.. class:: WSGIRequestHandler(request, client_address, server)
+Create an HTTP handler for the given *request* (i.e. a socket), *client_address*
+(a ``(host,port)`` tuple), and *server* (:class:`WSGIServer` instance).
+You do not need to create instances of this class directly; they are
+automatically created as needed by :class:`WSGIServer` objects.  You can,
+however, subclass this class and supply it as a *handler_class* to the
+:func:`make_server` function.  Some possibly relevant methods for overriding in
+subclasses:
+.. method:: WSGIRequestHandler.get_environ()
+Returns a dictionary containing the WSGI environment for a request.  The default
+implementation copies the contents of the :class:`WSGIServer` object's
+:attr:`base_environ` dictionary attribute and then adds various headers derived
+from the HTTP request.  Each call to this method should return a new dictionary
+containing all of the relevant CGI environment variables as specified in
+:pep:`333`.
+.. method:: WSGIRequestHandler.get_stderr()
+Return the object that should be used as the ``wsgi.errors`` stream. The default
+implementation just returns ``sys.stderr``.
+.. method:: WSGIRequestHandler.handle()
+Process the HTTP request.  The default implementation creates a handler instance
+using a :mod:`wsgiref.handlers` class to implement the actual WSGI application
+interface.
+:mod:`wsgiref.validate` --- WSGI conformance checker
+----------------------------------------------------
+.. module:: wsgiref.validate
+:synopsis: WSGI conformance checker.
+When creating new WSGI application objects, frameworks, servers, or middleware,
+it can be useful to validate the new code's conformance using
+:mod:`wsgiref.validate`.  This module provides a function that creates WSGI
+application objects that validate communications between a WSGI server or
+gateway and a WSGI application object, to check both sides for protocol
+conformance.
+Note that this utility does not guarantee complete :pep:`333` compliance; an
+absence of errors from this module does not necessarily mean that errors do not
+exist.  However, if this module does produce an error, then it is virtually
+certain that either the server or application is not 100% compliant.
+This module is based on the :mod:`paste.lint` module from Ian Bicking's "Python
+Paste" library.
+.. function:: validator(application)
+Wrap *application* and return a new WSGI application object.  The returned
+application will forward all requests to the original *application*, and will
+check that both the *application* and the server invoking it are conforming to
+the WSGI specification and to RFC 2616.
+Any detected nonconformance results in an :exc:`AssertionError` being raised;
+note, however, that how these errors are handled is server-dependent.  For
+example, :mod:`wsgiref.simple_server` and other servers based on
+:mod:`wsgiref.handlers` (that don't override the error handling methods to do
+something else) will simply output a message that an error has occurred, and
+dump the traceback to ``sys.stderr`` or some other error stream.
+This wrapper may also generate output using the :mod:`warnings` module to
+indicate behaviors that are questionable but which may not actually be
+prohibited by :pep:`333`.  Unless they are suppressed using Python command-line
+options or the :mod:`warnings` API, any such warnings will be written to
+``sys.stderr`` (*not* ``wsgi.errors``, unless they happen to be the same
+object).
+Example usage::
+from wsgiref.validate import validator
+from wsgiref.simple_server import make_server
+# Our callable object which is intentionally not compliant to the
+# standard, so the validator is going to break
+def simple_app(environ, start_response):
+status = '200 OK' # HTTP Status
+headers = [('Content-type', 'text/plain')] # HTTP Headers
+start_response(status, headers)
+# This is going to break because we need to return a list, and
+# the validator is going to inform us
+return "Hello World"
+# This is the application wrapped in a validator
+validator_app = validator(simple_app)
+httpd = make_server('', 8000, validator_app)
+print "Listening on port 8000...."
+httpd.serve_forever()
+:mod:`wsgiref.handlers` -- server/gateway base classes
+------------------------------------------------------
+.. module:: wsgiref.handlers
+:synopsis: WSGI server/gateway base classes.
+This module provides base handler classes for implementing WSGI servers and
+gateways.  These base classes handle most of the work of communicating with a
+WSGI application, as long as they are given a CGI-like environment, along with
+input, output, and error streams.
+.. class:: CGIHandler()
+CGI-based invocation via ``sys.stdin``, ``sys.stdout``, ``sys.stderr`` and
+``os.environ``.  This is useful when you have a WSGI application and want to run
+it as a CGI script.  Simply invoke ``CGIHandler().run(app)``, where ``app`` is
+the WSGI application object you wish to invoke.
+This class is a subclass of :class:`BaseCGIHandler` that sets ``wsgi.run_once``
+to true, ``wsgi.multithread`` to false, and ``wsgi.multiprocess`` to true, and
+always uses :mod:`sys` and :mod:`os` to obtain the necessary CGI streams and
+environment.
+.. class:: BaseCGIHandler(stdin, stdout, stderr, environ [, multithread=True [, multiprocess=False]])
+Similar to :class:`CGIHandler`, but instead of using the :mod:`sys` and
+:mod:`os` modules, the CGI environment and I/O streams are specified explicitly.
+The *multithread* and *multiprocess* values are used to set the
+``wsgi.multithread`` and ``wsgi.multiprocess`` flags for any applications run by
+the handler instance.
+This class is a subclass of :class:`SimpleHandler` intended for use with
+software other than HTTP "origin servers".  If you are writing a gateway
+protocol implementation (such as CGI, FastCGI, SCGI, etc.) that uses a
+``Status:`` header to send an HTTP status, you probably want to subclass this
+instead of :class:`SimpleHandler`.
+.. class:: SimpleHandler(stdin, stdout, stderr, environ [,multithread=True [, multiprocess=False]])
+Similar to :class:`BaseCGIHandler`, but designed for use with HTTP origin
+servers.  If you are writing an HTTP server implementation, you will probably
+want to subclass this instead of :class:`BaseCGIHandler`
+This class is a subclass of :class:`BaseHandler`.  It overrides the
+:meth:`__init__`, :meth:`get_stdin`, :meth:`get_stderr`, :meth:`add_cgi_vars`,
+:meth:`_write`, and :meth:`_flush` methods to support explicitly setting the
+environment and streams via the constructor.  The supplied environment and
+streams are stored in the :attr:`stdin`, :attr:`stdout`, :attr:`stderr`, and
+:attr:`environ` attributes.
+.. class:: BaseHandler()
+This is an abstract base class for running WSGI applications.  Each instance
+will handle a single HTTP request, although in principle you could create a
+subclass that was reusable for multiple requests.
+:class:`BaseHandler` instances have only one method intended for external use:
+.. method:: BaseHandler.run(app)
+Run the specified WSGI application, *app*.
+All of the other :class:`BaseHandler` methods are invoked by this method in the
+process of running the application, and thus exist primarily to allow
+customizing the process.
+The following methods MUST be overridden in a subclass:
+.. method:: BaseHandler._write(data)
+Buffer the string *data* for transmission to the client.  It's okay if this
+method actually transmits the data; :class:`BaseHandler` just separates write
+and flush operations for greater efficiency when the underlying system actually
+has such a distinction.
+.. method:: BaseHandler._flush()
+Force buffered data to be transmitted to the client.  It's okay if this method
+is a no-op (i.e., if :meth:`_write` actually sends the data).
+.. method:: BaseHandler.get_stdin()
+Return an input stream object suitable for use as the ``wsgi.input`` of the
+request currently being processed.
+.. method:: BaseHandler.get_stderr()
+Return an output stream object suitable for use as the ``wsgi.errors`` of the
+request currently being processed.
+.. method:: BaseHandler.add_cgi_vars()
+Insert CGI variables for the current request into the :attr:`environ` attribute.
+Here are some other methods and attributes you may wish to override. This list
+is only a summary, however, and does not include every method that can be
+overridden.  You should consult the docstrings and source code for additional
+information before attempting to create a customized :class:`BaseHandler`
+subclass.
+Attributes and methods for customizing the WSGI environment:
+.. attribute:: BaseHandler.wsgi_multithread
+The value to be used for the ``wsgi.multithread`` environment variable.  It
+defaults to true in :class:`BaseHandler`, but may have a different default (or
+be set by the constructor) in the other subclasses.
+.. attribute:: BaseHandler.wsgi_multiprocess
+The value to be used for the ``wsgi.multiprocess`` environment variable.  It
+defaults to true in :class:`BaseHandler`, but may have a different default (or
+be set by the constructor) in the other subclasses.
+.. attribute:: BaseHandler.wsgi_run_once
+The value to be used for the ``wsgi.run_once`` environment variable.  It
+defaults to false in :class:`BaseHandler`, but :class:`CGIHandler` sets it to
+true by default.
+.. attribute:: BaseHandler.os_environ
+The default environment variables to be included in every request's WSGI
+environment.  By default, this is a copy of ``os.environ`` at the time that
+:mod:`wsgiref.handlers` was imported, but subclasses can either create their own
+at the class or instance level.  Note that the dictionary should be considered
+read-only, since the default value is shared between multiple classes and
+instances.
+.. attribute:: BaseHandler.server_software
+If the :attr:`origin_server` attribute is set, this attribute's value is used to
+set the default ``SERVER_SOFTWARE`` WSGI environment variable, and also to set a
+default ``Server:`` header in HTTP responses.  It is ignored for handlers (such
+as :class:`BaseCGIHandler` and :class:`CGIHandler`) that are not HTTP origin
+servers.
+.. method:: BaseHandler.get_scheme()
+Return the URL scheme being used for the current request.  The default
+implementation uses the :func:`guess_scheme` function from :mod:`wsgiref.util`
+to guess whether the scheme should be "http" or "https", based on the current
+request's :attr:`environ` variables.
+.. method:: BaseHandler.setup_environ()
+Set the :attr:`environ` attribute to a fully-populated WSGI environment.  The
+default implementation uses all of the above methods and attributes, plus the
+:meth:`get_stdin`, :meth:`get_stderr`, and :meth:`add_cgi_vars` methods and the
+:attr:`wsgi_file_wrapper` attribute.  It also inserts a ``SERVER_SOFTWARE`` key
+if not present, as long as the :attr:`origin_server` attribute is a true value
+and the :attr:`server_software` attribute is set.
+Methods and attributes for customizing exception handling:
+.. method:: BaseHandler.log_exception(exc_info)
+Log the *exc_info* tuple in the server log.  *exc_info* is a ``(type, value,
+traceback)`` tuple.  The default implementation simply writes the traceback to
+the request's ``wsgi.errors`` stream and flushes it.  Subclasses can override
+this method to change the format or retarget the output, mail the traceback to
+an administrator, or whatever other action may be deemed suitable.
+.. attribute:: BaseHandler.traceback_limit
+The maximum number of frames to include in tracebacks output by the default
+:meth:`log_exception` method.  If ``None``, all frames are included.
+.. method:: BaseHandler.error_output(environ, start_response)
+This method is a WSGI application to generate an error page for the user.  It is
+only invoked if an error occurs before headers are sent to the client.
+This method can access the current error information using ``sys.exc_info()``,
+and should pass that information to *start_response* when calling it (as
+described in the "Error Handling" section of :pep:`333`).
+The default implementation just uses the :attr:`error_status`,
+:attr:`error_headers`, and :attr:`error_body` attributes to generate an output
+page.  Subclasses can override this to produce more dynamic error output.
+Note, however, that it's not recommended from a security perspective to spit out
+diagnostics to any old user; ideally, you should have to do something special to
+enable diagnostic output, which is why the default implementation doesn't
+include any.
+.. attribute:: BaseHandler.error_status
+The HTTP status used for error responses.  This should be a status string as
+defined in :pep:`333`; it defaults to a 500 code and message.
+.. attribute:: BaseHandler.error_headers
+The HTTP headers used for error responses.  This should be a list of WSGI
+response headers (``(name, value)`` tuples), as described in :pep:`333`.  The
+default list just sets the content type to ``text/plain``.
+.. attribute:: BaseHandler.error_body
+The error response body.  This should be an HTTP response body string. It
+defaults to the plain text, "A server error occurred.  Please contact the
+administrator."
+Methods and attributes for :pep:`333`'s "Optional Platform-Specific File
+Handling" feature:
+.. attribute:: BaseHandler.wsgi_file_wrapper
+A ``wsgi.file_wrapper`` factory, or ``None``.  The default value of this
+attribute is the :class:`FileWrapper` class from :mod:`wsgiref.util`.
+.. method:: BaseHandler.sendfile()
+Override to implement platform-specific file transmission.  This method is
+called only if the application's return value is an instance of the class
+specified by the :attr:`wsgi_file_wrapper` attribute.  It should return a true
+value if it was able to successfully transmit the file, so that the default
+transmission code will not be executed. The default implementation of this
+method just returns a false value.
+Miscellaneous methods and attributes:
+.. attribute:: BaseHandler.origin_server
+This attribute should be set to a true value if the handler's :meth:`_write` and
+:meth:`_flush` are being used to communicate directly to the client, rather than
+via a CGI-like gateway protocol that wants the HTTP status in a special
+``Status:`` header.
+This attribute's default value is true in :class:`BaseHandler`, but false in
+:class:`BaseCGIHandler` and :class:`CGIHandler`.
+.. attribute:: BaseHandler.http_version
+If :attr:`origin_server` is true, this string attribute is used to set the HTTP
+version of the response set to the client.  It defaults to ``"1.0"``.
+Examples
+--------
+This is a working "Hello World" WSGI application::
+from wsgiref.simple_server import make_server
+# Every WSGI application must have an application object - a callable
+# object that accepts two arguments. For that purpose, we're going to
+# use a function (note that you're not limited to a function, you can
+# use a class for example). The first argument passed to the function
+# is a dictionary containing CGI-style envrironment variables and the
+# second variable is the callable object (see PEP333)
+def hello_world_app(environ, start_response):
+status = '200 OK' # HTTP Status
+headers = [('Content-type', 'text/plain')] # HTTP Headers
+start_response(status, headers)
+# The returned object is going to be printed
+return ["Hello World"]
+httpd = make_server('', 8000, hello_world_app)
+print "Serving on port 8000..."
+# Serve until process is killed
+httpd.serve_forever()