From af2323bcb169653dd2d76d7c40909fd881041beb Mon Sep 17 00:00:00 2001 From: Chris McDonough Date: Sun, 24 Jul 2011 01:01:38 -0400 Subject: first cut --- CHANGES.txt | 59 +++++++++++++++++++++++++++++++++++++++++++++++++++++++++++ 1 file changed, 59 insertions(+) (limited to 'CHANGES.txt') diff --git a/CHANGES.txt b/CHANGES.txt index 3c232d880..b1979347a 100644 --- a/CHANGES.txt +++ b/CHANGES.txt @@ -51,6 +51,65 @@ Features argument; this chain will be returned to Pyramid as a single view callable. +- New configurator directive: + ``pyramid.config.Configurator.add_request_handler``. This directive adds + a request handler factory. + + A request handler factory is used to wrap the Pyramid router's primary + request handling function. This is a feature usually only used by + framework extensions, to provide, for example, view timing support and as + a convenient place to hang bookkeeping code that examines exceptions + before they are returned to the server. + + A request handler factory (passed as ``handler_factory``) must be a + callable which accepts two arguments: ``handler`` and ``registry``. + ``handler`` will be the request handler being wrapped. ``registry`` will + be the Pyramid application registry represented by this Configurator. A + request handler factory must return a request handler when it is called. + + A request handler accepts a request object and returns a response object. + + Here's an example of creating both a handler factory and a handler, and + registering the handler factory: + + .. code-block:: python + + import time + + def timing_handler_factory(handler, registry): + if registry.settings['do_timing']: + # if timing support is enabled, return a wrapper + def timing_handler(request): + start = time.time() + try: + response = handler(request) + finally: + end = time.time() + print: 'The request took %s seconds' % (end - start) + return response + return timing_handler + # if timing support is not enabled, return the original handler + return handler + + config.add_request_handler(timing_handler_factory, 'timing') + + The ``request`` argument to the handler will be the request created by + Pyramid's router when it receives a WSGI request. + + If more than one request handler factory is registered into a single + configuration, the request handlers will be chained together. The first + request handler factory added (in code execution order) will be called + with the default Pyramid request handler, the second handler factory added + will be called with the result of the first handler factory, ad + infinitum. The Pyramid router will use the outermost wrapper in this chain + (which is a bit like a WSGI middleware "pipeline") as its handler + function. + + The ``name`` argument to this function is required. The name is used as a + key for conflict detection. No two request handler factories may share + the same name in the same configuration (unless + automatic_conflict_resolution is able to resolve the conflict or + this is an autocommitting configurator). 1.1 (2011-07-22) ================ -- cgit v1.2.3