CHAPTER

TWENTYEIGHT

COMBINING TRAVERSAL AND URL DISPATCH

When you write most Pyramid applications, you’ll be using one or the other of two available resource location subsystems: traversal or URL dispatch. However, to solve a limited set of problems, it’s useful to use both traversal and URL dispatch together within the same application. Pyramid makes this possible via hybrid applications.

latex-warning.png

Reasoning about the behavior of a “hybrid” URL dispatch + traversal application can be challenging. To successfully reason about using URL dispatch and traversal together, you need to understand URL pattern matching, root factories, and the traversal algorithm, and the potential interactions between them. Therefore, we don’t recommend creating an application that relies on hybrid behavior unless you must.

28.1 A Review of Non-Hybrid Applications

When used according to the tutorials in its documentation Pyramid is a “dual-mode” framework: the tutorials explain how to create an application in terms of using either url dispatch or traversal. This chapter details how you might combine these two dispatch mechanisms, but we’ll review how they work in isolation before trying to combine them.

305

28. COMBINING TRAVERSAL AND URL DISPATCH

28.1.1 URL Dispatch Only

An application that uses url dispatch exclusively to map URLs to code will often have statements like this within application startup configuration:

1 # config is an instance of pyramid.config.Configurator

2

3 config.add_route(’foobar’, ’{foo}/{bar}’) 4 config.add_route(’bazbuz’, ’{baz}/{buz}’)

5

6 config.add_view(’myproject.views.foobar’, route_name=’foobar’) 7 config.add_view(’myproject.views.bazbuz’, route_name=’bazbuz’)

Each route corresponds to one or more view callables. Each view callable is associated with a route by passing a route_name parameter that matches its name during a call to add_view(). When a route is matched during a request, view lookup is used to match the request to its associated view callable. The presence of calls to add_route() signify that an application is using URL dispatch.

28.1.2 Traversal Only

An application that uses only traversal will have view configuration declarations that look like this:

1# config is an instance of pyramid.config.Configurator

2

3config.add_view(’mypackage.views.foobar’, name=’foobar’)

4config.add_view(’mypackage.views.bazbuz’, name=’bazbuz’)

When the above configuration is applied to an application, the mypackage.views.foobar view callable above will be called when the URL /foobar is visited. Likewise, the view mypackage.views.bazbuz will be called when the URL /bazbuz is visited.

Typically, an application that uses traversal exclusively won’t perform any calls to pyramid.config.Configurator.add_route() in its startup code.

306