- Add an API to the Configurator named get_routes_mapper.

  This returns an object implementing the ``IRoutesMapper`` interface.

CHANGES.txt

@@ -47,6 +47,9 @@ Paster Templates
 Internal
 --------
 
+- Add an API to the ``Configurator`` named ``get_routes_mapper``.
+  This returns an object implementing the ``IRoutesMapper`` interface.
+
 - The ``repoze.bfg.urldispatch.RoutesMapper`` object now has a
   ``get_route`` method which returns a single Route object or
   ``None``.

docs/glossary.rst

@@ -528,6 +528,10 @@ Glossary
      current request, the next route (in definition order) is
      attempted.
 
+   routes mapper
+     An object which compares path information from a request to an
+     ordered set of route patterns.  See :ref:`urldispatch_chapter`.
+
    predicate
      A test which returns ``True`` or ``False``.  Two different types
      of predicates exist in :mod:`repoze.bfg`: a :term:`view predicate`

repoze/bfg/configuration.py

@@ -1338,17 +1338,24 @@ def add_route(self,
                 _info=_info,
                 )
 
-        mapper = self.registry.queryUtility(IRoutesMapper)
-        if mapper is None:
-            mapper = RoutesMapper()
-            self.registry.registerUtility(mapper, IRoutesMapper)
+        mapper = self.get_routes_mapper()
+
         factory = self.maybe_dotted(factory)
         if pattern is None:
             pattern = path
         if pattern is None:
             raise ConfigurationError('"pattern" argument may not be None')
         return mapper.connect(name, pattern, factory, predicates=predicates)
 
+    def get_routes_mapper(self):
+        """ Return the :term:`routes mapper` object associated with
+        this configurator's :term:`registry`."""
+        mapper = self.registry.queryUtility(IRoutesMapper)
+        if mapper is None:
+            mapper = RoutesMapper()
+            self.registry.registerUtility(mapper, IRoutesMapper)
+        return mapper
+
     def scan(self, package=None, categories=None, _info=u''):
         """ Scan a Python package and any of its subpackages for
         objects marked with :term:`configuration decoration` such as

repoze/bfg/tests/test_configuration.py

@@ -1715,6 +1715,19 @@ def _assertRoute(self, config, name, path, num_predicates=0):
         self.assertEqual(len(routes[0].predicates), num_predicates)
         return route
 
+    def test_get_routes_mapper_not_yet_registered(self):
+        config = self._makeOne()
+        mapper = config.get_routes_mapper()
+        self.assertEqual(mapper.routelist, [])
+
+    def test_get_routes_mapper_already_registered(self):
+        from repoze.bfg.interfaces import IRoutesMapper
+        config = self._makeOne()
+        mapper = object()
+        config.registry.registerUtility(mapper, IRoutesMapper)
+        result = config.get_routes_mapper()
+        self.assertEqual(result, mapper)
+
     def test_add_route_defaults(self):
         config = self._makeOne()
         route = config.add_route('name', 'path')