add docs

Chris McDonough

2012-09-16 277b2af26871a4d84730b6d3e38fbaa2f4102823

add docs

 docs/api/request.rst

@@ -161,6 +161,49 @@
      request, the value of this attribute will be ``None``. See
      :ref:`matched_route`.

   .. method:: subrequest(request, use_tweens=False)

      Obtain a response object from the Pyramid application based on
      information in the ``request`` object provided.  The ``request`` object
      must be an object that implements the Pyramid request interface (such
      as a :class:`pyramid.request.Request` instance).  If ``use_tweens`` is
      ``True``, the request will be sent to the :term:`tween` in the tween
      stack closest to the request ingress.  If ``use_tweens`` is ``False``,
      the request will be sent to the main router handler, and no tweens will
      be invoked.  This isn't *actually* a method of the Request object; it's
      a callable added when the Pyramid router is invoked, or when a
      subrequest is invoked.  This function also:
        
      - manages the threadlocal stack (so that
        :func:`~pyramid.threadlocal.get_current_request` and
        :func:`~pyramid.threadlocal.get_current_registry` work during a
        request)

      - Adds a ``registry`` attribute (the current Pyramid registry) and a
        ``subrequest`` attribute (a callable) to the request object it's
        handed.

      - sets request extensions (such as those added via
        :meth:`~pyramid.config.Configurator.add_request_method` or
        :meth:`~pyramid.config.Configurator.set_request_property`) on the
        request it's passed.

      - causes a :class:`~pyramid.event.NewRequest` event to be sent at the
        beginning of request processing.

      - causes a :class:`~pyramid.event.ContextFound` event to be sent
        when a context resource is found.
          
      - causes a :class:`~pyramid.event.NewResponse` event to be sent when
        the Pyramid application returns a response.

      - Calls any :term:`response callback` functions defined within the
        request's lifetime if a response is obtained from the Pyramid
        application.

      - Calls any :term:`finished callback` functions defined within the
        request's lifetime.

   .. automethod:: add_response_callback

   .. automethod:: add_finished_callback

 pyramid/router.py

@@ -163,6 +163,45 @@
        return response

    def subrequest(self, request, use_tweens=False):
        """
        Obtain a response object from the Pyramid application based on
        information in the ``request`` object provided.  The ``request``
        object must be an object that implements the Pyramid request
        interface (such as a :class:`pyramid.request.Request` instance).  If
        ``use_tweens`` is ``True``, the request will be sent to the
        :term:`tween` in the tween stack closest to the request ingress.  If
        ``use_tweens`` is ``False``, the request will be sent to the main
        router handler, and no tweens will be invoked.  This function also:
        
        - manages the threadlocal stack (so that
          :func:`~pyramid.threadlocal.get_current_request` and
          :func:`~pyramid.threadlocal.get_current_registry` work during a
          request)

        - Adds a ``registry`` attribute and a ``subrequest`` attribute to the
          request object it's handed.

        - sets request extensions (such as those added via
          :meth:`~pyramid.config.Configurator.add_request_method` or
          :meth:`~pyramid.config.Configurator.set_request_property`) on the
          request it's passed.

        - causes a :class:`~pyramid.event.NewRequest` event to be sent at the
          beginning of request processing.

        - causes a :class:`~pyramid.event.ContextFound` event to be sent
          when a context resource is found.
          
        - causes a :class:`~pyramid.event.NewResponse` event to be sent when
          the Pyramid application returns a response.

        - Calls any :term:`response callback` functions defined within the
          request's lifetime if a response is obtained from the Pyramid
          application.

        - Calls any :term:`finished callback` functions defined within the
          request's lifetime.
          """
        registry = self.registry
        has_listeners = self.registry.has_listeners
        notify = self.registry.notify