diff options
Diffstat (limited to 'Doc/library/wsgiref.rst')
| -rw-r--r-- | Doc/library/wsgiref.rst | 641 |
1 files changed, 641 insertions, 0 deletions
diff --git a/Doc/library/wsgiref.rst b/Doc/library/wsgiref.rst new file mode 100644 index 0000000..ff68684 --- /dev/null +++ b/Doc/library/wsgiref.rst @@ -0,0 +1,641 @@ +: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! + +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 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. + + +: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). + + +: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"``. + |