> Read the latest version of this page
Edit me on GitHub

Hello Traversal World

Traversal is an alternative to URL dispatch which allows Pyramid applications to map URLs to code.

If code speaks louder than words, maybe this will help. Here is a single-file Pyramid application that uses traversal:

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18
19
20
from wsgiref.simple_server import make_server
from pyramid.config import Configurator
from pyramid.response import Response

class Resource(dict):
    pass

def get_root(request):
    return Resource({'a': Resource({'b': Resource({'c': Resource()})})})

def hello_world_of_resources(context, request):
    output = "Here's a resource and its children: %s" % context
    return Response(output)

if __name__ == '__main__':
    config = Configurator(root_factory=get_root)
    config.add_view(hello_world_of_resources, context=Resource)
    app = config.make_wsgi_app()
    server = make_server('0.0.0.0', 8080, app)
    server.serve_forever()

You may notice that this application is intentionally very similar to the “hello world” app from Creating Your First Pyramid Application.

On lines 5-6, we create a trivial resource class that’s just a dictionary subclass.

On lines 8-9, we hard-code a resource tree in our root factory function.

On lines 11-13 we define a single view callable that can display a single instance of our Resource class, passed as the context argument.

The rest of the file sets up and serves our pyramid WSGI app. Line 18 is where our view gets configured for use whenever the traversal ends with an instance of our Resource class.

Interestingly, there are no URLs explicitly configured in this application. Instead, the URL space is defined entirely by the keys in the resource tree.

Example requests

If this example is running on http://localhost:8080, and the user browses to http://localhost:8080/a/b, Pyramid will call get_root(request) to get the root resource, then traverse the tree from there by key; starting from the root, it will find the child with key "a", then its child with key "b"; then use that as the context argument for calling hello_world_of_resources.

Or, if the user browses to http://localhost:8080/ , Pyramid will stop at the root - the outermost Resource instance, in this case - and use that as the context argument to the same view.

Or, if the user browses to a key that doesn’t exist in this resource tree, like http://localhost:8080/xyz or http://localhost:8080/a/b/c/d, the traversal will end by raising a KeyError, and Pyramid will turn that into a 404 HTTP response.

A more complicated application could have many types of resources, with different view callables defined for each type, and even multiple views for each type.

See Also

Full technical details may be found in Traversal.

For more about why you might use traversal, see Much Ado About Traversal.

Table Of Contents

Previous topic

Resources

Next topic

Much Ado About Traversal