|
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.
-
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 BaseCGIHandler that sets
wsgi.run_once to true, wsgi.multithread to false, and
wsgi.multiprocess to true, and always uses sys and
os to obtain the necessary CGI streams and environment.
| class BaseCGIHandler( |
stdin, stdout, stderr, environ
[, multithread=True [, multiprocess=False]]) |
-
Similar to CGIHandler, but instead of using the sys and
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 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 SimpleHandler.
| class SimpleHandler( |
stdin, stdout, stderr, environ
[,multithread=True [, multiprocess=False]]) |
-
Similar to 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 BaseCGIHandler
This class is a subclass of BaseHandler. It overrides the
__init__(), get_stdin(), get_stderr(),
add_cgi_vars(), _write(), and _flush()
methods to support explicitly setting the environment and streams via
the constructor. The supplied environment and streams are stored in
the stdin, stdout, stderr, and
environ attributes.
-
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.
BaseHandler instances have only one method intended for external
use:
-
Run the specified WSGI application, app.
All of the other 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:
-
Buffer the string data for transmission to the client. It's okay
if this method actually transmits the data; BaseHandler
just separates write and flush operations for greater efficiency
when the underlying system actually has such a distinction.
-
Force buffered data to be transmitted to the client. It's okay if this
method is a no-op (i.e., if _write() actually sends the data).
-
Return an input stream object suitable for use as the
wsgi.input
of the request currently being processed.
-
Return an output stream object suitable for use as the
wsgi.errors of the request currently being processed.
-
Insert CGI variables for the current request into the 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
BaseHandler subclass.
Attributes and methods for customizing the WSGI environment:
- wsgi_multithread
-
The value to be used for the
wsgi.multithread environment
variable. It defaults to true in BaseHandler, but may have
a different default (or be set by the constructor) in the other
subclasses.
- wsgi_multiprocess
-
The value to be used for the
wsgi.multiprocess environment
variable. It defaults to true in BaseHandler, but may have
a different default (or be set by the constructor) in the other
subclasses.
- wsgi_run_once
-
The value to be used for the
wsgi.run_once environment
variable. It defaults to false in BaseHandler, but
CGIHandler sets it to true by default.
- 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 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.
- server_software
-
If the 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 BaseCGIHandler
and CGIHandler) that are not HTTP origin servers.
-
Return the URL scheme being used for the current request. The default
implementation uses the guess_scheme() function from
wsgiref.util to guess whether the scheme should be ``http'' or
``https'', based on the current request's environ variables.
-
Set the environ attribute to a fully-populated WSGI
environment. The default implementation uses all of the above methods
and attributes, plus the get_stdin(), get_stderr(),
and add_cgi_vars() methods and the wsgi_file_wrapper
attribute. It also inserts a
SERVER_SOFTWARE key if not present,
as long as the origin_server attribute is a true value and the
server_software attribute is set.
Methods and attributes for customizing exception handling:
-
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.
- traceback_limit
-
The maximum number of frames to include in tracebacks output by the
default log_exception() method. If
None, all frames
are included.
| 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 error_status,
error_headers, and 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.
- 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.
- 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.
- 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:
- wsgi_file_wrapper
-
A
wsgi.file_wrapper factory, or None. The default value
of this attribute is the FileWrapper class from
wsgiref.util.
-
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 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:
- origin_server
-
This attribute should be set to a true value if the handler's
_write() and _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 BaseHandler, but
false in BaseCGIHandler and CGIHandler.
- http_version
-
If 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".
Release 2.5.2, documentation updated on 21st February, 2008.
See About this document... for information on suggesting changes.
|
