Skip to content
This repository
tag: 1.2a2
Fetching contributors…

Octocat-spinner-32-eaf2f5

Cannot retrieve contributors at this time

file 694 lines (516 sloc) 26.69 kb

Resources

A :term:`resource` is an object that represents a "place" in a tree related to your application. Every :app:`Pyramid` application has at least one resource object: the :term:`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 :term:`resource tree`. A resource tree is a set of nested dictionary-like objects which you can use to represent your website's structure.

System Message: ERROR/3 (<string>, line 6); backlink

Unknown interpreted text role "term".

System Message: ERROR/3 (<string>, line 6); backlink

Unknown interpreted text role "app".

System Message: ERROR/3 (<string>, line 6); backlink

Unknown interpreted text role "term".

System Message: ERROR/3 (<string>, line 6); backlink

Unknown interpreted text role "term".

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

System Message: ERROR/3 (<string>, line 14); backlink

Unknown interpreted text role "term".

System Message: ERROR/3 (<string>, line 14); backlink

Unknown interpreted text role "term".

System Message: ERROR/3 (<string>, line 14); backlink

Unknown interpreted text role "term".

System Message: ERROR/3 (<string>, line 14); backlink

Unknown interpreted text role "app".

System Message: ERROR/3 (<string>, line 14); backlink

Unknown interpreted text role "term".

System Message: ERROR/3 (<string>, line 14); backlink

Unknown interpreted text role "term".

In an application which uses :term:`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.

System Message: ERROR/3 (<string>, line 22); backlink

Unknown interpreted text role "term".

In "Zope-like" :app:`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 :term:`domain model` of the application.

System Message: ERROR/3 (<string>, line 30); backlink

Unknown interpreted text role "app".

System Message: ERROR/3 (<string>, line 30); backlink

Unknown interpreted text role "term".

Also:

System Message: ERROR/3 (<string>, line 51)

Unknown directive type "index".

.. index::
   single: resource tree
   single: traversal tree
   single: object tree
   single: container resources
   single: leaf resources

Defining a Resource Tree

When :term:`traversal` is used (as opposed to a purely :term:`url dispatch` based application), :app:`Pyramid` expects to be able to traverse a tree composed of resources (the :term:`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. :app:`Pyramid` imposes the following policy on resource instances in the tree:

System Message: ERROR/3 (<string>, line 61); backlink

Unknown interpreted text role "term".

System Message: ERROR/3 (<string>, line 61); backlink

Unknown interpreted text role "term".

System Message: ERROR/3 (<string>, line 61); backlink

Unknown interpreted text role "app".

System Message: ERROR/3 (<string>, line 61); backlink

Unknown interpreted text role "term".

System Message: ERROR/3 (<string>, line 61); backlink

Unknown interpreted text role "app".
  • 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 :exc:`KeyError`. If a sub-resource by that name does exist, the container's __getitem__ should return the sub-resource.

    System Message: ERROR/3 (<string>, line 69); backlink

    Unknown interpreted text role "exc".

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

    System Message: ERROR/3 (<string>, line 76); backlink

    Unknown interpreted text role "exc".

See :ref:`traversal_chapter` for more information about how traversal works against resource instances.

System Message: ERROR/3 (<string>, line 80); backlink

Unknown interpreted text role "ref".

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

System Message: ERROR/3 (<string>, line 85)

Error in "code-block" directive: unknown option: "linenos".

.. code-block:: python
   :linenos:

    class Resource(dict):
        pass

    root = 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:

System Message: ERROR/3 (<string>, line 98)

Error in "code-block" directive: unknown option: "linenos".

.. code-block:: python
   :linenos:

   root['a']['b']['c']

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

System Message: ERROR/3 (<string>, line 103); backlink

Unknown interpreted text role "term".

System Message: ERROR/3 (<string>, line 103); backlink

Unknown interpreted text role "term".

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 :term:`location`, so their utility in a "real" application is limited. To make best use of built-in :app:`Pyramid` API facilities, your resources should be "location-aware". The next section details how to make resources location-aware.

System Message: ERROR/3 (<string>, line 112); backlink

Unknown interpreted text role "term".

System Message: ERROR/3 (<string>, line 112); backlink

Unknown interpreted text role "app".

System Message: ERROR/3 (<string>, line 118)

Unknown directive type "index".

.. index::
   pair: location-aware; resource

Location-Aware Resources

In order for certain :app:`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 :term:`location` -aware. This means they must have two attributes: __parent__ and __name__.

System Message: ERROR/3 (<string>, line 126); backlink

Unknown interpreted text role "app".

System Message: ERROR/3 (<string>, line 126); backlink

Unknown interpreted text role "term".

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:

System Message: ERROR/3 (<string>, line 139)

Error in "code-block" directive: unknown option: "linenos".

.. code-block:: python
   :linenos:

   class MyRootResource(object):
       __name__ = ''
       __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.

Warning

If your root resource has a __name__ argument that is not None or the empty string, URLs returned by the :func:`~pyramid.request.Request.resource_url` function and paths generated by the :func:`~pyramid.traversal.resource_path` and :func:`~pyramid.traversal.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).

System Message: ERROR/3 (<string>, line 163); backlink

Unknown interpreted text role "func".

System Message: ERROR/3 (<string>, line 163); backlink

Unknown interpreted text role "func".

System Message: ERROR/3 (<string>, line 163); backlink

Unknown interpreted text role "func".

Using :mod:`pyramid_traversalwrapper`

System Message: ERROR/3 (<string>, line 172); backlink

Unknown interpreted text role "mod".

If you'd rather not manage the __name__ and __parent__ attributes of your resources "by hand", an add-on package named :mod:`pyramid_traversalwrapper` can help.

System Message: ERROR/3 (<string>, line 174); backlink

Unknown interpreted text role "mod".

In order to use this helper feature, you must first install the :mod:`pyramid_traversalwrapper` package (available via PyPI), then register its ModelGraphTraverser as the traversal policy, rather than the default :app:`Pyramid` traverser. The package contains instructions for doing so.

System Message: ERROR/3 (<string>, line 178); backlink

Unknown interpreted text role "mod".

System Message: ERROR/3 (<string>, line 178); backlink

Unknown interpreted text role "app".

Once :app:`Pyramid` is configured with this feature, you will no longer need to manage the __parent__ and __name__ attributes on resource objects "by hand". Instead, as necessary, during traversal :app:`Pyramid` will wrap each resource (even the root resource) in a LocationProxy which will dynamically assign a __name__ and a __parent__ to the traversed resource (based on the last traversed resource and the name supplied to __getitem__). The root resource will have a __name__ attribute of None and a __parent__ attribute of None.

System Message: ERROR/3 (<string>, line 184); backlink

Unknown interpreted text role "app".

System Message: ERROR/3 (<string>, line 184); backlink

Unknown interpreted text role "app".

Applications which use tree-walking :app:`Pyramid` APIs require location-aware resources. These APIs include (but are not limited to) :meth:`~pyramid.request.Request.resource_url`, :func:`~pyramid.traversal.find_resource`, :func:`~pyramid.traversal.find_root`, :func:`~pyramid.traversal.find_interface`, :func:`~pyramid.traversal.resource_path`, :func:`~pyramid.traversal.resource_path_tuple`, or :func:`~pyramid.traversal.traverse`, :func:`~pyramid.traversal.virtual_root`, and (usually) :func:`~pyramid.security.has_permission` and :func:`~pyramid.security.principals_allowed_by_permission`.

System Message: ERROR/3 (<string>, line 193); backlink

Unknown interpreted text role "app".

System Message: ERROR/3 (<string>, line 193); backlink

Unknown interpreted text role "meth".

System Message: ERROR/3 (<string>, line 193); backlink

Unknown interpreted text role "func".

System Message: ERROR/3 (<string>, line 193); backlink

Unknown interpreted text role "func".

System Message: ERROR/3 (<string>, line 193); backlink

Unknown interpreted text role "func".

System Message: ERROR/3 (<string>, line 193); backlink

Unknown interpreted text role "func".

System Message: ERROR/3 (<string>, line 193); backlink

Unknown interpreted text role "func".

System Message: ERROR/3 (<string>, line 193); backlink

Unknown interpreted text role "func".

System Message: ERROR/3 (<string>, line 193); backlink

Unknown interpreted text role "func".

System Message: ERROR/3 (<string>, line 193); backlink

Unknown interpreted text role "func".

System Message: ERROR/3 (<string>, line 193); backlink

Unknown interpreted text role "func".

In general, since so much :app:`Pyramid` infrastructure depends on location-aware resources, it's a good idea to make each resource in your tree location-aware.

System Message: ERROR/3 (<string>, line 205); backlink

Unknown interpreted text role "app".

System Message: ERROR/3 (<string>, line 209)

Unknown directive type "index".

.. index::
   single: resource_url
   pair: generating; resource url

Generating The URL Of A Resource

If your resources are :term:`location` aware, you can use the :meth:`pyramid.request.Request.resource_url` API to generate a URL for the resource. This URL will use the resource's position in the parent tree to create a resource path, and it will prefix the path with the current application URL to form a fully-qualified URL with the scheme, host, port, and path. You can also pass extra arguments to :meth:`~pyramid.request.Request.resource_url` to influence the generated URL.

System Message: ERROR/3 (<string>, line 218); backlink

Unknown interpreted text role "term".

System Message: ERROR/3 (<string>, line 218); backlink

Unknown interpreted text role "meth".

System Message: ERROR/3 (<string>, line 218); backlink

Unknown interpreted text role "meth".

The simplest call to :meth:`~pyramid.request.Request.resource_url` looks like this:

System Message: ERROR/3 (<string>, line 226); backlink

Unknown interpreted text role "meth".

System Message: ERROR/3 (<string>, line 229)

Error in "code-block" directive: unknown option: "linenos".

.. code-block:: python
   :linenos:

   url = request.resource_url(resource, request)

The request in the above example is an instance of a :app:`Pyramid` :term:`request` object.

System Message: ERROR/3 (<string>, line 234); backlink

Unknown interpreted text role "app".

System Message: ERROR/3 (<string>, line 234); backlink

Unknown interpreted text role "term".

If the resource referred to as resource in the above example was the root resource, and the host that was used to contact the server was example.com, the URL generated would be http://example.com/. However, if the resource was a child of the root resource named a, the generated URL would be http://example.com/a/.

A slash is appended to all resource URLs when :meth:`~pyramid.request.Request.resource_url` is used to generate them in this simple manner, because resources are "places" in the hierarchy, and URLs are meant to be clicked on to be visited. Relative URLs that you include on HTML pages rendered as the result of the default view of a resource are more apt to be relative to these resources than relative to their parent.

System Message: ERROR/3 (<string>, line 243); backlink

Unknown interpreted text role "meth".

You can also pass extra elements to :meth:`~pyramid.request.Request.resource_url`:

System Message: ERROR/3 (<string>, line 250); backlink

Unknown interpreted text role "meth".

System Message: ERROR/3 (<string>, line 253)

Error in "code-block" directive: unknown option: "linenos".

.. code-block:: python
   :linenos:

   url = request.resource_url(resource, 'foo', 'bar')

If the resource referred to as resource in the above example was the root resource, and the host that was used to contact the server was example.com, the URL generated would be http://example.com/foo/bar. Any number of extra elements can be passed to :meth:`~pyramid.request.Request.resource_url` as extra positional arguments. When extra elements are passed, they are appended to the resource's URL. A slash is not appended to the final segment when elements are passed.

System Message: ERROR/3 (<string>, line 258); backlink

Unknown interpreted text role "meth".

You can also pass a query string:

System Message: ERROR/3 (<string>, line 268)

Error in "code-block" directive: unknown option: "linenos".

.. code-block:: python
   :linenos:

   url = request.resource_url(resource, query={'a':'1'})

If the resource referred to as resource in the above example was the root resource, and the host that was used to contact the server was example.com, the URL generated would be http://example.com/?a=1.

When a :term:`virtual root` is active, the URL generated by :meth:`~pyramid.request.Request.resource_url` for a resource may be "shorter" than its physical tree path. See :ref:`virtual_root_support` for more information about virtually rooting a resource.

System Message: ERROR/3 (<string>, line 277); backlink

Unknown interpreted text role "term".

System Message: ERROR/3 (<string>, line 277); backlink

Unknown interpreted text role "meth".

System Message: ERROR/3 (<string>, line 277); backlink

Unknown interpreted text role "ref".

For more information about generating resource URLs, see the documentation for :meth:`pyramid.request.Request.resource_url`.

System Message: ERROR/3 (<string>, line 282); backlink

Unknown interpreted text role "meth".

System Message: ERROR/3 (<string>, line 285)

Unknown directive type "index".

.. index::
   pair: resource URL generation; overriding

Overriding Resource URL Generation

If a resource object implements a __resource_url__ method, this method will be called when :meth:`~pyramid.request.Request.resource_url` is called to generate a URL for the resource, overriding the default URL returned for the resource by :meth:`~pyramid.request.Request.resource_url`.

System Message: ERROR/3 (<string>, line 293); backlink

Unknown interpreted text role "meth".

System Message: ERROR/3 (<string>, line 293); backlink

Unknown interpreted text role "meth".

The __resource_url__ hook is passed two arguments: request and info. request is the :term:`request` object passed to :meth:`~pyramid.request.Request.resource_url`. info is a dictionary with two keys:

System Message: ERROR/3 (<string>, line 298); backlink

Unknown interpreted text role "term".

System Message: ERROR/3 (<string>, line 298); backlink

Unknown interpreted text role "meth".
physical_path
The "physical path" computed for the resource, as defined by pyramid.traversal.resource_path(resource).
virtual_path

The "virtual path" computed for the resource, as defined by :ref:`virtual_root_support`. This will be identical to the physical path if virtual rooting is not enabled.

System Message: ERROR/3 (<string>, line 308); backlink

Unknown interpreted text role "ref".

The __resource_url__ method of a resource should return a string representing a URL. If it cannot override the default, it should return None. If it returns None, the default URL will be returned.

Here's an example __resource_url__ method.

System Message: ERROR/3 (<string>, line 318)

Error in "code-block" directive: unknown option: "linenos".

.. code-block:: python
   :linenos:

   class Resource(object):
       def __resource_url__(self, request, info):
           return request.application_url + info['virtual_path']

The above example actually just generates and returns the default URL, which would have been what was returned anyway, but your code can perform arbitrary logic as necessary. For example, your code may wish to override the hostname or port number of the generated URL.

Note that the URL generated by __resource_url__ should be fully qualified, should end in a slash, and should not contain any query string or anchor elements (only path elements) to work best with :meth:`~pyramid.request.Request.resource_url`.

System Message: ERROR/3 (<string>, line 330); backlink

Unknown interpreted text role "meth".

System Message: ERROR/3 (<string>, line 335)

Unknown directive type "index".

.. index::
   single: resource path generation

Generating the Path To a Resource

:func:`pyramid.traversal.resource_path` returns a string object representing the absolute physical path of the resource object based on its position in the resource tree. Each segment of the path is separated with a slash character.

System Message: ERROR/3 (<string>, line 341); backlink

Unknown interpreted text role "func".

System Message: ERROR/3 (<string>, line 346)

Error in "code-block" directive: unknown option: "linenos".

.. code-block:: python
   :linenos:

   from pyramid.traversal import resource_path
   url = resource_path(resource)

If resource in the example above was accessible in the tree as root['a']['b'], the above example would generate the string /a/b.

Any positional arguments passed in to :func:`~pyramid.traversal.resource_path` will be appended as path segments to the end of the resource path.

System Message: ERROR/3 (<string>, line 355); backlink

Unknown interpreted text role "func".

System Message: ERROR/3 (<string>, line 358)

Error in "code-block" directive: unknown option: "linenos".

.. code-block:: python
   :linenos:

   from pyramid.traversal import resource_path
   url = resource_path(resource, 'foo', 'bar')

If resource in the example above was accessible in the tree as root['a']['b'], the above example would generate the string /a/b/foo/bar.

The resource passed in must be :term:`location`-aware.

System Message: ERROR/3 (<string>, line 368); backlink

Unknown interpreted text role "term".

The presence or absence of a :term:`virtual root` has no impact on the behavior of :func:`~pyramid.traversal.resource_path`.

System Message: ERROR/3 (<string>, line 370); backlink

Unknown interpreted text role "term".

System Message: ERROR/3 (<string>, line 370); backlink

Unknown interpreted text role "func".

System Message: ERROR/3 (<string>, line 373)

Unknown directive type "index".

.. index::
   pair: resource; finding by path

Finding a Resource by Path

If you have a string path to a resource, you can grab the resource from that place in the application's resource tree using :func:`pyramid.traversal.find_resource`.

System Message: ERROR/3 (<string>, line 379); backlink

Unknown interpreted text role "func".

You can resolve an absolute path by passing a string prefixed with a / as the path argument:

System Message: ERROR/3 (<string>, line 386)

Error in "code-block" directive: unknown option: "linenos".

.. code-block:: python
   :linenos:

   from pyramid.traversal import find_resource
   url = find_resource(anyresource, '/path')

Or you can resolve a path relative to the resource you pass in by passing a string that isn't prefixed by /:

System Message: ERROR/3 (<string>, line 395)

Error in "code-block" directive: unknown option: "linenos".

.. code-block:: python
   :linenos:

   from pyramid.traversal import find_resource
   url = find_resource(anyresource, 'path')

Often the paths you pass to :func:`~pyramid.traversal.find_resource` are generated by the :func:`~pyramid.traversal.resource_path` API. These APIs are "mirrors" of each other.

System Message: ERROR/3 (<string>, line 401); backlink

Unknown interpreted text role "func".

System Message: ERROR/3 (<string>, line 401); backlink

Unknown interpreted text role "func".

If the path cannot be resolved when calling :func:`~pyramid.traversal.find_resource` (if the respective resource in the tree does not exist), a :exc:`KeyError` will be raised.

System Message: ERROR/3 (<string>, line 405); backlink

Unknown interpreted text role "func".

System Message: ERROR/3 (<string>, line 405); backlink

Unknown interpreted text role "exc".

See the :func:`pyramid.traversal.find_resource` documentation for more information about resolving a path to a resource.

System Message: ERROR/3 (<string>, line 409); backlink

Unknown interpreted text role "func".

System Message: ERROR/3 (<string>, line 412)

Unknown directive type "index".

.. index::
   pair: resource; lineage

Obtaining the Lineage of a Resource

:func:`pyramid.location.lineage` returns a generator representing the :term:`lineage` of the :term:`location` aware :term:`resource` object.

System Message: ERROR/3 (<string>, line 418); backlink

Unknown interpreted text role "func".

System Message: ERROR/3 (<string>, line 418); backlink

Unknown interpreted text role "term".

System Message: ERROR/3 (<string>, line 418); backlink

Unknown interpreted text role "term".

System Message: ERROR/3 (<string>, line 418); backlink

Unknown interpreted text role "term".

The :func:`~pyramid.location.lineage` function returns the resource it is passed, then each parent of the resource, in order. For example, if the resource tree is composed like so:

System Message: ERROR/3 (<string>, line 421); backlink

Unknown interpreted text role "func".

System Message: ERROR/3 (<string>, line 425)

Error in "code-block" directive: unknown option: "linenos".

.. code-block:: python
   :linenos:

   class Thing(object): pass

   thing1 = Thing()
   thing2 = Thing()
   thing2.__parent__ = thing1

Calling lineage(thing2) will return a generator. When we turn it into a list, we will get:

System Message: ERROR/3 (<string>, line 437)

Error in "code-block" directive: unknown option: "linenos".

.. code-block:: python
   :linenos:

   list(lineage(thing2))
   [ <Thing object at thing2>, <Thing object at thing1> ]

The generator returned by :func:`~pyramid.location.lineage` first returns the resource it was passed unconditionally. Then, if the resource supplied a __parent__ attribute, it returns the resource represented by resource.__parent__. If that resource has a __parent__ attribute, return that resource's parent, and so on, until the resource being inspected either has no __parent__ attribute or has a __parent__ attribute of None.

System Message: ERROR/3 (<string>, line 443); backlink

Unknown interpreted text role "func".

See the documentation for :func:`pyramid.location.lineage` for more information.

System Message: ERROR/3 (<string>, line 451); backlink

Unknown interpreted text role "func".

Determining if a Resource is In The Lineage of Another Resource

Use the :func:`pyramid.location.inside` function to determine if one resource is in the :term:`lineage` of another resource.

System Message: ERROR/3 (<string>, line 457); backlink

Unknown interpreted text role "func".

System Message: ERROR/3 (<string>, line 457); backlink

Unknown interpreted text role "term".

For example, if the resource tree is:

System Message: ERROR/3 (<string>, line 462)

Error in "code-block" directive: unknown option: "linenos".

.. code-block:: python
   :linenos:

   class Thing(object): pass

   a = Thing()
   b = Thing()
   b.__parent__ = a

Calling inside(b, a) will return True, because b has a lineage that includes a. However, calling inside(a, b) will return False because a does not have a lineage that includes b.

The argument list for :func:`~pyramid.location.inside` is (resource1, resource2). resource1 is 'inside' resource2 if resource2 is a :term:`lineage` ancestor of resource1. It is a lineage ancestor if its parent (or one of its parent's parents, etc.) is an ancestor.

System Message: ERROR/3 (<string>, line 475); backlink

Unknown interpreted text role "func".

System Message: ERROR/3 (<string>, line 475); backlink

Unknown interpreted text role "term".

See :func:`pyramid.location.inside` for more information.

System Message: ERROR/3 (<string>, line 480); backlink

Unknown interpreted text role "func".

System Message: ERROR/3 (<string>, line 482)

Unknown directive type "index".

.. index::
   pair: resource; finding root

Finding the Root Resource

Use the :func:`pyramid.traversal.find_root` API to find the :term:`root` resource. The root resource is the root resource of the :term:`resource tree`. The API accepts a single argument: resource. This is a resource that is :term:`location` aware. It can be any resource in the tree for which you want to find the root.

System Message: ERROR/3 (<string>, line 488); backlink

Unknown interpreted text role "func".

System Message: ERROR/3 (<string>, line 488); backlink

Unknown interpreted text role "term".

System Message: ERROR/3 (<string>, line 488); backlink

Unknown interpreted text role "term".

System Message: ERROR/3 (<string>, line 488); backlink

Unknown interpreted text role "term".

For example, if the resource tree is:

System Message: ERROR/3 (<string>, line 496)

Error in "code-block" directive: unknown option: "linenos".

.. code-block:: python
   :linenos:

   class Thing(object): pass

   a = Thing()
   b = Thing()
   b.__parent__ = a

Calling find_root(b) will return a.

The root resource is also available as request.root within :term:`view callable` code.

System Message: ERROR/3 (<string>, line 507); backlink

Unknown interpreted text role "term".

The presence or absence of a :term:`virtual root` has no impact on the behavior of :func:`~pyramid.traversal.find_root`. The root object returned is always the physical root object.

System Message: ERROR/3 (<string>, line 510); backlink

Unknown interpreted text role "term".

System Message: ERROR/3 (<string>, line 510); backlink

Unknown interpreted text role "func".

System Message: ERROR/3 (<string>, line 514)

Unknown directive type "index".

.. index::
   single: resource interfaces

Resources Which Implement Interfaces

Resources can optionally be made to implement an :term:`interface`. An interface is used to tag a resource object with a "type" that can later be referred to within :term:`view configuration` and by :func:`pyramid.traversal.find_interface`.

System Message: ERROR/3 (<string>, line 522); backlink

Unknown interpreted text role "term".

System Message: ERROR/3 (<string>, line 522); backlink

Unknown interpreted text role "term".

System Message: ERROR/3 (<string>, line 522); backlink

Unknown interpreted text role "func".

Specifying an interface instead of a class as the context or containment predicate arguments within :term:`view configuration` statements makes it possible to use a single view callable for more than one class of resource object. If your application is simple enough that you see no reason to want to do this, you can skip reading this section of the chapter.

System Message: ERROR/3 (<string>, line 527); backlink

Unknown interpreted text role "term".

For example, here's some code which describes a blog entry which also declares that the blog entry implements an :term:`interface`.

System Message: ERROR/3 (<string>, line 534); backlink

Unknown interpreted text role "term".

System Message: ERROR/3 (<string>, line 537)

Error in "code-block" directive: unknown option: "linenos".

.. code-block:: python
   :linenos:

   import datetime
   from zope.interface import implements
   from zope.interface import Interface

   class IBlogEntry(Interface):
       pass

   class BlogEntry(object):
       implements(IBlogEntry)
       def __init__(self, title, body, author):
           self.title = title
           self.body = body
           self.author = author
           self.created = datetime.datetime.now()

This resource consists of two things: the class which defines the resource constructor as the class BlogEntry, and an :term:`interface` attached to the class via an implements statement at class scope using the IBlogEntry interface as its sole argument.

System Message: ERROR/3 (<string>, line 555); backlink

Unknown interpreted text role "term".

The interface object used must be an instance of a class that inherits from :class:`zope.interface.Interface`.

System Message: ERROR/3 (<string>, line 560); backlink

Unknown interpreted text role "class".

A resource class may implement zero or more interfaces. You specify that a resource implements an interface by using the :func:`zope.interface.implements` function at class scope. The above BlogEntry resource implements the IBlogEntry interface.

System Message: ERROR/3 (<string>, line 563); backlink

Unknown interpreted text role "func".

You can also specify that a particular resource instance provides an interface, as opposed to its class. When you declare that a class implements an interface, all instances of that class will also provide that interface. However, you can also just say that a single object provides the interface. To do so, use the :func:`zope.interface.directlyProvides` function:

System Message: ERROR/3 (<string>, line 568); backlink

Unknown interpreted text role "func".

System Message: ERROR/3 (<string>, line 574)

Error in "code-block" directive: unknown option: "linenos".

.. code-block:: python
   :linenos:

   import datetime
   from zope.interface import directlyProvides
   from zope.interface import Interface

   class IBlogEntry(Interface):
       pass

   class BlogEntry(object):
       def __init__(self, title, body, author):
           self.title = title
           self.body = body
           self.author = author
           self.created = datetime.datetime.now()

   entry = BlogEntry('title', 'body', 'author')
   directlyProvides(entry, IBlogEntry)

:func:`zope.interface.directlyProvides` will replace any existing interface that was previously provided by an instance. If a resource object already has instance-level interface declarations that you don't want to replace, use the :func:`zope.interface.alsoProvides` function:

System Message: ERROR/3 (<string>, line 594); backlink

Unknown interpreted text role "func".

System Message: ERROR/3 (<string>, line 594); backlink

Unknown interpreted text role "func".

System Message: ERROR/3 (<string>, line 599)

Error in "code-block" directive: unknown option: "linenos".

.. code-block:: python
   :linenos:

   import datetime
   from zope.interface import alsoProvides
   from zope.interface import directlyProvides
   from zope.interface import Interface

   class IBlogEntry1(Interface):
       pass

   class IBlogEntry2(Interface):
       pass

   class BlogEntry(object):
       def __init__(self, title, body, author):
           self.title = title
           self.body = body
           self.author = author
           self.created = datetime.datetime.now()

   entry = BlogEntry('title', 'body', 'author')
   directlyProvides(entry, IBlogEntry1)
   alsoProvides(entry, IBlogEntry2)

:func:`zope.interface.alsoProvides` will augment the set of interfaces directly provided by an instance instead of overwriting them like :func:`zope.interface.directlyProvides` does.

System Message: ERROR/3 (<string>, line 624); backlink

Unknown interpreted text role "func".

System Message: ERROR/3 (<string>, line 624); backlink

Unknown interpreted text role "func".

For more information about how resource interfaces can be used by view configuration, see :ref:`using_resource_interfaces`.

System Message: ERROR/3 (<string>, line 628); backlink

Unknown interpreted text role "ref".

System Message: ERROR/3 (<string>, line 631)

Unknown directive type "index".

.. index::
   pair: resource; finding by interface or class

Finding a Resource With a Class or Interface in Lineage

Use the :func:`~pyramid.traversal.find_interface` API to locate a parent that is of a particular Python class, or which implements some :term:`interface`.

System Message: ERROR/3 (<string>, line 637); backlink

Unknown interpreted text role "func".

System Message: ERROR/3 (<string>, line 637); backlink

Unknown interpreted text role "term".

For example, if your resource tree is composed as follows:

System Message: ERROR/3 (<string>, line 642)

Error in "code-block" directive: unknown option: "linenos".

.. code-block:: python
   :linenos:

   class Thing1(object): pass
   class Thing2(object): pass

   a = Thing1()
   b = Thing2()
   b.__parent__ = a

Calling find_interface(a, Thing1) will return the a resource because a is of class Thing1 (the resource passed as the first argument is considered first, and is returned if the class or interface spec matches).

Calling find_interface(b, Thing1) will return the a resource because a is of class Thing1 and a is the first resource in b's lineage of this class.

Calling find_interface(b, Thing2) will return the b resource.

The second argument to find_interface may also be a :term:`interface` instead of a class. If it is an interface, each resource in the lineage is checked to see if the resource implements the specificed interface (instead of seeing if the resource is of a class). See also :ref:`resources_which_implement_interfaces`.

System Message: ERROR/3 (<string>, line 662); backlink

Unknown interpreted text role "term".

System Message: ERROR/3 (<string>, line 662); backlink

Unknown interpreted text role "ref".

System Message: ERROR/3 (<string>, line 668)

Unknown directive type "index".

.. index::
   single: resource API functions
   single: url generation (traversal)

:app:`Pyramid` API Functions That Act Against Resources

System Message: ERROR/3 (<string>, line 672); backlink

Unknown interpreted text role "app".

A resource object is used as the :term:`context` provided to a view. See :ref:`traversal_chapter` and :ref:`urldispatch_chapter` for more information about how a resource object becomes the context.

System Message: ERROR/3 (<string>, line 675); backlink

Unknown interpreted text role "term".

System Message: ERROR/3 (<string>, line 675); backlink

Unknown interpreted text role "ref".

System Message: ERROR/3 (<string>, line 675); backlink

Unknown interpreted text role "ref".

The APIs provided by :ref:`traversal_module` are used against resource objects. These functions can be used to find the "path" of a resource, the root resource in a resource tree, or to generate a URL for a resource.

System Message: ERROR/3 (<string>, line 679); backlink

Unknown interpreted text role "ref".

The APIs provided by :ref:`location_module` are used against resources. These can be used to walk down a resource tree, or conveniently locate one resource "inside" another.

System Message: ERROR/3 (<string>, line 683); backlink

Unknown interpreted text role "ref".

Some APIs in :ref:`security_module` accept a resource object as a parameter. For example, the :func:`~pyramid.security.has_permission` API accepts a resource object as one of its arguments; the ACL is obtained from this resource or one of its ancestors. Other APIs in the :mod:`pyramid.security` module also accept :term:`context` as an argument, and a context is always a resource.

System Message: ERROR/3 (<string>, line 687); backlink

Unknown interpreted text role "ref".

System Message: ERROR/3 (<string>, line 687); backlink

Unknown interpreted text role "func".

System Message: ERROR/3 (<string>, line 687); backlink

Unknown interpreted text role "mod".

System Message: ERROR/3 (<string>, line 687); backlink

Unknown interpreted text role "term".
Something went wrong with that request. Please try again.