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.

1 files changed, 78 insertions, 0 deletions

diff --git a/docs/api/request.rst b/docs/api/request.rst
new file mode 100644
index 000000000..86202b830
--- /dev/null
+++ b/docs/api/request.rst
@@ -0,0 +1,78 @@
+.. _request_module:
+
+:mod:`repoze.bfg.request`
+---------------------------
+
+.. module:: repoze.bfg.request
+
+.. autoclass:: Request
+   :members:
+   :inherited-members:
+
+   .. attribute:: context
+
+     The :term:`context` will be available as the ``context``
+     attribute of the :term:`request` object.  It will be the context
+     object implied by the current request.  See
+     :ref:`traversal_chapter` for information about context objects.
+
+   .. attribute:: registry
+
+     The :term:`application registry` will be available as the
+     ``registry`` attribute of the :term:`request` object.  See
+     :ref:`zca_chapter` for more information about the application
+     registry.
+
+   .. attribute:: root
+
+      The :term:`root` object will be available as the ``root``
+      attribute of the :term:`request` object.  It will be the model
+      object at which traversal started (the root).  See
+      :ref:`traversal_chapter` for information about root objects.
+
+   .. attribute:: subpath
+
+      The traversal :term:`subpath` will be available as the
+      ``subpath`` attribute of the :term:`request` object.  It will
+      be a sequence containing zero or more elements (which will be
+      Unicode objects).  See :ref:`traversal_chapter` for information
+      about the subpath.
+
+   .. attribute:: traversed
+
+      The "traversal path" will be available as the ``traversed``
+      attribute of the :term:`request` object.  It will be a sequence
+      representing the ordered set of names that were used to
+      traverse to the :term:`context`, not including the view name or
+      subpath.  If there is a virtual root associated with the
+      request, the virtual root path is included within the traversal
+      path.  See :ref:`traversal_chapter` for more information.
+
+   .. attribute:: view_name
+
+      The :term:`view name` will be available as the ``view_name``
+      attribute of the :term:`request` object.  It will be a single
+      string (possibly the empty string if we're rendering a default
+      view).  See :ref:`traversal_chapter` for information about view
+      names.
+
+   .. attribute:: virtual_root
+
+      The :term:`virtual root` will be available as the
+      ``virtual_root`` attribute of the :term:`request` object.  It
+      will be the virtual root object implied by the current request.
+      See :ref:`vhosting_chapter` for more information about virtual
+      roots.
+
+   .. attribute:: virtual_root_path
+
+      The  :term:`virtual  root`  *path*  will be  available  as  the
+      ``virtual_root_path`` attribute  of the :term:`request` object.
+      It will  be a  sequence representing the  ordered set  of names
+      that were  used to  traverse to the  virtual root  object.  See
+      :ref:`vhosting_chapter`  for  more  information  about  virtual
+      roots.
+
+.. autofunction:: make_request_ascii
+
+