CHAPTER

TWENTYFOUR

RESOURCES

A resource is an object that represents a “place” in a tree related to your application. Every Pyramid application has at least one resource object: the root resource. Even if you don’t define a root resource manually, a default one is created for you. The root resource is the root of a resource tree. A resource tree is a set of nested dictionary-like objects which you can use to represent your website’s structure.

In an application which uses traversal to map URLs to code, the resource tree structure is used heavily to map each URL to a view callable. When traversal is used, Pyramid will walk through the resource tree by traversing through its nested dictionary structure in order to find a context resource. Once a context resource is found, the context resource and data in the request will be used to find a view callable.

In an application which uses URL dispatch, the resource tree is only used indirectly, and is often “invisible” to the developer. In URL dispatch applications, the resource “tree” is often composed of only the root resource by itself. This root resource sometimes has security declarations attached to it, but is not required to have any. In general, the resource tree is much less important in applications that use URL dispatch than applications that use traversal.

In “Zope-like” Pyramid applications, resource objects also often store data persistently, and offer methods related to mutating that persistent data. In these kinds of applications, resources not only represent the site structure of your website, but they become the domain model of the application.

Also:

•The context and containment predicate arguments to add_view() (or a view_config() decorator) reference a resource class or resource interface.

•A root factory returns a resource.

•A resource is exposed to view code as the context of a view.

•Various helpful Pyramid API methods expect a resource as an argument (e.g. resource_url() and others).

261

24. RESOURCES

24.1 Defining a Resource Tree

When traversal is used (as opposed to a purely url dispatch based application), Pyramid expects to be able to traverse a tree composed of resources (the resource tree). Traversal begins at a root resource, and descends into the tree recursively, trying each resource’s __getitem__ method to resolve a path segment to another resource object. Pyramid imposes the following policy on resource instances in the tree:

•A container resource (a resource which contains other resources) must supply a __getitem__ method which is willing to resolve a unicode name to a sub-resource. If a sub-resource by a particular name does not exist in a container resource, __getitem__ method of the container resource must raise a KeyError. If a sub-resource by that name does exist, the container’s __getitem__ should return the sub-resource.

•Leaf resources, which do not contain other resources, must not implement a __getitem__, or if they do, their __getitem__ method must always raise a KeyError.

See Traversal for more information about how traversal works against resource instances.

Here’s a sample resource tree, represented by a variable named root:

1class Resource(dict):

2pass

3

4root = Resource({’a’:Resource({’b’:Resource({’c’:Resource()})})})

The resource tree we’ve created above is represented by a dictionary-like root object which has a single child named ’a’. ’a’ has a single child named ’b’, and ’b’ has a single child named ’c’, which has no children. It is therefore possible to access the ’c’ leaf resource like so:

1 root[’a’][’b’][’c’]

If you returned the above root object from a root factory, the path /a/b/c would find the ’c’ object in the resource tree as the result of traversal.

In this example, each of the resources in the tree is of the same class. This is not a requirement. Resource elements in the tree can be of any type. We used a single class to represent all resources in the tree for the sake of simplicity, but in a “real” app, the resources in the tree can be arbitrary.

Although the example tree above can service a traversal, the resource instances in the above example are not aware of location, so their utility in a “real” application is limited. To make best use of built-in Pyramid API facilities, your resources should be “location-aware”. The next section details how to make resources location-aware.

262

24.2. LOCATION-AWARE RESOURCES

24.2 Location-Aware Resources

In order for certain Pyramid location, security, URL-generation, and traversal APIs to work properly against the resources in a resource tree, all resources in the tree must be location -aware. This means they must have two attributes: __parent__ and __name__.

The __parent__ attribute of a location-aware resource should be a reference to the resource’s parent resource instance in the tree. The __name__ attribute should be the name with which a resource’s parent refers to the resource via __getitem__.

The __parent__ of the root resource should be None and its __name__ should be the empty string. For instance:

1 class MyRootResource(object):

2__name__ = ’’

3__parent__ = None

A resource returned from the root resource’s __getitem__ method should have a __parent__ attribute that is a reference to the root resource, and its __name__ attribute should match the name by which it is reachable via the root resource’s __getitem__. A container resource within the root resource should have a __getitem__ that returns resources with a __parent__ attribute that points at the container, and these subobjects should have a __name__ attribute that matches the name by which they are retrieved from the container via __getitem__. This pattern continues recursively “up” the tree from the root.

The __parent__ attributes of each resource form a linked list that points “downwards” toward the root. This is analogous to the .. entry in filesystem directories. If you follow the __parent__ values from any resource in the resource tree, you will eventually come to the root resource, just like if you keep executing the cd .. filesystem command, eventually you will reach the filesystem root directory.

latex-warning.png

If your root resource has a __name__ argument that is not None or the empty string, URLs returned by the resource_url() function and paths generated by the resource_path() and resource_path_tuple() APIs will be generated improperly. The value of __name__ will be prepended to every path and URL generated (as opposed to a single leading slash or empty tuple element).

263