Make views that do not have a route_name match when any route is used.

3 files changed, 185 insertions, 60 deletions

diff --git a/docs/narr/hybrid.rst b/docs/narr/hybrid.rst
index a8c8fc0eb..c3e61d906 100644
--- a/docs/narr/hybrid.rst
+++ b/docs/narr/hybrid.rst
@@ -13,11 +13,11 @@ However, for some problems, it's useful to use both traversal *and*
 URL dispatch within the same application.  :mod:`repoze.bfg` makes
 this possible.
 
-Trying to explain a "hybrid" URL dispatch + traversal model is
-difficult because combining the two concepts seems to break a law of
+Reasoning about a "hybrid" URL dispatch + traversal model is difficult
+because the combination of the two concepts seems to break the law of
 `the magical number seven plus or minus 2
-<http://en.wikipedia.org/wiki/The_Magical_Number_Seven,_Plus_or_Minus_Two>`_
-().  This is because, as a user, you need to understand 1) URL pattern
+<http://en.wikipedia.org/wiki/The_Magical_Number_Seven,_Plus_or_Minus_Two>`_.
+This is because, as a user, you need to understand 1) URL pattern
 matching, 2) root factories and 3) the traversal algorithm, and the
 interactions between all of them.  Therefore, use of this pattern is
 not recommended unless you *really* need to use it.
@@ -29,6 +29,15 @@ feature.
 The Schism
 ----------
 
+BFG, when used according to the currently published tutorials in its
+documentation is sort of a dual-mode framework.  The tutorials explain
+how to create an application terms of using either :term:`url
+dispatch` *or* :term:`traversal`.  It's useful to examine that pattern
+in order to understand the schism between the two.
+
+URL Dispatch Only
+~~~~~~~~~~~~~~~~~
+
 An application that uses :term:`url dispatch` exclusively to map URLs
 to code will usually exlusively have declarations like this within
 their ``configure.zcml`` file:
@@ -60,6 +69,9 @@ context) and a route-statement-specific (dynamically-constructed)
 (implying the default view).  This ensures that the named view will
 only be called when the route it's attached to actually matches.
 
+Traversal Only
+~~~~~~~~~~~~~~
+
 In application that uses :term:`traversal` exclusively to map URLs to
 code just won't have any ``<route>`` declarations.  Instead, its ZCML
 (or bfg_view decorators) will imply declarations that look like this:
@@ -82,16 +94,15 @@ with a :term:`view name` matching the name= argument.  The "foobar"
 view above will match the URL ``/a/b/c/foobar`` or ``/foobar``, etc,
 assuming that no view is named "a", "b", or "c" during traversal.
 
-BFG, when used in these two styles is a sort of dual-mode framework
-that can be used by people who prefer one style over the other.
-
 Hybrid Applications
 -------------------
 
-It's not a very common requirement, but it is possible to combine the
-competing concepts of traversal and url dispatch to resolve URLs to
-code within the same application by using a ``<route>`` declaration
-that contains the special token ``*traverse`` in its path.
+We've seen how the current crop of tutorials explain that you can use
+*either* traversal or url dispatch to create a :mod:`repoze.bfg`
+application.  However, it is possible to combine the competing
+concepts of traversal and url dispatch to resolve URLs to code within
+the same application by using a ``<route>`` declaration that contains
+the special token ``*traverse`` in its path.
 
 .. code-block:: xml
 
@@ -101,13 +112,14 @@ that contains the special token ``*traverse`` in its path.
      view=".views.home"
      />
 
-When the view attached to this route is invoked, BFG will attempt to
-use :term:`traversal` against the context implied by the :term:`root
-factory` of this route.  The above example isn't very useful unless
-you've defined a custom :term:`root factory` by passing it to the
-``repoze.bfg.router.make_app`` function, because the *default* root
-factory cannot be traversed (it has no useful ``__getitem__`` method).
-But let's imagine that your root factory looks like so:
+When the view attached to this route is invoked, :mod:`repoze.bfg`
+will attempt to use :term:`traversal` against the context implied by
+the :term:`root factory` of this route.  The above example isn't very
+useful unless you've defined a custom :term:`root factory` by passing
+it to the ``repoze.bfg.router.make_app`` function, because the
+*default* root factory cannot be traversed (it has no useful
+``__getitem__`` method).  But let's imagine that your root factory
+looks like so:
 
 .. code-block:: python
 
@@ -144,7 +156,7 @@ Under this circumstance, traversal is performed *after* the route
 matches.  If the root factory returns a traversable object, the
 "capture value" implied by the ``*traverse`` element in the path
 pattern will be used to traverse the graph.  For example, if the URL
-requested by a user was "http://example.com/one/two/a/b/c", and the
+requested by a user was ``http://example.com/one/two/a/b/c``, and the
 above route was matched (some other route might match before this one
 does), the traversal path used against the root would be ``a/b/c``.
 BFG will attempt to traverse a graph through the edges "a", "b", and
@@ -180,13 +192,38 @@ It's :term:`view name` will be looked for during traversal.  So if our
 URL is "http://example.com/one/two/a/another", the ``.views.another``
 view will be called.
 
-A ``<route>`` declarations *must* precede (in XML order) any
-``<view>`` declaration which names it as a ``route_name``.  If it does
-not, at application startup time a ConfigurationError will be raised.
+A ``<route>`` declaration *must* precede (in XML order) any ``<view>``
+declaration which names it as a ``route_name``.  If it does not, at
+application startup time a ConfigurationError will be raised.
+
+Route Factories
+---------------
+
+A "route" declaration can mention a "factory".  When a factory is
+attached to a route, it is used to generate a root (it's a :term:`root
+factory`) instead of the *default* root factory.
+
+.. code-block:: xml
+
+   <route
+    factory=".models.root_factory"
+    path="/abc/*traverse"
+    name="abc"
+    />
+
+In this way, each route can use a different factory, making it
+possible to traverse different graphs based on some routing parameter
+within the same application.
 
 Corner Cases
 ------------
 
+A number of corner case "gotchas" exist when using a hybrid
+application.  Let's see what they are.
+
+Registering a Default View for a Route That has a ``view`` attribute
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+
 It is an error to provide *both* a ``view`` attribute on a ``<route>``
 declaration *and* a ``<view>`` declaration that serves as a "default
 view" (a view with no ``name`` attribute or the empty ``name``
@@ -236,6 +273,9 @@ Can also be spelled like so:
 
 The two spellings are logically equivalent.  
 
+Binding Extra Views Against a  ``<route>`` Statement that Doesn't Have a ``*traverse`` Element In Its Path
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+
 Here's another corner case that just makes no sense.
 
 .. code-block:: xml
@@ -274,9 +314,12 @@ you must the special ``*traverse`` token to the route's "path"., e.g.:
      route_name="abc"
      />
 
-Note that views that *don't* mention a ``route_name`` won't ever match
-when any route matches.  For example, the "bazbuz" view below will
-never be found if the route named "abc" below is matched.
+"Global" Views Match Any Route When A More Specific View Doesn't
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+
+Note that views that *don't* mention a ``route_name`` will *also*
+match when *any* route matches.  For example, the "bazbuz" view below
+will be found if the route named "abc" below is matched.
 
 .. code-block:: xml
 
@@ -291,31 +334,45 @@ never be found if the route named "abc" below is matched.
      view=".views.bazbuz"
      />
 
-Views defined without a ``route_name`` will only be invoked when *no*
-route matches.
+To override the behavior of the "bazbuz" view when this route matches,
+use an additional view that mentions the route name explicitly.
 
-One other thing to look out for: ``<route>`` statements need to be
-ordered relative to each other; view statements don't.  <route>
-statement ordering is very important, because routes are evaluated in
-a specific order, unlike traversal, which depends on emergent behavior
-rather than an ordered list of directives.
+.. code-block:: xml
 
-Route Factories
----------------
+   <route
+     path="/abc/*traverse"
+     name="abc"
+     view=".views.abc"
+     />
 
-A "route" declaration can mention a "factory".  When a factory is
-attached to a route, it is used to generate a root (it's a :term:`root
-factory`) instead of the *default* root factory.
+   <view
+     name="bazbuz"
+     view=".views.bazbuz"
+     />
 
-.. code-block:: xml
+   <view
+     name="bazbuz"
+     route_name="abc"
+     view=".views.bazbuz2"
+     />
 
-   <route
-    factory=".models.root_factory"
-    path="/abc/*traverse"
-    name="abc"
-    />
+In the above setup, when no route matches, and traversal finds the
+view name to be "bazbuz", the ``.views.bazbuz`` view will be used.
+However, if the "abc" route matches, and traversal finds the view name
+to be "bazbuz", the ``.views.bazbuz2`` view will be used.
 
-In this way, each route can use a different factory, making it
-possible to traverse different graphs based on some routing parameter
-within the same application.
+Route Ordering
+~~~~~~~~~~~~~~
+
+One other thing to look out for: ``<route>`` statements need to be
+ordered relative to each other; view statements don't.  ``<route>``
+statement ordering is very important, because routes are evaluated in
+a specific order, unlike traversal, which depends on emergent behavior
+rather than an ordered list of directives.
+
+A ``<route>`` Statement *Must* Precede Any ``<view>>`` Statement Which Mentions It
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
 
+A ``<route>`` declaration *must* precede (in XML order) any ``<view>``
+declaration which names it as a ``route_name``.  If it does not, at
+application startup time a ConfigurationError will be raised.
diff --git a/repoze/bfg/request.py b/repoze/bfg/request.py
index e26ed1b5f..8a07c6b75 100644
--- a/repoze/bfg/request.py
+++ b/repoze/bfg/request.py
@@ -54,13 +54,13 @@ def named_request_factories(name=None):
         delete_iface = IDELETERequest
         head_iface = IHEADRequest
     else:
-        default_iface = InterfaceClass('%s_IRequest' % name)
-        get_iface = InterfaceClass('%s_IGETRequest' % name, (default_iface,))
-        post_iface = InterfaceClass('%s_IPOSTRequest' % name, (default_iface,))
-        put_iface = InterfaceClass('%s_IPUTRequest' % name, (default_iface,))
-        delete_iface = InterfaceClass('%s_IDELETERequest' % name,
-                                      (default_iface,))
-        head_iface = InterfaceClass('%s_IHEADRequest' % name, (default_iface))
+        IC = InterfaceClass
+        default_iface = IC('%s_IRequest' % name, (IRequest,))
+        get_iface = IC('%s_IGETRequest' % name, (IGETRequest,))
+        post_iface = IC('%s_IPOSTRequest' % name, (IPOSTRequest,))
+        put_iface = IC('%s_IPUTRequest' % name, (IPUTRequest,))
+        delete_iface = IC('%s_IDELETERequest' % name, (IDELETERequest,))
+        head_iface = IC('%s_IHEADRequest' % name, (IHEADRequest,))
         
     class Request(WebobRequest):
         implements(default_iface)
diff --git a/repoze/bfg/tests/test_request.py b/repoze/bfg/tests/test_request.py
index 557e1db71..6855018b8 100644
--- a/repoze/bfg/tests/test_request.py
+++ b/repoze/bfg/tests/test_request.py
@@ -11,11 +11,7 @@ class TestMakeRequestASCII(unittest.TestCase):
         self._callFUT(event)
         self.assertEqual(request.charset, None)
 
-class TestSubclassedRequest(unittest.TestCase):
-    def _getTargetClass(self):
-        from repoze.bfg.request import DEFAULT_REQUEST_FACTORIES
-        return DEFAULT_REQUEST_FACTORIES[None]['factory']
-    
+class TestRequestSubclass(object):
     def _makeOne(self, environ):
         request = self._getTargetClass()(environ)
         return request
@@ -37,6 +33,75 @@ class TestSubclassedRequest(unittest.TestCase):
         request.charset = None
         self.assertEqual(request.GET['la'], 'La Pe\xc3\xb1a')
 
+    def test_class_implements(self):
+        from repoze.bfg.interfaces import IRequest
+        klass = self._getTargetClass()
+        iface = self._getInterface()
+        self.assertTrue(iface.implementedBy(klass))
+        self.assertTrue(IRequest.implementedBy(klass))
+
+    def test_instance_provides(self):
+        from repoze.bfg.interfaces import IRequest
+        inst = self._makeOne({})
+        iface = self._getInterface()
+        self.assertTrue(iface.providedBy(inst))
+        self.assertTrue(IRequest.providedBy(inst))
+
+
+class Test_Request(TestRequestSubclass, unittest.TestCase):
+    def _getTargetClass(self):
+        from repoze.bfg.request import DEFAULT_REQUEST_FACTORIES
+        return DEFAULT_REQUEST_FACTORIES[None]['factory']
+
+    def _getInterface(self):
+        from repoze.bfg.request import DEFAULT_REQUEST_FACTORIES
+        return DEFAULT_REQUEST_FACTORIES[None]['interface']
+
+class Test_GETRequest(TestRequestSubclass, unittest.TestCase):
+    def _getTargetClass(self):
+        from repoze.bfg.request import DEFAULT_REQUEST_FACTORIES
+        return DEFAULT_REQUEST_FACTORIES['GET']['factory']
+
+    def _getInterface(self):
+        from repoze.bfg.request import DEFAULT_REQUEST_FACTORIES
+        return DEFAULT_REQUEST_FACTORIES['GET']['interface']
+
+class Test_POSTRequest(TestRequestSubclass, unittest.TestCase):
+    def _getTargetClass(self):
+        from repoze.bfg.request import DEFAULT_REQUEST_FACTORIES
+        return DEFAULT_REQUEST_FACTORIES['POST']['factory']
+
+    def _getInterface(self):
+        from repoze.bfg.request import DEFAULT_REQUEST_FACTORIES
+        return DEFAULT_REQUEST_FACTORIES['POST']['interface']
+
+class Test_PUTRequest(TestRequestSubclass, unittest.TestCase):
+    def _getTargetClass(self):
+        from repoze.bfg.request import DEFAULT_REQUEST_FACTORIES
+        return DEFAULT_REQUEST_FACTORIES['PUT']['factory']
+
+    def _getInterface(self):
+        from repoze.bfg.request import DEFAULT_REQUEST_FACTORIES
+        return DEFAULT_REQUEST_FACTORIES['PUT']['interface']
+
+class Test_DELETERequest(TestRequestSubclass, unittest.TestCase):
+    def _getTargetClass(self):
+        from repoze.bfg.request import DEFAULT_REQUEST_FACTORIES
+        return DEFAULT_REQUEST_FACTORIES['DELETE']['factory']
+
+    def _getInterface(self):
+        from repoze.bfg.request import DEFAULT_REQUEST_FACTORIES
+        return DEFAULT_REQUEST_FACTORIES['DELETE']['interface']
+
+class Test_HEADRequest(TestRequestSubclass, unittest.TestCase):
+    def _getTargetClass(self):
+        from repoze.bfg.request import DEFAULT_REQUEST_FACTORIES
+        return DEFAULT_REQUEST_FACTORIES['HEAD']['factory']
+
+    def _getInterface(self):
+        from repoze.bfg.request import DEFAULT_REQUEST_FACTORIES
+        return DEFAULT_REQUEST_FACTORIES['HEAD']['interface']
+
 class TestRequestFactory(unittest.TestCase):
     def _callFUT(self, environ):
         from repoze.bfg.request import request_factory
@@ -142,14 +207,15 @@ class TestNamedRequestFactories(unittest.TestCase):
             self.assertEqual(factories[alias], factories[iface])
             named_iface = factories[alias]['interface']
             named_factory = factories[alias]['factory']
-            self.failUnless(named_iface.implementedBy(named_factory))
             self.assertEqual(factories[alias]['interface'], iface)
             self.assertEqual(factories[iface]['interface'], iface)
             self.assertEqual(factories[alias]['factory'].charset, 'utf-8')
+            self.failUnless(named_iface.implementedBy(named_factory))
+            self.failUnless(iface.implementedBy(named_factory))
+            self.failUnless(IRequest.implementedBy(named_factory))
 
     def test_it_named(self):
         factories = self._callFUT('name')
-        from zope.interface.interface import InterfaceClass
         from repoze.bfg.interfaces import IRequest
         from repoze.bfg.interfaces import IGETRequest
         from repoze.bfg.interfaces import IPOSTRequest
@@ -171,6 +237,8 @@ class TestNamedRequestFactories(unittest.TestCase):
             named_iface = factories[alias]['interface']
             named_factory = factories[alias]['factory']
             self.failUnless(named_iface.implementedBy(named_factory))
+            self.failUnless(iface.implementedBy(named_factory))
+            self.failUnless(IRequest.implementedBy(named_factory))
 
 class TestDefaultRequestFactories(unittest.TestCase):
     def test_it(self):