Documentation

-------------

- Add an API chapter for the ``repoze.bfg.request`` module, which
  includes documentation for the ``repoze.bfg.request.Request`` class
  (the "request object").

- Modify the "Request and Response" narrative chapter to reference the
  new ``repoze.bfg.request`` API chapter.  Some content was moved from
  this chapter into the API documentation itself.

Features
--------

- A new ``repoze.bfg.request.Request.add_response_callback`` API has
  been added.  This method is documented in the new
  ``repoze.bfg.request`` API chapter.  It can be used to influence
  response values before a concrete response object has been created.

Internal
--------

- The (internal) feature which made it possible to attach a
  ``global_response_headers`` attribute to the request (which was
  assumed to contain a sequence of header key/value pairs which would
  later be added to the response by the router), has been removed.
  The functionality of
  ``repoze.bfg.request.Request.add_response_callback`` takes its
  place.

4 files changed, 74 insertions, 11 deletions

diff --git a/repoze/bfg/tests/test_authentication.py b/repoze/bfg/tests/test_authentication.py
index a6f34970f..bce80ca20 100644
--- a/repoze/bfg/tests/test_authentication.py
+++ b/repoze/bfg/tests/test_authentication.py
@@ -416,9 +416,11 @@ class TestAuthTktCookieHelper(unittest.TestCase):
         request = self._makeRequest({'HTTP_COOKIE':'auth_tkt=bogus'})
         result = plugin.identify(request)
         self.failUnless(result)
-        response_headers = request.global_response_headers
-        self.assertEqual(len(response_headers), 3)
-        self.assertEqual(response_headers[0][0], 'Set-Cookie')
+        self.assertEqual(len(request.callbacks), 1)
+        response = DummyResponse()
+        request.callbacks[0](None, response)
+        self.assertEqual(len(response.headers.added), 3)
+        self.assertEqual(response.headers.added[0][0], 'Set-Cookie')
 
     def test_remember(self):
         plugin = self._makeOne('secret')
@@ -595,6 +597,10 @@ class DummyContext:
 class DummyRequest:
     def __init__(self, environ):
         self.environ = environ
+        self.callbacks = []
+
+    def add_response_callback(self, callback):
+        self.callbacks.append(callback)
 
 class DummyWhoPlugin:
     def remember(self, environ, identity):
@@ -652,3 +658,14 @@ class DummyAuthTktModule(object):
     class BadTicket(Exception):
         pass
 
+class DummyHeaders:
+    def __init__(self):
+        self.added = []
+
+    def add(self, k, v):
+        self.added.append((k, v))
+
+class DummyResponse:
+    def __init__(self):
+        self.headers = DummyHeaders()
+        
diff --git a/repoze/bfg/tests/test_request.py b/repoze/bfg/tests/test_request.py
index 7b3d0ce7b..8d23e360f 100644
--- a/repoze/bfg/tests/test_request.py
+++ b/repoze/bfg/tests/test_request.py
@@ -157,6 +157,33 @@ class TestRequest(unittest.TestCase):
         result = inst.values()
         self.assertEqual(result, environ.values())
 
+    def test_add_response_callback(self):
+        inst = self._makeOne({})
+        self.assertEqual(inst.response_callbacks, ())
+        def callback(request, response):
+            """ """
+        inst.add_response_callback(callback)
+        self.assertEqual(inst.response_callbacks, [callback])
+        inst.add_response_callback(callback)
+        self.assertEqual(inst.response_callbacks, [callback, callback])
+
+    def test__process_response_callbacks(self):
+        inst = self._makeOne({})
+        def callback1(request, response):
+            request.called1 = True
+            response.called1 = True
+        def callback2(request, response):
+            request.called2  = True
+            response.called2 = True
+        inst.response_callbacks = [callback1, callback2]
+        response = DummyResponse()
+        inst._process_response_callbacks(response)
+        self.assertEqual(inst.called1, True)
+        self.assertEqual(inst.called2, True)
+        self.assertEqual(response.called1, True)
+        self.assertEqual(response.called2, True)
+        self.assertEqual(inst.response_callbacks, ())
+
 class Test_route_request_iface(unittest.TestCase):
     def _callFUT(self, name):
         from repoze.bfg.request import route_request_iface
@@ -175,10 +202,11 @@ class Test_add_global_response_headers(unittest.TestCase):
 
     def test_it(self):
         request = DummyRequest()
-        headers = [('a', 1), ('b', 2)]
-        request.global_response_headers = headers[:]
+        response = DummyResponse()
         self._callFUT(request, [('c', 1)])
-        self.assertEqual(request.global_response_headers, headers + [('c', 1)])
+        self.assertEqual(len(request.response_callbacks), 1)
+        request.response_callbacks[0](None, response)
+        self.assertEqual(response.headers.added,  [('c', 1)] )
 
 class DummyRequest:
     def __init__(self, environ=None):
@@ -186,10 +214,21 @@ class DummyRequest:
             environ = {}
         self.environ = environ
 
+    def add_response_callback(self, callback):
+        self.response_callbacks = [callback]
+
 class DummyNewRequestEvent:
     def __init__(self, request):
         self.request = request
         
-
+class DummyHeaders:
+    def __init__(self):
+        self.added = []
+    def add(self, k, v):
+        self.added.append((k, v))
+
+class DummyResponse:
+    def __init__(self):
+        self.headers = DummyHeaders()
 
 
diff --git a/repoze/bfg/tests/test_router.py b/repoze/bfg/tests/test_router.py
index 6e25b0584..1ce499e41 100644
--- a/repoze/bfg/tests/test_router.py
+++ b/repoze/bfg/tests/test_router.py
@@ -372,7 +372,7 @@ class TestRouter(unittest.TestCase):
         why = exc_raised(NotFound, router, environ, start_response)
         self.assertEqual(why[0], 'notfound')
 
-    def test_call_request_has_global_response_headers(self):
+    def test_call_request_has_response_callbacks(self):
         from zope.interface import Interface
         from zope.interface import directlyProvides
         class IContext(Interface):
@@ -385,15 +385,16 @@ class TestRouter(unittest.TestCase):
         response = DummyResponse('200 OK')
         response.headerlist = [('a', 1)]
         def view(context, request):
-            request.global_response_headers = [('b', 2)]
+            def callback(request, response):
+                response.called_back = True
+            request.response_callbacks = [callback]
             return response
         environ = self._makeEnviron()
         self._registerView(view, '', IViewClassifier, IRequest, IContext)
         router = self._makeOne()
         start_response = DummyStartResponse()
         router(environ, start_response)
-        self.assertEqual(start_response.status, '200 OK')
-        self.assertEqual(start_response.headers, [('a', 1), ('b', 2)])
+        self.assertEqual(response.called_back, True)
 
     def test_call_eventsends(self):
         from repoze.bfg.interfaces import INewRequest
diff --git a/repoze/bfg/tests/test_testing.py b/repoze/bfg/tests/test_testing.py
index b24843e77..b900a44a4 100644
--- a/repoze/bfg/tests/test_testing.py
+++ b/repoze/bfg/tests/test_testing.py
@@ -514,6 +514,12 @@ class TestDummyRequest(unittest.TestCase):
         request = self._makeOne(water = 1)
         self.assertEqual(request.water, 1)
 
+    def test_add_response_callback(self):
+        request = self._makeOne()
+        request.add_response_callback(1)
+        self.assertEqual(request.response_callbacks, [1])
+        
+
 class TestDummyTemplateRenderer(unittest.TestCase):
     def _getTargetClass(self, ):
         from repoze.bfg.testing import DummyTemplateRenderer