Feature: BeforeTraversal

[digitalresistor]

This updates #1876 and renames it from RouteFound to BeforeTraversal.

[digitalresistor]

@stevepiercy This may require your expertise in massaging the router.rst document to make it all flow correctly. Currently 7 and 8 both have information about the BeforeTraversal event because it is emitted BEFORE the root_factory is called.

Not sure how to best word that.

[digitalresistor]

@mmerickel let me know if there is anything else that needs to be done here

@dstufft Please let me know if this still matches the spirit of your original idea.

[stevepiercy]

@bertjwregeer how about this? I'm a little uncertain about the third item.

#. If any route matches, the route mapper adds the attributes ``matchdict``
   and ``matched_route`` to the request object. The former contains a
   dictionary representing the matched dynamic elements of the request's
   ``PATH_INFO`` value, and the latter contains the
   :class:`~pyramid.interfaces.IRoute` object representing the route which
   matched.

#. A :class:`~pyramid.events.BeforeTraversal` :term:`event` is sent to any
   subscribers.

#. Continuing, if any route matches, the root object associated with the found
   route is generated. If the :term:`route configuration` which matched has an
   associated ``factory`` argument, then this factory is used to generate the
   root object; otherwise a default :term:`root factory` is used.

   However, if no route matches, and if a ``root_factory`` argument was passed
   to the :term:`Configurator` constructor, that callable is used to generate
   the root object. If the ``root_factory`` argument passed to the
   Configurator constructor was ``None``, a default root factory is used to
   generate a root object.

Additionally, I think I need to add a purple box for the new event, BeforeTraversal, and place it just to the right of the green URL dispatch box in the Request Processing diagram. Please let me know, and I will make it so.

[mmerickel]

@bertjwregeer I think it might be nice to expose the root to the BeforeTraversal event by moving the event down a couple lines. Maybe not but it's a thought. It's hard to say without a real use-case for the event.

@stevepiercy #2413 also needs an update to the diagram... you might just want to make a separate issue to update the diagram once prior to release.

[dstufft]

My original use case was to give me a hook that happened prior to anything that would touch the database. In my case it was via traversal that the DB was getting touched and I think that would mean, to satisfy the original use case, BeforeTraversal would need to happen prior to the root being created.

[mmerickel]

Yeah but a requirement like "hitting the database" is completely application dependent obviously. Is there a reason you aren't using a separate read-only db session for those requests and then just performing a rollback on any changes to the writable session? That's the approach I'd take so just curious.

[dstufft]

@mmerickel Duplication, particularly in that if I want to have the same resource work for both read only and writable sessions it means I need to duplicate my factories so that I have one for read only and one for writable or I need some sort of wrapper around them, but that just sort of feels wrong to me. Whether or not my session is writable has nothing to do with how I traverse the object graph to locate the final resource. It's an error in the separation of concerns IMO.

[digitalresistor]

@mmerickel I moved it before the root being created because the root may or may not touch the database, and IMHO creation of the root is the start of traversal.

I had moved it to after the root creation, but quickly realised that would defeat one of the goals that @dstufft had in creating the original RouteFound event. It is also the reason I added the comment above it, with the hopes that would stop someone from in the future going "Hey, I can move this down after root factory creation".

@stevepiercy That looks good actually. Could you create a PR on the feature/BeforeTraversal branch with that change? I'll merge it :-)

[mmerickel]

LGTM, I'll let it sit for a bit incase there are some more comments.