Bug Fixes

---------

- When the ``Configurator`` is passed an instance of
  ``zope.component.registry.Components`` as a ``registry`` constructor
  argument, fix the instance up to have the attributes we expect of an
  instance of ``repoze.bfg.registry.Registry`` when ``setup_registry``
  is called.  This makes it possible to use the global Zope component
  registry as a BFG application registry.

Documentation
-------------

- Change renderings of ZCML directive documentation.

- Add a narrative documentation chapter: "Using the Zope Component
  Architecture in ``repoze.bfg``"

16 files changed, 0 insertions, 75 deletions

diff --git a/docs/zcml/adapter.rst b/docs/zcml/adapter.rst
index 48ed49f6c..83cce0c39 100644
--- a/docs/zcml/adapter.rst
+++ b/docs/zcml/adapter.rst
@@ -9,21 +9,17 @@ Attributes
 ~~~~~~~~~~
 
 ``factory``
-
   The adapter factory (often a class).
 
 ``provides``
-
   The :term:`interface` that an adapter instance resulting from a
   lookup will provide.
 
 ``for``
-
   Interfaces or classes to be adapted, separated by spaces,
   e.g. ``interfaces.IFoo interfaces.IBar``.
 
 ``name``
-
   The adapter name.
 
 Example
diff --git a/docs/zcml/authtktauthenticationpolicy.rst b/docs/zcml/authtktauthenticationpolicy.rst
index de1bcdcd6..e779fc9a8 100644
--- a/docs/zcml/authtktauthenticationpolicy.rst
+++ b/docs/zcml/authtktauthenticationpolicy.rst
@@ -11,12 +11,10 @@ Attributes
 ~~~~~~~~~~
 
 ``secret``
-
     The ``secret`` is a string that will be used to encrypt the data
     stored by the cookie.  It is required and has no default.
 
 ``callback``
-
     The ``callback`` is a Python dotted name to a function passed the
     string representing the userid stored in the cookie and the
     request as positional arguments.  The callback is expected to
@@ -26,18 +24,15 @@ Attributes
     exist with no groups.  It defaults to ``None``.
 
 ``cookie_name``
-
     The ``cookie_name`` is the name used for the cookie that contains
     the user information.  It defaults to ``repoze.bfg.auth_tkt``.
 
 ``secure``
-
     ``secure`` is a boolean value.  If it's set to "true", the cookie
     will only be sent back by the browser over a secure (HTTPS)
     connection.  It defaults to "false".
 
 ``include_ip``
-
     ``include_ip`` is a boolean value.  If it's set to true, the
     requesting IP address is made part of the authentication data in
     the cookie; if the IP encoded in the cookie differs from the IP of
@@ -45,7 +40,6 @@ Attributes
     defaults to "false".
 
 ``timeout``
-
     ``timeout`` is an integer value.  It represents the maximum age in
     seconds which the auth_tkt ticket will be considered valid.  If
     ``timeout`` is specified, and ``reissue_time`` is also specified,
@@ -54,7 +48,6 @@ Attributes
     valid forever.
 
 ``reissue_time``
-
     ``reissue_time`` is an integer value.  If ``reissue_time`` is
     specified, when we encounter a cookie that is older than the
     reissue time (in seconds), but younger that the ``timeout``, a new
@@ -64,7 +57,6 @@ Attributes
     authentication.
 
 ``max_age``
-
     ``max_age`` is the maximum age of the auth_tkt *cookie*, in
     seconds.  This differs from ``timeout`` inasmuch as ``timeout``
     represents the lifetime of the ticket contained in the cookie,
diff --git a/docs/zcml/configure.rst b/docs/zcml/configure.rst
index 20c0ed76a..7b479b2c0 100644
--- a/docs/zcml/configure.rst
+++ b/docs/zcml/configure.rst
@@ -13,7 +13,6 @@ Attributes
 ~~~~~~~~~~
 
 ``xmlns``
-
    The default XML namespace used for subdirectives.
 
 Example
diff --git a/docs/zcml/forbidden.rst b/docs/zcml/forbidden.rst
index 7540c28cb..bd2235ccf 100644
--- a/docs/zcml/forbidden.rst
+++ b/docs/zcml/forbidden.rst
@@ -13,7 +13,6 @@ Attributes
 ~~~~~~~~~~
 
 ``view``
-
   The :term:`dotted Python name` to a :term:`view callable`.  This
   attribute is required unless a ``renderer`` attribute also exists.
   If a ``renderer`` attribute exists on the directive, this attribute
@@ -21,7 +20,6 @@ Attributes
   :ref:`views_which_use_a_renderer`).
 
 ``attr``
-
   The attribute of the view callable to use if ``__call__`` is not
   correct (has the same meaning as in the context of
   :ref:`view_directive`; see the description of ``attr``
@@ -30,7 +28,6 @@ Attributes
   .. note:: This feature is new as of :mod:`repoze.bfg` 1.1.
 
 ``renderer``
-
   This is either a single string term (e.g. ``json``) or a string
   implying a path or :term:`resource specification`
   (e.g. ``templates/views.pt``) used when the view returns a
@@ -41,7 +38,6 @@ Attributes
   .. note:: This feature is new as of :mod:`repoze.bfg` 1.1.
 
 ``wrapper``
-
   The :term:`view name` (*not* an object dotted name) of another view
   declared elsewhere in ZCML (or via the ``@bfg_view`` decorator)
   which will receive the response body of this view as the
diff --git a/docs/zcml/include.rst b/docs/zcml/include.rst
index 5e22f584a..149ddb67a 100644
--- a/docs/zcml/include.rst
+++ b/docs/zcml/include.rst
@@ -13,11 +13,9 @@ Attributes
 ~~~~~~~~~~
 
 ``package``
-
    A :term:`dotted Python name` which references a Python :term:`package`.
 
 ``filename``
-
    An absolute or relative filename which references a ZCML file.
 
 The ``package`` and ``filename`` attributes can be used together or
diff --git a/docs/zcml/notfound.rst b/docs/zcml/notfound.rst
index 76846d770..141cac6f9 100644
--- a/docs/zcml/notfound.rst
+++ b/docs/zcml/notfound.rst
@@ -12,7 +12,6 @@ Attributes
 ~~~~~~~~~~
 
 ``view``
-
   The :term:`dotted Python name` to a :term:`view callable`.  This
   attribute is required unless a ``renderer`` attribute also exists.
   If a ``renderer`` attribute exists on the directive, this attribute
@@ -20,7 +19,6 @@ Attributes
   :ref:`views_which_use_a_renderer`).
 
 ``attr``
-
   The attribute of the view callable to use if ``__call__`` is not
   correct (has the same meaning as in the context of
   :ref:`view_directive`; see the description of ``attr``
@@ -29,7 +27,6 @@ Attributes
   .. note:: This feature is new as of :mod:`repoze.bfg` 1.1.
 
 ``renderer``
-
   This is either a single string term (e.g. ``json``) or a string
   implying a path or :term:`resource specification`
   (e.g. ``templates/views.pt``) used when the view returns a
@@ -40,7 +37,6 @@ Attributes
   .. note:: This feature is new as of :mod:`repoze.bfg` 1.1.
 
 ``wrapper``
-
   The :term:`view name` (*not* an object dotted name) of another view
   declared elsewhere in ZCML (or via the ``@bfg_view`` decorator)
   which will receive the response body of this view as the
diff --git a/docs/zcml/remoteuserauthenticationpolicy.rst b/docs/zcml/remoteuserauthenticationpolicy.rst
index 61f519e4c..0435bfbdb 100644
--- a/docs/zcml/remoteuserauthenticationpolicy.rst
+++ b/docs/zcml/remoteuserauthenticationpolicy.rst
@@ -11,13 +11,11 @@ Attributes
 ~~~~~~~~~~
 
 ``environ_key``
-
     The ``environ_key`` is the name that will be used to obtain the
     remote user value from the WSGI environment.  It defaults to
     ``REMOTE_USER``.
 
 ``callback``
-
     The ``callback`` is a Python dotted name to a function passed the
     string representing the remote user and the request as positional
     arguments.  The callback is expected to return None if the user
diff --git a/docs/zcml/renderer.rst b/docs/zcml/renderer.rst
index 1a3942ede..5eb4f03f8 100644
--- a/docs/zcml/renderer.rst
+++ b/docs/zcml/renderer.rst
@@ -10,12 +10,10 @@ Attributes
 ~~~~~~~~~~
 
 ``factory``
-
     A :term:`dotted Python name` referencing a callable object that
     accepts a renderer name and returns a :term:`renderer` object.
 
 ``name``
-
    The renderer name, which is a string.
 
 Examples
diff --git a/docs/zcml/repozewho1authenticatiohnpolicy.rst b/docs/zcml/repozewho1authenticatiohnpolicy.rst
index a41ae08e0..62713e822 100644
--- a/docs/zcml/repozewho1authenticatiohnpolicy.rst
+++ b/docs/zcml/repozewho1authenticatiohnpolicy.rst
@@ -11,7 +11,6 @@ Attributes
 ~~~~~~~~~~
 
 ``identifier_name``
-
     The ``identifier_name`` controls the name used to look up the
     :term:`repoze.who` "identifier" plugin within
     ``request.environ['repoze.who.plugins']`` which is used by this
@@ -19,7 +18,6 @@ Attributes
     ``auth_tkt``.
 
 ``callback``
-
     The ``callback`` is a Python dotted name to a function passed the
     repoze.who identity and the request as positional arguments.  The
     callback is expected to return None if the user represented by the
diff --git a/docs/zcml/resource.rst b/docs/zcml/resource.rst
index 45aa1ce53..80a5e6722 100644
--- a/docs/zcml/resource.rst
+++ b/docs/zcml/resource.rst
@@ -10,12 +10,10 @@ Attributes
 ~~~~~~~~~~
 
 ``to_override``
-
    A :term:`resource specification` specifying the resource to be
    overridden.
 
 ``override_with``
-
    A :term:`resource specification` specifying the resource which
    is used as the override.
 
diff --git a/docs/zcml/route.rst b/docs/zcml/route.rst
index d3181bdf6..bb842819d 100644
--- a/docs/zcml/route.rst
+++ b/docs/zcml/route.rst
@@ -10,32 +10,27 @@ Attributes
 ~~~~~~~~~~
 
 ``path``
-
   The path of the route e.g. ``ideas/:idea``.  This attribute is
   required.  See :ref:`route_path_pattern_syntax` for information
   about the syntax of route paths.
 
 ``name``
-
   The name of the route, e.g. ``myroute``.  This attribute is
   required.  It must be unique among all defined routes in a given
   configuration.
 
 ``factory``
-
   The :term:`dotted Python name` to a function that will generate a
   :mod:`repoze.bfg` context object when this route matches.
   e.g. ``mypackage.models.MyFactoryClass``.  If this argument is not
   specified, a default root factory will be used.
 
 ``view``
-
   The :term:`dotted Python name` to a function that will be used as a
   view callable when this route matches.
   e.g. ``mypackage.views.my_view``.
 
 ``xhr``
-
   This value should be either ``True`` or ``False``.  If this value is
   specified and is ``True``, the :term:`request` must possess an
   ``HTTP_X_REQUESTED_WITH`` (aka ``X-Requested-With``) header for this
@@ -46,7 +41,6 @@ Attributes
   .. note:: This feature is new as of :mod:`repoze.bfg` 1.1.
 
 ``request_method``
-
   A string representing an HTTP method name, e.g. ``GET``, ``POST``,
   ``HEAD``, ``DELETE``, ``PUT``.  If this argument is not specified,
   this route will match if the request has *any* request method.  If
@@ -55,7 +49,6 @@ Attributes
   .. note:: This feature is new as of :mod:`repoze.bfg` 1.1.
 
 ``path_info``
-
   The value of this attribute represents a regular expression pattern
   that will be tested against the ``PATH_INFO`` WSGI environment
   variable.  If the regex matches, this predicate will be true.  If
@@ -64,7 +57,6 @@ Attributes
   .. note:: This feature is new as of :mod:`repoze.bfg` 1.1.
 
 ``request_param``
-
   This value can be any string.  A view declaration with this
   attribute ensures that the associated route will only match when the
   request has a key in the ``request.params`` dictionary (an HTTP
@@ -79,7 +71,6 @@ Attributes
   .. note:: This feature is new as of :mod:`repoze.bfg` 1.1.
 
 ``header``
-
   The value of this attribute represents an HTTP header name or a
   header name/value pair.  If the value contains a ``:`` (colon), it
   will be considered a name/value pair (e.g. ``User-Agent:Mozilla/.*``
@@ -100,7 +91,6 @@ Attributes
   .. note:: This feature is new as of :mod:`repoze.bfg` 1.1.
 
 ``accept``
-
   The value of this attribute represents a match query for one or more
   mimetypes in the ``Accept`` HTTP request header.  If this value is
   specified, it must be in one of the following forms: a mimetype
@@ -113,7 +103,6 @@ Attributes
   .. note:: This feature is new as of :mod:`repoze.bfg` 1.1.
 
 ``custom_predicates``
-
   This value should be a sequence of references to custom predicate
   callables.  Use custom predicates when no set of predefined
   predicates does what you need.  Custom predicates can be combined
@@ -129,7 +118,6 @@ Attributes
   .. note:: This feature is new as of :mod:`repoze.bfg` 1.2.
 
 ``view_context``
-
   The :term:`dotted Python name` to a class or an interface that the
   :term:`context` of the view should match for the view named by the
   route to be used.  This attribute is only useful if the ``view``
@@ -143,7 +131,6 @@ Attributes
   these are valid older spellings.
 
 ``view_permission``
-
   The permission name required to invoke the view associated with this
   route.  e.g. ``edit``. (see :ref:`using_security_with_urldispatch`
   for more information about permissions).
@@ -154,7 +141,6 @@ Attributes
   This attribute can also be spelled as ``permission``.
 
 ``view_renderer``
-
   This is either a single string term (e.g. ``json``) or a string
   implying a path or :term:`resource specification`
   (e.g. ``templates/views.pt``).  If the renderer value is a single
@@ -177,7 +163,6 @@ Attributes
   .. note:: This feature is new as of :mod:`repoze.bfg` 1.1.
 
 ``view_request_type``
-
   A :term:`dotted Python name` to an interface representing a
   :term:`request type`.  If this argument is not specified, any
   request type will be considered a match for the view associated with
@@ -189,7 +174,6 @@ Attributes
   This attribute can also be spelled as ``request_type``.
 
 ``view_containment``
-
   This value should be a :term:`dotted Python name` string
   representing the class that a graph traversal parent object of the
   :term:`context` must be an instance of (or :term:`interface` that a
@@ -204,7 +188,6 @@ Attributes
   .. note:: This feature is new as of :mod:`repoze.bfg` 1.1.
 
 ``view_attr``
-
   The view machinery defaults to using the ``__call__`` method of the
   view callable (or the function itself, if the view callable is a
   function) to obtain a response dictionary.  The ``attr`` value allows
diff --git a/docs/zcml/scan.rst b/docs/zcml/scan.rst
index d48cf66b4..679f035e2 100644
--- a/docs/zcml/scan.rst
+++ b/docs/zcml/scan.rst
@@ -11,7 +11,6 @@ Attributes
 ~~~~~~~~~~
 
 ``package``
-
     The package to scan or the single dot (``.``), meaning the
     "current" package (the package in which the ZCML file lives).
 
diff --git a/docs/zcml/static.rst b/docs/zcml/static.rst
index 23cd57538..1a11f222c 100644
--- a/docs/zcml/static.rst
+++ b/docs/zcml/static.rst
@@ -12,13 +12,11 @@ Attributes
 ~~~~~~~~~~
 
 ``name``
-
   The (application-root-relative) URL prefix of the static directory.
   For example, to serve static files from ``/static`` in most
   applications, you would provide a ``name`` of ``static``.
 
 ``path``
-
   A path to a directory on disk where the static files live.  This
   path may either be 1) absolute (e.g. ``/foo/bar/baz``) 2)
   Python-package-relative (e.g. (``packagename:foo/bar/baz``) or 3)
@@ -26,7 +24,6 @@ Attributes
   contains the directive (e.g. ``foo/bar/baz``).
 
 ``cache_max_age``
-
   The number of seconds that the static resource can be cached, as
   represented in the returned response's ``Expires`` and/or
   ``Cache-Control`` headers, when any static file is served from this
diff --git a/docs/zcml/subscriber.rst b/docs/zcml/subscriber.rst
index ef56d2b1c..371ec0752 100644
--- a/docs/zcml/subscriber.rst
+++ b/docs/zcml/subscriber.rst
@@ -11,7 +11,6 @@ Attributes
 ~~~~~~~~~~
 
 ``for``
-
    The class or :term:`interface` that you are subscribing the
    listener for, e.g. :class:`repoze.bfg.interfaces.INewRequest`.
    Registering a subscriber for a specific class or interface limits
@@ -20,7 +19,6 @@ Attributes
    (implying *any* event type).
 
 ``handler``
-
    A :term:`dotted Python name` which references an event handler
    callable.  The callable should accept a single argument: ``event``.
    The return value of the callable is ignored.
diff --git a/docs/zcml/utility.rst b/docs/zcml/utility.rst
index 88198eaa0..1341dfb83 100644
--- a/docs/zcml/utility.rst
+++ b/docs/zcml/utility.rst
@@ -9,22 +9,18 @@ Attributes
 ~~~~~~~~~~
 
 ``component``
-
   The utility component (cannot be specified if ``factory`` is
   specified).
 
 ``factory``
-
   A factory that creates a component (cannot be specified if
   ``component`` is specified).
 
 ``provides``
-
   The :term:`interface` that an utility instance resulting from a
   lookup will provide.
 
 ``name``
-
   The utility name.
 
 Example
diff --git a/docs/zcml/view.rst b/docs/zcml/view.rst
index ea55352a8..d33a9a9a5 100644
--- a/docs/zcml/view.rst
+++ b/docs/zcml/view.rst
@@ -27,7 +27,6 @@ Non-Predicate Attributes
 ########################
 
 ``view``
-
   The :term:`dotted Python name` to a :term:`view callable`.  This
   attribute is required unless a ``renderer`` attribute also exists.
   If a ``renderer`` attribute exists on the directive, this attribute
@@ -35,13 +34,11 @@ Non-Predicate Attributes
   :ref:`views_which_use_a_renderer`).
 
 ``permission``
-
   The name of a *permission* that the user must possess in order to
   call the view.  See :ref:`view_security_section` for more
   information about view security and permissions.
 
 ``attr``
-
   The view machinery defaults to using the ``__call__`` method of the
   view callable (or the function itself, if the view callable is a
   function) to obtain a response dictionary.  The ``attr`` value
@@ -55,7 +52,6 @@ Non-Predicate Attributes
   .. note:: This feature is new as of :mod:`repoze.bfg` 1.1.
 
 ``renderer``
-
   This is either a single string term (e.g. ``json``) or a string
   implying a path or :term:`resource specification`
   (e.g. ``templates/views.pt``).  If the renderer value is a single
@@ -90,7 +86,6 @@ Non-Predicate Attributes
   .. note:: This feature is new as of :mod:`repoze.bfg` 1.1.
 
 ``wrapper``
-
   The :term:`view name` (*not* an object dotted name) of another view
   declared elsewhere in ZCML (or via the ``@bfg_view`` decorator)
   which will receive the response body of this view as the
@@ -113,12 +108,10 @@ Predicate Attributes
 ####################
 
 ``name``
-
   The *view name*.  Read the :ref:`traversal_chapter` to understand
   the concept of a view name.
 
 ``context``
-
   A :term:`dotted Python name` representing the Python class that the
   :term:`context` must be an instance of, *or* the :term:`interface`
   that the :term:`context` must provide in order for this view to be
@@ -129,7 +122,6 @@ Predicate Attributes
   spelling).
 
 ``route_name``
-
   *This attribute services an advanced feature that isn't often used
   unless you want to perform traversal after a route has matched.*
   This value must match the ``name`` of a ``<route>`` declaration (see
@@ -142,7 +134,6 @@ Predicate Attributes
   advanced feature.
 
 ``request_type``
-
   This value should be a :term:`dotted Python name` string
   representing the :term:`interface` that the :term:`request` must
   have in order for this view to be found and called.  The presence of
@@ -154,7 +145,6 @@ Predicate Attributes
   attribute instead for maximum forward compatibility.
 
 ``request_method``
-
   This value can either be one of the strings 'GET', 'POST', 'PUT',
   'DELETE', or 'HEAD' representing an HTTP ``REQUEST_METHOD``.  A view
   declaration with this attribute ensures that the view will only be
@@ -164,7 +154,6 @@ Predicate Attributes
   .. note:: This feature is new as of :mod:`repoze.bfg` 1.1.
 
 ``request_param``
-
   This value can be any string.  A view declaration with this
   attribute ensures that the view will only be called when the request
   has a key in the ``request.params`` dictionary (an HTTP ``GET`` or
@@ -178,7 +167,6 @@ Predicate Attributes
   .. note:: This feature is new as of :mod:`repoze.bfg` 1.1.
 
 ``containment``
-
   This value should be a :term:`dotted Python name` string
   representing the class that a graph traversal parent object of the
   :term:`context` must be an instance of (or :term:`interface` that a
@@ -190,7 +178,6 @@ Predicate Attributes
   .. note:: This feature is new as of :mod:`repoze.bfg` 1.1.
 
 ``xhr``
-
   This value should be either ``True`` or ``False``.  If this value is
   specified and is ``True``, the :term:`request` must possess an
   ``HTTP_X_REQUESTED_WITH`` (aka ``X-Requested-With``) header that has
@@ -201,7 +188,6 @@ Predicate Attributes
   .. note:: This feature is new as of :mod:`repoze.bfg` 1.1.
 
 ``accept``
-
   The value of this attribute represents a match query for one or more
   mimetypes in the ``Accept`` HTTP request header.  If this value is
   specified, it must be in one of the following forms: a mimetype
@@ -213,7 +199,6 @@ Predicate Attributes
   .. note:: This feature is new as of :mod:`repoze.bfg` 1.1.
 
 ``header``
-
   The value of this attribute represents an HTTP header name or a
   header name/value pair.  If the value contains a ``:`` (colon), it
   will be considered a name/value pair (e.g. ``User-Agent:Mozilla/.*``
@@ -233,7 +218,6 @@ Predicate Attributes
   .. note:: This feature is new as of :mod:`repoze.bfg` 1.1.
 
 ``path_info``
-
   The value of this attribute represents a regular expression pattern
   that will be tested against the ``PATH_INFO`` WSGI environment
   variable.  If the regex matches, this predicate will be true.
@@ -241,7 +225,6 @@ Predicate Attributes
   .. note:: This feature is new as of :mod:`repoze.bfg` 1.1.
 
 ``custom_predicates``
-
   This value should be a sequence of references to custom predicate
   callables (e.g. ``dotted.name.one dotted.name.two``, if used in
   ZCML; a :term:`dotted Python name` to each callable separated by a