- 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``.

1 files changed, 42 insertions, 3 deletions

diff --git a/repoze/bfg/interfaces.py b/repoze/bfg/interfaces.py
index 86e2206e3..7082846e4 100644
--- a/repoze/bfg/interfaces.py
+++ b/repoze/bfg/interfaces.py
@@ -234,12 +234,48 @@ class IDebugLogger(Interface):
 
 ILogger = IDebugLogger # b/c
 
+class IRoute(Interface):
+    """ Interface representing the type of object returned from
+    ``IRoutesMapper.get_route``"""
+    name = Attribute('The route name')
+    pattern = Attribute('The route pattern')
+    factory = Attribute(
+        'The :term:`root factory` used by the :mod:`repoze.bfg` router '
+        'when this route matches (or ``None``)')
+    predicates = Attribute(
+        'A sequence of :term:`route predicate` objects used to '
+        'determine if a request matches this route or not or not after '
+        'basic pattern matching has been completed.')
+    def match(path):
+        """
+        If the ``path`` passed to this function can be matched by the
+        ``pattern`` of this route, return a dictionary (the
+        'matchdict'), which will contain keys representing the dynamic
+        segment markers in the pattern mapped to values extracted from
+        the provided ``path``.
+
+        If the ``path`` passed to this function cannot be matched by
+        the ``pattern`` of this route, return ``None``.
+        """
+    def generate(kw):
+        """
+        Generate a URL based on filling in the dynamic segment markers
+        in the pattern using the ``kw`` dictionary provided.
+        """
+
 class IRoutesMapper(Interface):
     """ Interface representing a Routes ``Mapper`` object """
     def get_routes():
         """ Return a sequence of Route objects registered in the mapper."""
 
-    def connect(path, name, factory=None, predicates=()):
+    def has_routes():
+        """ Returns ``True`` if any route has been registered. """
+
+    def get_route(name):
+        """ Returns an ``IRoute`` object if a route with the name ``name``
+        was registered, otherwise return ``None``."""
+
+    def connect(name, pattern, factory=None, predicates=()):
         """ Add a new route. """
 
     def generate(name, kw):
@@ -247,8 +283,11 @@ class IRoutesMapper(Interface):
         keywords implied by kw"""
 
     def __call__(request):
-        """ Return a matchdict for the request; the ``route`` key will
-        either be a Route object or ``None`` if no route matched."""
+        """ Return a dictionary containing matching information for
+        the request; the ``route`` key of this dictionary will either
+        be a Route object or ``None`` if no route matched; the
+        ``match``key will be the matchdict or ``None`` if no route
+        matched."""
 
 class IContextURL(Interface):
     """ An adapter which deals with URLs related to a context.