- The ``repoze.bfg.urldispatch.Route`` constructor (not an API) now

  accepts a different ordering of arguments.  Previously it was
  ``(pattern, name, factory=None, predicates=())``.  It is now
  ``(name, pattern, factory=None, predicates=())``.  This is in
  support of consistency with ``configurator.add_route``.

- The ``repoze.bfg.urldispatch.RoutesMapper.connect`` method (not an
  API) now accepts a different ordering of arguments.  Previously it
  was ``(pattern, name, factory=None, predicates=())``.  It is now
  ``(name, pattern, factory=None, predicates=())``.  This is in
  support of consistency with ``configurator.add_route``.

- The ``repoze.bfg.urldispatch.RoutesMapper`` object now has a
  ``get_route`` method which returns a single Route object or
  ``None``.

- A new interface ``repoze.bfg.interfaces.IRoute`` was added.  The
  ``repoze.bfg.urldispatch.Route`` object implements this interface.

- The canonical attribute for accessing the routing pattern from a
  route object is now ``pattern`` rather than ``path``.

- The argument to ``repoze.bfg.configuration.Configurator.add_route``
  which was previously called ``path`` is now called ``pattern`` for
  better explicability.  For backwards compatibility purposes, passing
  a keyword argument named ``path`` to ``add_route`` will still work
  indefinitely.

- The ``path`` attribute to the ZCML ``route`` directive is now named
  ``pattern`` for better explicability.  The older ``path`` attribute
  will continue to work indefinitely.

- All narrative, API, and tutorial docs which referred to a route
  pattern as a ``path`` have now been updated to refer to them as a
  ``pattern``.

- The routesalchemy template has been updated to use ``pattern`` in
  its route declarations rather than ``path``.

4 files changed, 117 insertions, 49 deletions

diff --git a/repoze/bfg/tests/test_configuration.py b/repoze/bfg/tests/test_configuration.py
index 1ee2c1018..fc01e3ed4 100644
--- a/repoze/bfg/tests/test_configuration.py
+++ b/repoze/bfg/tests/test_configuration.py
@@ -1936,6 +1936,17 @@ class ConfiguratorTests(unittest.TestCase):
         self._assertRoute(config, 'name', 'path')
         self.failUnless(hasattr(wrapper, '__call_permissive__'))
 
+    def test_add_route_no_pattern_with_path(self):
+        config = self._makeOne()
+        route = config.add_route('name', path='path')
+        self._assertRoute(config, 'name', 'path')
+        self.assertEqual(route.name, 'name')
+
+    def test_add_route_no_path_no_pattern(self):
+        from repoze.bfg.exceptions import ConfigurationError
+        config = self._makeOne()
+        self.assertRaises(ConfigurationError, config.add_route, 'name')
+
     def test__override_not_yet_registered(self):
         from repoze.bfg.interfaces import IPackageOverrides
         package = DummyPackage('package')
diff --git a/repoze/bfg/tests/test_router.py b/repoze/bfg/tests/test_router.py
index 1ce499e41..c243d739e 100644
--- a/repoze/bfg/tests/test_router.py
+++ b/repoze/bfg/tests/test_router.py
@@ -18,14 +18,14 @@ class TestRouter(unittest.TestCase):
         self.registry.registerUtility(iface, IRouteRequest, name=name)
         return iface
 
-    def _connectRoute(self, path, name, factory=None):
+    def _connectRoute(self, name, path, factory=None):
         from repoze.bfg.interfaces import IRoutesMapper
         from repoze.bfg.urldispatch import RoutesMapper
         mapper = self.registry.queryUtility(IRoutesMapper)
         if mapper is None:
             mapper = RoutesMapper()
             self.registry.registerUtility(mapper, IRoutesMapper)
-        mapper.connect(path, name, factory)
+        mapper.connect(name, path, factory)
 
     def _registerLogger(self):
         from repoze.bfg.interfaces import IDebugLogger
@@ -444,7 +444,7 @@ class TestRouter(unittest.TestCase):
         root = object()
         def factory(request):
             return root
-        self._connectRoute('archives/:action/:article', 'foo', factory)
+        self._connectRoute('foo', 'archives/:action/:article', factory)
         context = DummyContext()
         self._registerTraverserFactory(context)
         response = DummyResponse()
@@ -485,7 +485,7 @@ class TestRouter(unittest.TestCase):
         root = object()
         def factory(request):
             return root
-        self._connectRoute('archives/:action/:article', 'foo', factory)
+        self._connectRoute('foo', 'archives/:action/:article', factory)
         context = DummyContext()
         self._registerTraverserFactory(context)
         response = DummyResponse()
@@ -727,7 +727,7 @@ class TestRouter(unittest.TestCase):
         from repoze.bfg.interfaces import IViewClassifier
         from repoze.bfg.interfaces import IExceptionViewClassifier
         req_iface = self._registerRouteRequest('foo')
-        self._connectRoute('archives/:action/:article', 'foo', None)
+        self._connectRoute('foo', 'archives/:action/:article', None)
         view = DummyView(DummyResponse(), raise_exception=RuntimeError)
         self._registerView(view, '', IViewClassifier, req_iface, None)
         response = DummyResponse()
@@ -746,7 +746,7 @@ class TestRouter(unittest.TestCase):
         from repoze.bfg.interfaces import IExceptionViewClassifier
         from repoze.bfg.interfaces import IRequest
         req_iface = self._registerRouteRequest('foo')
-        self._connectRoute('archives/:action/:article', 'foo', None)
+        self._connectRoute('foo', 'archives/:action/:article', None)
         view = DummyView(DummyResponse(), raise_exception=RuntimeError)
         self._registerView(view, '', IViewClassifier, IRequest, None)
         response = DummyResponse()
@@ -764,7 +764,7 @@ class TestRouter(unittest.TestCase):
         from repoze.bfg.interfaces import IExceptionViewClassifier
         from repoze.bfg.interfaces import IRequest
         req_iface = self._registerRouteRequest('foo')
-        self._connectRoute('archives/:action/:article', 'foo', None)
+        self._connectRoute('foo', 'archives/:action/:article', None)
         view = DummyView(DummyResponse(), raise_exception=RuntimeError)
         self._registerView(view, '', IViewClassifier, req_iface, None)
         response = DummyResponse()
@@ -787,7 +787,7 @@ class TestRouter(unittest.TestCase):
         class SubException(SuperException):
             pass
         req_iface = self._registerRouteRequest('foo')
-        self._connectRoute('archives/:action/:article', 'foo', None)
+        self._connectRoute('foo', 'archives/:action/:article', None)
         view = DummyView(DummyResponse(), raise_exception=SuperException)
         self._registerView(view, '', IViewClassifier, req_iface, None)
         response = DummyResponse()
@@ -809,7 +809,7 @@ class TestRouter(unittest.TestCase):
         class SubException(SuperException):
             pass
         req_iface = self._registerRouteRequest('foo')
-        self._connectRoute('archives/:action/:article', 'foo', None)
+        self._connectRoute('foo', 'archives/:action/:article', None)
         view = DummyView(DummyResponse(), raise_exception=SubException)
         self._registerView(view, '', IViewClassifier, req_iface, None)
         response = DummyResponse()
@@ -832,7 +832,7 @@ class TestRouter(unittest.TestCase):
         class AnotherException(Exception):
             pass
         req_iface = self._registerRouteRequest('foo')
-        self._connectRoute('archives/:action/:article', 'foo', None)
+        self._connectRoute('foo', 'archives/:action/:article', None)
         view = DummyView(DummyResponse(), raise_exception=MyException)
         self._registerView(view, '', IViewClassifier, req_iface, None)
         response = DummyResponse()
@@ -850,7 +850,7 @@ class TestRouter(unittest.TestCase):
         from repoze.bfg.interfaces import IExceptionViewClassifier
         from repoze.bfg.interfaces import IRequest
         req_iface = self._registerRouteRequest('foo')
-        self._connectRoute('archives/:action/:article', 'foo', None)
+        self._connectRoute('foo', 'archives/:action/:article', None)
         view = DummyView(DummyResponse(), raise_exception=RuntimeError)
         self._registerView(view, '', IViewClassifier, req_iface, None)
         response = DummyResponse()
@@ -874,7 +874,7 @@ class TestRouter(unittest.TestCase):
         from repoze.bfg.interfaces import IExceptionViewClassifier
         req_iface = self._registerRouteRequest('foo')
         another_req_iface = self._registerRouteRequest('bar')
-        self._connectRoute('archives/:action/:article', 'foo', None)
+        self._connectRoute('foo', 'archives/:action/:article', None)
         view = DummyView(DummyResponse(), raise_exception=RuntimeError)
         self._registerView(view, '', IViewClassifier, req_iface, None)
         response = DummyResponse()
diff --git a/repoze/bfg/tests/test_urldispatch.py b/repoze/bfg/tests/test_urldispatch.py
index f51bf7e87..bf43750ea 100644
--- a/repoze/bfg/tests/test_urldispatch.py
+++ b/repoze/bfg/tests/test_urldispatch.py
@@ -9,9 +9,15 @@ class TestRoute(unittest.TestCase):
     def _makeOne(self, *arg):
         return self._getTargetClass()(*arg)
 
+    def test_provides_IRoute(self):
+        from repoze.bfg.interfaces import IRoute
+        from zope.interface.verify import verifyObject
+        verifyObject(IRoute, self._makeOne('name', 'pattern'))
+
     def test_ctor(self):
         import types
-        route = self._makeOne(':path', 'name', 'factory')
+        route = self._makeOne('name', ':path', 'factory')
+        self.assertEqual(route.pattern, ':path')
         self.assertEqual(route.path, ':path')
         self.assertEqual(route.name, 'name')
         self.assertEqual(route.factory, 'factory')
@@ -20,19 +26,20 @@ class TestRoute(unittest.TestCase):
 
     def test_ctor_defaults(self):
         import types
-        route = self._makeOne(':path')
+        route = self._makeOne('name', ':path')
+        self.assertEqual(route.pattern, ':path')
         self.assertEqual(route.path, ':path')
-        self.assertEqual(route.name, None)
+        self.assertEqual(route.name, 'name')
         self.assertEqual(route.factory, None)
         self.failUnless(route.generate.__class__ is types.FunctionType)
         self.failUnless(route.match.__class__ is types.FunctionType)
 
     def test_match(self):
-        route = self._makeOne(':path')
+        route = self._makeOne('name', ':path')
         self.assertEqual(route.match('/whatever'), {'path':'whatever'})
 
     def test_generate(self):
-        route = self._makeOne(':path')
+        route = self._makeOne('name', ':path')
         self.assertEqual(route.generate({'path':'abc'}), '/abc')
 
 class RoutesMapperTests(unittest.TestCase):
@@ -60,6 +67,11 @@ class RoutesMapperTests(unittest.TestCase):
         klass = self._getTargetClass()
         return klass()
 
+    def test_provides_IRoutesMapper(self):
+        from repoze.bfg.interfaces import IRoutesMapper
+        from zope.interface.verify import verifyObject
+        verifyObject(IRoutesMapper, self._makeOne())
+
     def test_no_route_matches(self):
         mapper = self._makeOne()
         request = self._getRequest(PATH_INFO='/')
@@ -69,18 +81,18 @@ class RoutesMapperTests(unittest.TestCase):
 
     def test_connect_name_exists_removes_old(self):
         mapper = self._makeOne()
-        mapper.connect('archives/:action/:article', 'foo')
-        mapper.connect('archives/:action/:article2', 'foo')
+        mapper.connect('foo', 'archives/:action/:article')
+        mapper.connect('foo', 'archives/:action/:article2')
         self.assertEqual(len(mapper.routelist), 1)
         self.assertEqual(len(mapper.routes), 1)
-        self.assertEqual(mapper.routes['foo'].path,
+        self.assertEqual(mapper.routes['foo'].pattern,
                          'archives/:action/:article2')
-        self.assertEqual(mapper.routelist[0].path,
+        self.assertEqual(mapper.routelist[0].pattern,
                          'archives/:action/:article2')
 
     def test___call__route_matches(self):
         mapper = self._makeOne()
-        mapper.connect('archives/:action/:article', 'foo')
+        mapper.connect('foo', 'archives/:action/:article')
         request = self._getRequest(PATH_INFO='/archives/action1/article1')
         result = mapper(request)
         self.assertEqual(result['route'], mapper.routes['foo'])
@@ -89,7 +101,7 @@ class RoutesMapperTests(unittest.TestCase):
 
     def test___call__route_matches_with_predicates(self):
         mapper = self._makeOne()
-        mapper.connect('archives/:action/:article', 'foo',
+        mapper.connect('foo', 'archives/:action/:article',
                        predicates=[lambda *arg: True])
         request = self._getRequest(PATH_INFO='/archives/action1/article1')
         result = mapper(request)
@@ -99,9 +111,9 @@ class RoutesMapperTests(unittest.TestCase):
 
     def test___call__route_fails_to_match_with_predicates(self):
         mapper = self._makeOne()
-        mapper.connect('archives/:action/article1', 'foo',
+        mapper.connect('foo', 'archives/:action/article1',
                        predicates=[lambda *arg: True, lambda *arg: False])
-        mapper.connect('archives/:action/:article', 'bar')
+        mapper.connect('bar', 'archives/:action/:article')
         request = self._getRequest(PATH_INFO='/archives/action1/article1')
         result = mapper(request)
         self.assertEqual(result['route'], mapper.routes['bar'])
@@ -114,7 +126,7 @@ class RoutesMapperTests(unittest.TestCase):
             self.assertEqual(info['match'], {'action':u'action1'})
             self.assertEqual(info['route'], mapper.routes['foo'])
             return True
-        mapper.connect('archives/:action/article1', 'foo', predicates=[pred])
+        mapper.connect('foo', 'archives/:action/article1', predicates=[pred])
         request = self._getRequest(PATH_INFO='/archives/action1/article1')
         mapper(request)
 
@@ -122,9 +134,9 @@ class RoutesMapperTests(unittest.TestCase):
         # "unordered" as reported in IRC by author of
         # http://labs.creativecommons.org/2010/01/13/cc-engine-and-web-non-frameworks/
         mapper = self._makeOne()
-        mapper.connect('licenses/:license_code/:license_version/rdf', 'rdf')
-        mapper.connect('licenses/:license_code/:license_version/:jurisdiction',
-                       'juri')
+        mapper.connect('rdf', 'licenses/:license_code/:license_version/rdf')
+        mapper.connect('juri',
+                       'licenses/:license_code/:license_version/:jurisdiction')
 
         request = self._getRequest(PATH_INFO='/licenses/1/v2/rdf')
         result = mapper(request)
@@ -141,7 +153,7 @@ class RoutesMapperTests(unittest.TestCase):
 
     def test___call__root_route_matches(self):
         mapper = self._makeOne()
-        mapper.connect('', 'root')
+        mapper.connect('root', '')
         request = self._getRequest(PATH_INFO='/')
         result = mapper(request)
         self.assertEqual(result['route'], mapper.routes['root'])
@@ -149,7 +161,7 @@ class RoutesMapperTests(unittest.TestCase):
 
     def test___call__root_route_matches2(self):
         mapper = self._makeOne()
-        mapper.connect('/', 'root')
+        mapper.connect('root', '/')
         request = self._getRequest(PATH_INFO='/')
         result = mapper(request)
         self.assertEqual(result['route'], mapper.routes['root'])
@@ -157,7 +169,7 @@ class RoutesMapperTests(unittest.TestCase):
 
     def test___call__root_route_when_path_info_empty(self):
         mapper = self._makeOne()
-        mapper.connect('/', 'root')
+        mapper.connect('root', '/')
         request = self._getRequest(PATH_INFO='')
         result = mapper(request)
         self.assertEqual(result['route'], mapper.routes['root'])
@@ -165,7 +177,7 @@ class RoutesMapperTests(unittest.TestCase):
 
     def test___call__no_path_info(self):
         mapper = self._makeOne()
-        mapper.connect('/', 'root')
+        mapper.connect('root', '/')
         request = self._getRequest()
         result = mapper(request)
         self.assertEqual(result['route'], mapper.routes['root'])
@@ -186,6 +198,17 @@ class RoutesMapperTests(unittest.TestCase):
         self.assertEqual(len(routes), 1)
         self.assertEqual(routes[0].__class__, Route)
 
+    def test_get_route_matches(self):
+        mapper = self._makeOne()
+        mapper.connect('whatever', 'archives/:action/:article')
+        result = mapper.get_route('whatever')
+        self.assertEqual(result.pattern, 'archives/:action/:article')
+
+    def test_get_route_misses(self):
+        mapper = self._makeOne()
+        result = mapper.get_route('whatever')
+        self.assertEqual(result, None)
+
     def test_generate(self):
         mapper = self._makeOne()
         def generator(kw):
@@ -195,9 +218,9 @@ class RoutesMapperTests(unittest.TestCase):
         self.assertEqual(mapper.generate('abc', {}), 123)
 
 class TestCompileRoute(unittest.TestCase):
-    def _callFUT(self, path):
+    def _callFUT(self, pattern):
         from repoze.bfg.urldispatch import _compile_route
-        return _compile_route(path)
+        return _compile_route(pattern)
 
     def test_no_star(self):
         matcher, generator = self._callFUT('/foo/:baz/biz/:buz/bar')
diff --git a/repoze/bfg/tests/test_zcml.py b/repoze/bfg/tests/test_zcml.py
index a01b52840..4cd7f88d3 100644
--- a/repoze/bfg/tests/test_zcml.py
+++ b/repoze/bfg/tests/test_zcml.py
@@ -514,7 +514,7 @@ class TestRouteDirective(unittest.TestCase):
         from repoze.bfg.zcml import route
         return route(*arg, **kw)
 
-    def _assertRoute(self, name, path, num_predicates=0):
+    def _assertRoute(self, name, pattern, num_predicates=0):
         from repoze.bfg.threadlocal import get_current_registry
         from repoze.bfg.interfaces import IRoutesMapper
         reg = get_current_registry()
@@ -523,7 +523,7 @@ class TestRouteDirective(unittest.TestCase):
         route = routes[0]
         self.assertEqual(len(routes), 1)
         self.assertEqual(route.name, name)
-        self.assertEqual(route.path, path)
+        self.assertEqual(route.pattern, pattern)
         self.assertEqual(len(routes[0].predicates), num_predicates)
         return route
 
@@ -535,7 +535,7 @@ class TestRouteDirective(unittest.TestCase):
         from repoze.bfg.interfaces import IRouteRequest
         context = DummyContext()
         view = lambda *arg: 'OK'
-        self._callFUT(context, 'name', 'path', view=view)
+        self._callFUT(context, 'name', 'pattern', view=view)
         actions = context.actions
         self.assertEqual(len(actions), 2)
 
@@ -544,7 +544,7 @@ class TestRouteDirective(unittest.TestCase):
         route_discriminator = route_action['discriminator']
         self.assertEqual(route_discriminator,
                          ('route', 'name', False, None, None, None, None,None))
-        self._assertRoute('name', 'path')
+        self._assertRoute('name', 'pattern')
 
         view_action = actions[1]
         reg = get_current_registry()
@@ -563,7 +563,8 @@ class TestRouteDirective(unittest.TestCase):
         from repoze.bfg.interfaces import IRouteRequest
         context = DummyContext()
         view = lambda *arg: 'OK'
-        self._callFUT(context, 'name', 'path', view=view, view_context=IDummy)
+        self._callFUT(context, 'name', 'pattern', view=view,
+                      view_context=IDummy)
         actions = context.actions
         self.assertEqual(len(actions), 2)
 
@@ -572,7 +573,7 @@ class TestRouteDirective(unittest.TestCase):
         route_discriminator = route_action['discriminator']
         self.assertEqual(route_discriminator,
                          ('route', 'name', False, None, None, None, None,None))
-        self._assertRoute('name', 'path')
+        self._assertRoute('name', 'pattern')
 
         view_action = actions[1]
         reg = get_current_registry()
@@ -593,8 +594,8 @@ class TestRouteDirective(unittest.TestCase):
         view = lambda *arg: 'OK'
         class Foo:
             pass
-        self._callFUT(context, 'name', 'path', view=view, view_context=IDummy,
-                      view_for=Foo)
+        self._callFUT(context, 'name', 'pattern', view=view,
+                      view_context=IDummy, view_for=Foo)
         actions = context.actions
         self.assertEqual(len(actions), 2)
 
@@ -603,7 +604,7 @@ class TestRouteDirective(unittest.TestCase):
         route_discriminator = route_action['discriminator']
         self.assertEqual(route_discriminator,
                          ('route', 'name', False, None, None, None, None,None))
-        self._assertRoute('name', 'path')
+        self._assertRoute('name', 'pattern')
 
         view_action = actions[1]
         reg = get_current_registry()
@@ -630,7 +631,7 @@ class TestRouteDirective(unittest.TestCase):
 
         context = DummyContext()
         view = lambda *arg: 'OK'
-        self._callFUT(context, 'name', 'path', view=view,
+        self._callFUT(context, 'name', 'pattern', view=view,
                       renderer='fixtureapp/templates/foo.pt')
         actions = context.actions
         self.assertEqual(len(actions), 2)
@@ -640,7 +641,7 @@ class TestRouteDirective(unittest.TestCase):
         route_discriminator = route_action['discriminator']
         self.assertEqual(route_discriminator,
                          ('route', 'name', False, None, None, None, None,None))
-        self._assertRoute('name', 'path')
+        self._assertRoute('name', 'pattern')
 
         view_action = actions[1]
         request_type = reg.getUtility(IRouteRequest, 'name')
@@ -660,7 +661,8 @@ class TestRouteDirective(unittest.TestCase):
         preds = tuple(sorted([pred1, pred2]))
 
         context = DummyContext()
-        self._callFUT(context, 'name', 'path', custom_predicates=(pred1, pred2))
+        self._callFUT(context, 'name', 'pattern',
+                      custom_predicates=(pred1, pred2))
         actions = context.actions
         self.assertEqual(len(actions), 1)
 
@@ -670,7 +672,39 @@ class TestRouteDirective(unittest.TestCase):
         self.assertEqual(
             route_discriminator,
             ('route', 'name', False, None, None, None, None,None) + preds)
-        self._assertRoute('name', 'path', 2)
+        self._assertRoute('name', 'pattern', 2)
+
+    def test_with_path_argument_no_pattern(self):
+        context = DummyContext()
+        self._callFUT(context, 'name', path='pattern')
+        actions = context.actions
+        self.assertEqual(len(actions), 1)
+
+        route_action = actions[0]
+        route_action['callable']()
+        route_discriminator = route_action['discriminator']
+        self.assertEqual(route_discriminator,
+                         ('route', 'name', False, None, None, None, None,None))
+        self._assertRoute('name', 'pattern')
+
+    def test_with_path_argument_and_pattern(self):
+        context = DummyContext()
+        self._callFUT(context, 'name', pattern='pattern', path='path')
+        actions = context.actions
+        self.assertEqual(len(actions), 1)
+
+        route_action = actions[0]
+        route_action['callable']()
+        route_discriminator = route_action['discriminator']
+        self.assertEqual(route_discriminator,
+                         ('route', 'name', False, None, None, None, None,None))
+        self._assertRoute('name', 'pattern')
+        
+
+    def test_with_neither_path_nor_pattern(self):
+        from repoze.bfg.exceptions import ConfigurationError
+        context = DummyContext()
+        self.assertRaises(ConfigurationError, self._callFUT, context, 'name')
 
 class TestStaticDirective(unittest.TestCase):
     def setUp(self):
@@ -706,7 +740,7 @@ class TestStaticDirective(unittest.TestCase):
         mapper = reg.getUtility(IRoutesMapper)
         routes = mapper.get_routes()
         self.assertEqual(len(routes), 1)
-        self.assertEqual(routes[0].path, 'name/*subpath')
+        self.assertEqual(routes[0].pattern, 'name/*subpath')
         self.assertEqual(routes[0].name, 'name/')
 
         view_action = actions[1]