From 499b78aea5bc94626a48022afcf8cf92afb55cf8 Mon Sep 17 00:00:00 2001
From: Donald Stufft <donald@stufft.io>
Date: Sun, 23 Aug 2015 11:59:51 -0400
Subject: Add a RouteFound event which will fire after a route is found

---
 pyramid/events.py     | 19 +++++++++++++++++++
 pyramid/interfaces.py |  8 ++++++++
 pyramid/router.py     |  3 +++
 3 files changed, 30 insertions(+)

diff --git a/pyramid/events.py b/pyramid/events.py
index 97375638e..78ebf4d70 100644
--- a/pyramid/events.py
+++ b/pyramid/events.py
@@ -11,6 +11,7 @@ from pyramid.interfaces import (
     INewResponse,
     IApplicationCreated,
     IBeforeRender,
+    IRouteFound,
     )
 
 class subscriber(object):
@@ -129,6 +130,24 @@ class NewResponse(object):
         self.request = request
         self.response = response
 
+@implementer(IRouteFound)
+class RouteFound(object):
+    """
+    An instance of this class is emitted as an :term:`event` after the
+    :app:`Pyramid` :term:`router` finds a :term:`route` object but before any
+    traversal or view code is executed. The instance has an attribute,
+    ``request``, which is the request object generated by :app:`Pyramid`.
+
+    Notably, the request object will have an attributed named
+    ``matched_route``, which is the matched route that was found.
+
+    This class implements the :class:`pyramid.interfaces.IRouteFound`
+    interface.
+    """
+
+    def __init__(self, request):
+        self.request = request
+
 @implementer(IContextFound)
 class ContextFound(object):
     """ An instance of this class is emitted as an :term:`event` after
diff --git a/pyramid/interfaces.py b/pyramid/interfaces.py
index 90534593c..baf36610a 100644
--- a/pyramid/interfaces.py
+++ b/pyramid/interfaces.py
@@ -25,6 +25,14 @@ class IContextFound(Interface):
 
 IAfterTraversal = IContextFound
 
+class IRouteFound(Interface):
+    """
+    An event type that is emitted whenever :app:`Pyramid` has found a route
+    but before it calls any traversal or view code. See the documentation
+    attached to :class:`pyramid.events.Routefound` for more information.
+    """
+    request = Attribute('The request object')
+
 class INewRequest(Interface):
     """ An event type that is emitted whenever :app:`Pyramid`
     begins to process a new request.  See the documentation attached
diff --git a/pyramid/router.py b/pyramid/router.py
index 4054ef52e..c4b86f89d 100644
--- a/pyramid/router.py
+++ b/pyramid/router.py
@@ -20,6 +20,7 @@ from pyramid.events import (
     ContextFound,
     NewRequest,
     NewResponse,
+    RouteFound,
     )
 
 from pyramid.httpexceptions import HTTPNotFound
@@ -112,6 +113,8 @@ class Router(object):
                     name=route.name,
                     default=IRequest)
 
+                has_listeners and notify(RouteFound(request))
+
                 root_factory = route.factory or self.root_factory
 
         root = root_factory(request)
-- 
cgit v1.2.3