garden todo, add docs about exception handling

2 files changed, 30 insertions, 9 deletions

diff --git a/TODO.txt b/TODO.txt
index 202d1afbb..1686c27a2 100644
--- a/TODO.txt
+++ b/TODO.txt
@@ -82,15 +82,6 @@ Nice-to-Have
 - Deprecate pyramid.security.view_execution_permitted (it only works for
   traversal).
 
-- Create a function which performs a recursive request.
-
-- Create a ``render_view`` that works by using config.derive_view against an
-  existing view callable instead of querying the registry (some sort of API
-  for rendering a view callable object to a response from within another view
-  callable). Possible idea: have config.add_view mark up the
-  function/method/class like @view_config does, then use the attached info to
-  derive a view callable whenever called via some API.
-
 - Provide a ``has_view`` function.
 
 - Update App engine chapter with less creaky directions.
diff --git a/docs/narr/subrequest.rst b/docs/narr/subrequest.rst
index 8429fe7fe..39f985520 100644
--- a/docs/narr/subrequest.rst
+++ b/docs/narr/subrequest.rst
@@ -96,6 +96,36 @@ callable directly.  Subrequests are slower and are less convenient if you
 actually do want just the literal information returned by a function that
 happens to be a view callable.
 
+Note that if a view callable invoked by a subrequest raises an exception, the
+exception will usually bubble up to the invoking code:
+
+.. code-block:: python
+
+   from wsgiref.simple_server import make_server
+   from pyramid.config import Configurator
+   from pyramid.request import Request
+
+   def view_one(request):
+       subreq = Request.blank('/view_two')
+       response = request.subrequest(subreq)
+       return response
+
+   def view_two(request):
+       raise ValueError('foo')
+
+   if __name__ == '__main__':
+       config = Configurator()
+       config.add_route('one', '/view_one')
+       config.add_route('two', '/view_two')
+       config.add_view(view_one, route_name='one')
+       config.add_view(view_two, route_name='two', renderer='string')
+       app = config.make_wsgi_app()
+       server = make_server('0.0.0.0', 8080, app)
+       server.serve_forever()
+
+In the above application, the call to ``request.subrequest(subreq)`` will
+raise a :exc:`ValueError` exception instead of obtaining a "500" response.
+
 The :meth:`pyramid.request.Request.subrequest` API accepts two arguments: a
 positional argument ``request`` that must be provided, and and ``use_tweens``
 keyword argument that is optional; it defaults to ``False``.