26.3. THE TRAVERSAL ALGORITHM
In general, the resource tree is traversed beginning at its root resource using a sequence of path elements described by the PATH_INFO of the current request; if there are path segments, the root resource’s __getitem__ is called with the next path segment, and it is expected to return another resource. The resulting resource’s __getitem__ is called with the very next path segment, and it is expected to return another resource. This happens ad infinitum until all path segments are exhausted.
26.3 The Traversal Algorithm
This section will attempt to explain the Pyramid traversal algorithm. We’ll provide a description of the algorithm, a diagram of how the algorithm works, and some example traversal scenarios that might help you understand how the algorithm operates against a specific resource tree.
We’ll also talk a bit about view lookup. The View Configuration chapter discusses view lookup in detail, and it is the canonical source for information about views. Technically, view lookup is a Pyramid subsystem that is separated from traversal entirely. However, we’ll describe the fundamental behavior of view lookup in the examples in the next few sections to give you an idea of how traversal and view lookup cooperate, because they are almost always used together.
26.3.1 A Description of The Traversal Algorithm
When a user requests a page from your traversal-powered application, the system uses this algorithm to find a context resource and a view name.
1.The request for the page is presented to the Pyramid router in terms of a standard WSGI request, which is represented by a WSGI environment and a WSGI start_response callable.
2.The router creates a request object based on the WSGI environment.
3.The root factory is called with the request. It returns a root resource.
4.The router uses the WSGI environment’s PATH_INFO information to determine the path segments to traverse. The leading slash is stripped off PATH_INFO, and the remaining path segments are split on the slash character to form a traversal sequence.
The traversal algorithm by default attempts to first URL-unquote and then Unicode-decode each path segment derived from PATH_INFO from its natural byte string (str type) representation. URL unquoting is performed using the Python standard library urllib.unquote function. Conversion from a URL-decoded string into Unicode is attempted using the UTF-8 encoding. If any URL-unquoted path segment in PATH_INFO is not decodeable using the UTF-8 decoding, a TypeError is raised. A segment will be fully URL-unquoted and UTF8-decoded before it is passed in to the __getitem__ of any resource during traversal.
Thus, a request with a PATH_INFO variable of /a/b/c maps to the traversal sequence [u’a’, u’b’, u’c’].
285
26.TRAVERSAL
5.Traversal begins at the root resource returned by the root factory. For the traversal sequence [u’a’, u’b’, u’c’], the root resource’s __getitem__ is called with the name ’a’. Traversal continues through the sequence. In our example, if the root resource’s __getitem__ called with the name a returns a resource (aka resource “A”), that resource’s __getitem__ is called with the name ’b’. If resource “A” returns a resource “B” when asked for ’b’, resource B’s __getitem__ is then asked for the name ’c’, and may return resource “C”.
6.Traversal ends when a) the entire path is exhausted or b) when any resouce raises a KeyError from its __getitem__ or c) when any non-final path element traversal does not have a __getitem__ method (resulting in a AttributeError) or d) when any path element is prefixed with the set of characters @@ (indicating that the characters following the @@ token should be treated as a view name).
7.When traversal ends for any of the reasons in the previous step, the last resource found during traversal is deemed to be the context. If the path has been exhausted when traversal ends, the view name is deemed to be the empty string (”). However, if the path was not exhausted before traversal terminated, the first remaining path segment is treated as the view name.
8.Any subsequent path elements after the view name is found are deemed the subpath. The subpath is always a sequence of path segments that come from PATH_INFO that are “left over” after traversal has completed.
Once the context resource, the view name, and associated attributes such as the subpath are located, the job of traversal is finished. It passes back the information it obtained to its caller, the Pyramid Router, which subsequently invokes view lookup with the context and view name information.
The traversal algorithm exposes two special cases:
•You will often end up with a view name that is the empty string as the result of a particular traversal. This indicates that the view lookup machinery should look up the default view. The default view is a view that is registered with no name or a view which is registered with a name that equals the empty string.
•If any path segment element begins with the special characters @@ (think of them as goggles), the value of that segment minus the goggle characters is considered the view name immediately and traversal stops there. This allows you to address views that may have the same names as resource names in the tree unambiguously.
Finally, traversal is responsible for locating a virtual root. A virtual root is used during “virtual hosting”; see the Virtual Hosting chapter for information. We won’t speak more about it in this chapter.
286
26.3. THE TRAVERSAL ALGORITHM
287
26. TRAVERSAL
26.3.2 Traversal Algorithm Examples
No one can be expected to understand the traversal algorithm by analogy and description alone, so let’s examine some traversal scenarios that use concrete URLs and resource tree compositions.
Let’s pretend the user asks for http://example.com/foo/bar/baz/biz/buz.txt. The request’s PATH_INFO in that case is /foo/bar/baz/biz/buz.txt. Let’s further pretend that when this request comes in that we’re traversing the following resource tree:
/--
|
|-- foo
|
----bar
Here’s what happens:
•traversal traverses the root, and attempts to find “foo”, which it finds.
•traversal traverses “foo”, and attempts to find “bar”, which it finds.
•traversal traverses “bar”, and attempts to find “baz”, which it does not find (the “bar” resource raises a KeyError when asked for “baz”).
The fact that it does not find “baz” at this point does not signify an error condition. It signifies that:
•the context is the “bar” resource (the context is the last resource found during traversal).
•the view name is baz
•the subpath is (’biz’, ’buz.txt’)
At this point, traversal has ended, and view lookup begins.
Because it’s the “context” resource, the view lookup machinery examines “bar” to find out what “type” it is. Let’s say it finds that the context is a Bar type (because “bar” happens to be an instance of the class Bar). Using the view name (baz) and the type, view lookup asks the application registry this question:
•Please find me a view callable registered using a view configuration with the name “baz” that can be used for the class Bar.
Let’s say that view lookup finds no matching view type. In this circumstance, the Pyramid router returns the result of the not found view and the request ends.
However, for this tree:
288
26.3. THE TRAVERSAL ALGORITHM
/--
|
|-- foo
|
----bar
|
----baz
|
biz
The user asks for http://example.com/foo/bar/baz/biz/buz.txt
•traversal traverses “foo”, and attempts to find “bar”, which it finds.
•traversal traverses “bar”, and attempts to find “baz”, which it finds.
•traversal traverses “baz”, and attempts to find “biz”, which it finds.
•traversal traverses “biz”, and attempts to find “buz.txt” which it does not find.
The fact that it does not find a resource related to “buz.txt” at this point does not signify an error condition. It signifies that:
•the context is the “biz” resource (the context is the last resource found during traversal).
•the view name is “buz.txt”
•the subpath is an empty sequence ( () ).
At this point, traversal has ended, and view lookup begins.
Because it’s the “context” resource, the view lookup machinery examines the “biz” resource to find out what “type” it is. Let’s say it finds that the resource is a Biz type (because “biz” is an instance of the Python class Biz). Using the view name (buz.txt) and the type, view lookup asks the application registry this question:
•Please find me a view callable registered with a view configuration with the name buz.txt that can be used for class Biz.
Let’s say that question is answered by the application registry; in such a situation, the application registry returns a view callable. The view callable is then called with the current WebOb request as the sole argument: request; it is expected to return a response.
289
26. TRAVERSAL
The Example View Callables Accept Only a Request; How Do I Access the Context Resource?
Most of the examples in this book assume that a view callable is typically passed only a request object. Sometimes your view callables need access to the context resource, especially when you use traversal. You might use a supported alternate view callable argument list in your view callables such as the (context, request) calling convention described in Alternate View Callable Argument/Calling Conventions. But you don’t need to if you don’t want to. In view callables that accept only a request, the context resource found by traversal is available as the context attribute of the request object, e.g. request.context. The view name is available as the view_name attribute of the request object, e.g. request.view_name. Other Pyramid -specific request attributes are also available as described in Special Attributes Added to the Request by Pyramid.
26.3.3 Using Resource Interfaces In View Configuration
Instead of registering your views with a context that names a Python resource class, you can optionally register a view callable with a context which is an interface. An interface can be attached arbitrarily to any resource object. View lookup treats context interfaces specially, and therefore the identity of a resource can be divorced from that of the class which implements it. As a result, associating a view with an interface can provide more flexibility for sharing a single view between two or more different implementations of a resource type. For example, if two resource objects of different Python class types share the same interface, you can use the same view configuration to specify both of them as a context.
In order to make use of interfaces in your application during view dispatch, you must create an interface and mark up your resource classes or instances with interface declarations that refer to this interface.
To attach an interface to a resource class, you define the interface and use the zope.interface.implementer() class decorator to associate the interface with the class.
1 |
from |
zope.interface |
import |
Interface |
2 |
from |
zope.interface |
import |
implementer |
3
4 class IHello(Interface):
5""" A marker interface """
6
7 @implementer(IHello)
8 class Hello(object):
9pass
To attach an interface to a resource instance, you define the interface and use the zope.interface.alsoProvides() function to associate the interface with the instance. This function mutates the instance in such a way that the interface is attached to it.
290
26.3. THE TRAVERSAL ALGORITHM
1 |
from |
zope.interface |
import |
Interface |
2 |
from |
zope.interface |
import |
alsoProvides |
3
4 class IHello(Interface):
5""" A marker interface """
6
7 class Hello(object):
8pass
9
10def make_hello():
11hello = Hello()
12alsoProvides(hello, IHello)
13return hello
Regardless of how you associate an interface, with a resource instance, or a resource class, the resulting code to associate that interface with a view callable is the same. Assuming the above code that defines an IHello interface lives in the root of your application, and its module is named “resources.py”, the interface declaration below will associate the mypackage.views.hello_world view with resources that implement, or provide, this interface.
1
2
3
4
# config is an instance of pyramid.config.Configurator
config.add_view(’mypackage.views.hello_world’, name=’hello.html’, context=’mypackage.resources.IHello’)
Any time a resource that is determined to be the context provides this interface, and a view named hello.html is looked up against it as per the URL, the mypackage.views.hello_world view callable will be invoked.
Note, in cases where a view is registered against a resource class, and a view is also registered against an interface that the resource class implements, an ambiguity arises. Views registered for the resource class take precedence over any views registered for any interface the resource class implements. Thus, if one view configuration names a context of both the class type of a resource, and another view configuration names a context of interface implemented by the resource’s class, and both view configurations are otherwise identical, the view registered for the context’s class will “win”.
For more information about defining resources with interfaces for use within view configuration, see
Resources Which Implement Interfaces.
291