From df15ed98612e7962e3122da52d8d5f5b9d8882b2 Mon Sep 17 00:00:00 2001
From: Chris McDonough <chrism@plope.com>
Date: Sat, 4 Jun 2011 18:43:25 -0400
Subject: - It is now possible to control how the Pyramid router calls the WSGI
   ``start_response`` callable and obtains the WSGI ``app_iter`` based on  
 adapting the response object to the new ``pyramid.interfaces.IResponder``  
 interface.  The default ``IResponder`` uses Pyramid 1.0's logic to do this.  
 To override the responder::

     from pyramid.interfaces import IResponder
     from pyramid.response import Response
     from myapp import MyResponder

     config.registry.registerAdapter(MyResponder, (Response,),
                                     IResponder, name='')

  This makes it possible to reuse response object implementations which have,
  for example, their own ``__call__`` expected to be used as a WSGI
  application (like ``pyramid.response.Response``), e.g.:

     class MyResponder(object):
         def __init__(self, response):
             """ Obtain a reference to the response """
             self.response = response
         def __call__(self, request, start_response):
             """ Call start_response and return an app_iter """
             app_iter = self.response(request.environ, start_response)
             return app_iter
---
 docs/narr/hooks.rst | 36 ++++++++++++++++++++++++++++++++++++
 1 file changed, 36 insertions(+)

(limited to 'docs/narr')

diff --git a/docs/narr/hooks.rst b/docs/narr/hooks.rst
index d620b5672..aa151d281 100644
--- a/docs/narr/hooks.rst
+++ b/docs/narr/hooks.rst
@@ -521,6 +521,42 @@ The default context URL generator is available for perusal as the class
 <http://github.com/Pylons/pyramid/blob/master/pyramid/traversal.py>`_ of the
 :term:`Pylons` GitHub Pyramid repository.
 
+.. index::
+   single: IResponder
+
+.. _using_iresponder:
+
+Changing How Pyramid Treats Response Objects
+--------------------------------------------
+
+It is possible to control how the Pyramid :term:`router` calls the WSGI
+``start_response`` callable and obtains the WSGI ``app_iter`` based on
+adapting the response object to the :class: `pyramid.interfaces.IResponder`
+interface.  The default ``IResponder`` uses the three attributes ``status``,
+``headerlist``, and ``app_iter`` attached to the response object, and calls
+``start_response`` with the status and headerlist, returning the
+``app_iter``.  To override the responder::
+
+     from pyramid.interfaces import IResponder
+     from pyramid.response import Response
+     from myapp import MyResponder
+
+     config.registry.registerAdapter(MyResponder, (Response,),
+                                     IResponder, name='')
+
+Overriding makes it possible to reuse response object implementations which
+have, for example, their own ``__call__`` expected to be used as a WSGI
+application (like :class:`pyramid.response.Response`), e.g.:
+
+     class MyResponder(object):
+         def __init__(self, response):
+             """ Obtain a reference to the response """
+             self.response = response
+         def __call__(self, request, start_response):
+             """ Call start_response and return an app_iter """
+             app_iter = self.response(request.environ, start_response)
+             return app_iter
+
 .. index::
    single: view mapper
 
-- 
cgit v1.2.3