pylons.middleware – WSGI Middleware

Pylons’ WSGI middlewares

Module Contents

class pylons.middleware.StatusCodeRedirect(app, errors=(400, 401, 403, 404), path='/error/document')

Internally redirects a request based on status code

StatusCodeRedirect watches the response of the app it wraps. If the response is an error code in the errors sequence passed the request will be re-run with the path URL set to the path passed in.

This operation is non-recursive and the output of the second request will be used no matter what it is.

Should an application wish to bypass the error response (ie, to purposely return a 401), set environ['pylons.status_code_redirect'] = True in the application.

__init__(app, errors=(400, 401, 403, 404), path='/error/document')

Initialize the ErrorRedirect

errors
A sequence (list, tuple) of error code integers that should be caught.
path
The path to set for the next request down to the application.
class pylons.middleware.StaticJavascripts(**kwargs)

Middleware for intercepting requests for WebHelpers’ included javascript files.

Triggered when PATH_INFO begins with ‘/javascripts/’.

pylons.middleware.ErrorHandler(app, global_conf, **errorware)

ErrorHandler Toggle

If debug is enabled, this function will return the app wrapped in the WebError EvalException middleware which displays interactive debugging sessions when a traceback occurs.

Otherwise, the app will be wrapped in the WebError ErrorMiddleware, and the errorware dict will be passed into it. The ErrorMiddleware handles sending an email to the address listed in the .ini file, under email_to.

note:

The errorware dictionary is constructed from the settings in the DEFAULT section of development.ini. the recognised keys and settings at initialization are:
  • error_email = conf.get(‘email_to’)
  • error_log = conf.get(‘error_log’, None)
  • smtp_server = conf.get(‘smtp_server’,’localhost’)
  • error_subject_prefix = conf.get(‘error_subject_prefix’, ‘WebApp Error: ‘)
  • from_address = conf.get(‘from_address’, conf.get(‘error_email_from’, 'pylons@yourapp.com‘))
  • error_message = conf.get(‘error_message’, ‘An internal server error occurred’)

Referenced classes

Pylons middleware uses WebError to effect the error-handling. The two classes implicated are:

ErrorMiddleware

Error handler middleware

class weberror.errormiddleware.ErrorMiddleware(application, global_conf=None, debug=<NoDefault>, error_email=None, error_log=None, show_exceptions_in_wsgi_errors=<NoDefault>, from_address=None, smtp_server=None, smtp_username=None, smtp_password=None, smtp_use_tls=False, error_subject_prefix=None, error_message=None, xmlhttp_key=None, reporters=None)

Error handling middleware

Usage:

error_caching_wsgi_app = ErrorMiddleware(wsgi_app)

Settings:

debug:
If true, then tracebacks will be shown in the browser.
error_email:
an email address (or list of addresses) to send exception reports to
error_log:
a filename to append tracebacks to
show_exceptions_in_wsgi_errors:
If true, then errors will be printed to wsgi.errors (frequently a server error log, or stderr).
from_address, smtp_server, error_subject_prefix, smtp_username, smtp_password, smtp_use_tls:
variables to control the emailed exception reports
error_message:
When debug mode is off, the error message to show to users.
xmlhttp_key:
When this key (default _) is in the request GET variables (not POST!), expect that this is an XMLHttpRequest, and the response should be more minimal; it should not be a complete HTML page.

Environment Configuration:

paste.throw_errors:
If this setting in the request environment is true, then this middleware is disabled. This can be useful in a testing situation where you don’t want errors to be caught and transformed.
paste.expected_exceptions:
When this middleware encounters an exception listed in this environment variable and when the start_response has not yet occurred, the exception will be re-raised instead of being caught. This should generally be set by middleware that may (but probably shouldn’t be) installed above this middleware, and wants to get certain exceptions. Exceptions raised after start_response have been called are always caught since by definition they are no longer expected.

EvalException

Exception-catching middleware that allows interactive debugging.

This middleware catches all unexpected exceptions. A normal traceback, like produced by weberror.exceptions.errormiddleware.ErrorMiddleware is given, plus controls to see local variables and evaluate expressions in a local context.

This can only be used in single-process environments, because subsequent requests must go back to the same process that the exception originally occurred in. Threaded or non-concurrent environments both work.

This shouldn’t be used in production in any way. That would just be silly.

If calling from an XMLHttpRequest call, if the GET variable _ is given then it will make the response more compact (and less Javascripty), since if you use innerHTML it’ll kill your browser. You can look for the header X-Debug-URL in your 500 responses if you want to see the full debuggable traceback. Also, this URL is printed to wsgi.errors, so you can open it up in another browser window.

class weberror.evalexception.EvalException(application, global_conf=None, error_template_filename=None, xmlhttp_key=None, media_paths=None, templating_formatters=None, head_html='', footer_html='', reporters=None, libraries=None, **params)

Handles capturing an exception and turning it into an interactive exception explorer

media(req)
Static path where images and other files live
relay(req)
Relay a request to a remote machine for JS proxying
summary(req)
Returns a JSON-format summary of all the cached exception reports
view(req)
View old exception reports

Legacy

Changed in version 0.9.7: These functions were deprecated in Pylons 0.9.7, and have been superseded by the StatusCodeRedirect middleware.

pylons.middleware.ErrorDocuments(app, global_conf=None, mapper=None, **kw)

Wraps the app in error docs using Paste RecursiveMiddleware and ErrorDocumentsMiddleware

All the args are passed directly into the ErrorDocumentsMiddleware. If no mapper is given, a default error_mapper is passed in.

pylons.middleware.error_mapper(code, message, environ, global_conf=None, **kw)
Legacy function used with ErrorDocuments to provide a mapping of error codes to handle

Table Of Contents

This Page