8. URL DISPATCH

If a predicate is a method you’ll need to assign it after method declaration (see PEP 232)

1

2

3

def custom_predicate(): pass

custom_predicate.__text__ = ’my custom method predicate’

If a predicate is a classmethod using @classmethod will not work, but you can still easily do it by wrapping it in classmethod call.

1 def classmethod_predicate():

2pass

3 classmethod_predicate.__text__ = ’my classmethod predicate’ 4 classmethod_predicate = classmethod(classmethod_predicate)

Same will work with staticmethod, just use staticmethod instead of classmethod.

See also pyramid.interfaces.IRoute for more API documentation about route objects.

8.12 Route Factories

Although it is not a particular common need in basic applications, a “route” configuration declaration can mention a “factory”. When that route matches a request, and a factory is attached to a route, the root factory passed at startup time to the Configurator is ignored; instead the factory associated with the route is used to generate a root object. This object will usually be used as the context resource of the view callable ultimately found via view lookup.

1

2

3

config.add_route(’abc’, ’/abc’, factory=’myproject.resources.root_factory’)

config.add_view(’myproject.views.theview’, route_name=’abc’)

The factory can either be a Python object or a dotted Python name (a string) which points to such a Python object, as it is above.

In this way, each route can use a different factory, making it possible to supply a different context resource object to the view related to each particular route.

A factory must be a callable which accepts a request and returns an arbitrary Python object. For example, the below class can be used as a factory:

92

8.13. USING PYRAMID SECURITY WITH URL DISPATCH

1

2

3

class Mine(object):

def __init__(self, request): pass

A route factory is actually conceptually identical to the root factory described at The Resource Tree.

Supplying a different resource factory for each route is useful when you’re trying to use a Pyramid authorization policy to provide declarative, “context sensitive” security checks; each resource can maintain a separate ACL, as documented in Using Pyramid Security With URL Dispatch. It is also useful when you wish to combine URL dispatch with traversal as documented within Combining Traversal and URL Dispatch.

8.13 Using Pyramid Security With URL Dispatch

Pyramid provides its own security framework which consults an authorization policy before allowing any application code to be called. This framework operates in terms of an access control list, which is stored as an __acl__ attribute of a resource object. A common thing to want to do is to attach an __acl__ to the resource object dynamically for declarative security purposes. You can use the factory argument that points at a factory which attaches a custom __acl__ to an object at its creation time.

Such a factory might look like so:

1 class Article(object):

2def __init__(self, request):

3matchdict = request.matchdict

4 article = matchdict.get(’article’, None)

5if article == ’1’:

6self.__acl__ = [ (Allow, ’editor’, ’view’) ]

If the route archives/{article} is matched, and the article number is 1, Pyramid will generate an Article context resource with an ACL on it that allows the editor principal the view permission. Obviously you can do more generic things than inspect the routes match dict to see if the article argument matches a particular string; our sample Article factory class is not very ambitious.

latex-note.png

See Security for more information about Pyramid security and ACLs.

93

8. URL DISPATCH

8.14 Route View Callable Registration and Lookup Details

When a request enters the system which matches the pattern of the route, the usual result is simple: the view callable associated with the route is invoked with the request that caused the invocation.

For most usage, you needn’t understand more than this; how it works is an implementation detail. In the interest of completeness, however, we’ll explain how it does work in the this section. You can skip it if you’re uninterested.

When a view is associated with a route configuration, Pyramid ensures that a view configuration is registered that will always be found when the route pattern is matched during a request. To do so:

•A special route-specific interface is created at startup time for each route configuration declaration.

•When an add_view statement mentions a route name attribute, a view configuration is registered at startup time. This view configuration uses a route-specific interface as a request type.

•At runtime, when a request causes any route to match, the request object is decorated with the route-specific interface.

•The fact that the request is decorated with a route-specific interface causes the view lookup machinery to always use the view callable registered using that interface by the route configuration to service requests that match the route pattern.

As we can see from the above description, technically, URL dispatch doesn’t actually map a URL pattern directly to a view callable. Instead, URL dispatch is a resource location mechanism. A Pyramid resource location subsystem (i.e., URL dispatch or traversal) finds a resource object that is the context of a request. Once the context is determined, a separate subsystem named view lookup is then responsible for finding and invoking a view callable based on information available in the context and the request. When URL dispatch is used, the resource location and view lookup subsystems provided by Pyramid are still being utilized, but in a way which does not require a developer to understand either of them in detail.

If no route is matched using URL dispatch, Pyramid falls back to traversal to handle the request.

8.15 References

A tutorial showing how URL dispatch can be used to create a Pyramid application exists in SQLAlchemy + URL Dispatch Wiki Tutorial.

94