pyramid.traversal

find_interface(resource, class_or_interface)[source]

Return the first resource found in the lineage of resource which, a) if class_or_interface is a Python class object, is an instance of the class or any subclass of that class or b) if class_or_interface is a interface, provides the specified interface. Return None if no resource providing interface_or_class can be found in the lineage. The resource passed in must be location-aware.

find_resource(resource, path)[source]

Given a resource object and a string or tuple representing a path (such as the return value of pyramid.traversal.resource_path() or pyramid.traversal.resource_path_tuple()), return a resource in this application's resource tree at the specified path. The resource passed in must be location-aware. If the path cannot be resolved (if the respective node in the resource tree does not exist), a KeyError will be raised.

This function is the logical inverse of pyramid.traversal.resource_path() and pyramid.traversal.resource_path_tuple(); it can resolve any path string or tuple generated by either of those functions.

Rules for passing a string as the path argument: if the first character in the path string is the / character, the path is considered absolute and the resource tree traversal will start at the root resource. If the first character of the path string is not the / character, the path is considered relative and resource tree traversal will begin at the resource object supplied to the function as the resource argument. If an empty string is passed as path, the resource passed in will be returned. Resource path strings must be escaped in the following manner: each path segment must be UTF-8 encoded and escaped via Python's urllib.quote. For example, /path/to%20the/La%20Pe%C3%B1a (absolute) or to%20the/La%20Pe%C3%B1a (relative). The pyramid.traversal.resource_path() function generates strings which follow these rules (albeit only absolute ones). The text may not have any non-ASCII characters in it.

Rules for passing a tuple as the path argument: if the first element in the path tuple is the empty string (for example ('', 'a', 'b', 'c'), the path is considered absolute and the resource tree traversal will start at the resource tree root object. If the first element in the path tuple is not the empty string (for example ('a', 'b', 'c')), the path is considered relative and resource tree traversal will begin at the resource object supplied to the function as the resource argument. If an empty sequence is passed as path, the resource passed in itself will be returned. No URL-quoting of individual path segments within the tuple is required (each segment may be any string representing a resource name). Resource path tuples generated by pyramid.traversal.resource_path_tuple() can always be resolved by find_resource.

find_root(resource)[source]

Find the root node in the resource tree to which resource belongs. Note that resource should be location-aware. Note that the root resource is available in the request object by accessing the request.root attribute.

resource_path(resource, *elements)[source]

Return a string object representing the absolute physical path of the resource object based on its position in the resource tree, e.g /foo/bar. Any positional arguments passed in as elements will be appended as path segments to the end of the resource path. For instance, if the resource's path is /foo/bar and elements equals ('a', 'b'), the returned string will be /foo/bar/a/b. The first character in the string will always be the / character (a leading / character in a path string represents that the path is absolute).

Resource path strings returned will be escaped in the following manner: each path segment will be encoded as UTF-8 and escaped via Python's urllib.quote. For example, /path/to%20the/La%20Pe%C3%B1a.

This function is a logical inverse of pyramid.traversal.find_resource: it can be used to generate path references that can later be resolved via that function.

The resource passed in must be location-aware.

Note

Each segment in the path string returned will use the __name__ attribute of the resource it represents within the resource tree. Each of these segments should be a string (as per the contract of location-awareness). However, no conversion or safety checking of resource names is performed. For instance, if one of the resources in your tree has a __name__ which (by error) is a dictionary, the pyramid.traversal.resource_path() function will attempt to append it to a string and it will cause a pyramid.exceptions.URLDecodeError.

Note

The root resource must have a __name__ attribute with a value of either None or the empty string for paths to be generated properly. If the root resource has a non-null __name__ attribute, its name will be prepended to the generated path rather than a single leading '/' character.

resource_path_tuple(resource, *elements)[source]

Return a tuple representing the absolute physical path of the resource object based on its position in a resource tree, e.g ('', 'foo', 'bar'). Any positional arguments passed in as elements will be appended as elements in the tuple representing the resource path. For instance, if the resource's path is ('', 'foo', 'bar') and elements equals ('a', 'b'), the returned tuple will be ('', 'foo', 'bar', 'a', 'b'). The first element of this tuple will always be the empty string (a leading empty string element in a path tuple represents that the path is absolute).

This function is a logical inverse of pyramid.traversal.find_resource(): it can be used to generate path references that can later be resolved by that function.

The resource passed in must be location-aware.

Note

Each segment in the path tuple returned will equal the __name__ attribute of the resource it represents within the resource tree. Each of these segments should be a string (as per the contract of location-awareness). However, no conversion or safety checking of resource names is performed. For instance, if one of the resources in your tree has a __name__ which (by error) is a dictionary, that dictionary will be placed in the path tuple; no warning or error will be given.

Note

The root resource must have a __name__ attribute with a value of either None or the empty string for path tuples to be generated properly. If the root resource has a non-null __name__ attribute, its name will be the first element in the generated path tuple rather than the empty string.

quote_path_segment(segment, safe="~!$&'()*+,;=:@")[source]

Return a quoted representation of a 'path segment' (such as the string __name__ attribute of a resource) as a string. If the segment passed in is a bytes object, it is decoded as a UTF-8 string. The result is then URL-quoted using Python's urllib.quote. If the segment passed in is not bytes nor a string, an error will be raised. The return value of quote_path_segment is always a string.

You may pass a string of characters that need not be encoded as the safe argument to this function. This corresponds to the safe argument to urllib.quote.

Note

The return value for each segment passed to this function is cached in a module-scope dictionary for speed: the cached version is returned when possible rather than recomputing the quoted version. No cache emptying is ever done for the lifetime of an application, however. If you pass arbitrary user-supplied strings to this function (as opposed to some bounded set of values from a 'working set' known to your application), it may become a memory leak.

virtual_root(resource, request)[source]

Provided any resource and a request object, return the resource object representing the virtual root of the current request. Using a virtual root in a traversal -based Pyramid application permits rooting. For example, the resource at the traversal path /cms will be found at http://example.com/ instead of rooting it at http://example.com/cms/.

If the resource passed in is a context obtained via traversal, and if the HTTP_X_VHM_ROOT key is in the WSGI environment, the value of this key will be treated as a 'virtual root path': the pyramid.traversal.find_resource() API will be used to find the virtual root resource using this path; if the resource is found, it will be returned. If the HTTP_X_VHM_ROOT key is not present in the WSGI environment, the physical root of the resource tree will be returned instead.

Virtual roots are not useful at all in applications that use URL dispatch. Contexts obtained via URL dispatch don't really support being virtually rooted (each URL dispatch context is both its own physical and virtual root). However if this API is called with a resource argument which is a context obtained via URL dispatch, the resource passed in will be returned unconditionally.

traverse(resource, path)[source]

Given a resource object as resource and a string or tuple representing a path as path (such as the return value of pyramid.traversal.resource_path() or pyramid.traversal.resource_path_tuple() or the value of request.environ['PATH_INFO']), return a dictionary with the keys context, root, view_name, subpath, traversed, virtual_root, and virtual_root_path.

A definition of each value in the returned dictionary:

  • context: The context (a resource object) found via traversal or URL dispatch. If the path passed in is the empty string, the value of the resource argument passed to this function is returned.

  • root: The resource object at which traversal begins. If the resource passed in was found via URL dispatch or if the path passed in was relative (non-absolute), the value of the resource argument passed to this function is returned.

  • view_name: The view name found during traversal or URL dispatch; if the resource was found via traversal, this is usually a representation of the path segment which directly follows the path to the context in the path. The view_name will be a string. The view_name will be the empty string if there is no element which follows the context path. An example: if the path passed is /foo/bar, and a resource object is found at /foo (but not at /foo/bar), the 'view name' will be 'bar'. If the resource was found via URL dispatch, the view_name will be the empty string unless the traverse predicate was specified or the *traverse route pattern was used, at which point normal traversal rules dictate the result.

  • subpath: For a resource found via traversal, this is a sequence of path segments found in the path that follow the view_name (if any). Each of these items is a string. If no path segments follow the view_name, the subpath will be the empty sequence. An example: if the path passed is /foo/bar/baz/buz, and a resource object is found at /foo (but not /foo/bar), the 'view name' will be 'bar' and the subpath will be ['baz', 'buz']. For a resource found via URL dispatch, the subpath will be a sequence of values discerned from *subpath in the route pattern matched or the empty sequence.

  • traversed: The sequence of path elements traversed from the root to find the context object during traversal. Each of these items is a string. If no path segments were traversed to find the context object (e.g. if the path provided is the empty string), the traversed value will be the empty sequence. If the resource is a resource found via URL dispatch, traversed will be None.

  • virtual_root: A resource object representing the 'virtual' root of the resource tree being traversed during traversal. See Virtual Hosting for a definition of the virtual root object. If no virtual hosting is in effect, and the path passed in was absolute, the virtual_root will be the physical root resource object (the object at which traversal begins). If the resource passed in was found via URL dispatch or if the path passed in was relative, the virtual_root will always equal the root object (the resource passed in).

  • virtual_root_path -- If traversal was used to find the resource, this will be the sequence of path elements traversed to find the virtual_root resource. Each of these items is a string. If no path segments were traversed to find the virtual_root resource (e.g. if virtual hosting is not in effect), the traversed value will be the empty list. If URL dispatch was used to find the resource, this will be None.

If the path cannot be resolved, a KeyError will be raised.

Rules for passing a string as the path argument: if the first character in the path string is the with the / character, the path will considered absolute and the resource tree traversal will start at the root resource. If the first character of the path string is not the / character, the path is considered relative and resource tree traversal will begin at the resource object supplied to the function as the resource argument. If an empty string is passed as path, the resource passed in will be returned. Resource path strings must be escaped in the following manner: each path segment must be encoded as UTF-8 and escaped via Python's urllib.quote. For example, /path/to%20the/La%20Pe%C3%B1a (absolute) or to%20the/La%20Pe%C3%B1a (relative). The pyramid.traversal.resource_path() function generates strings which follow these rules (albeit only absolute ones).

Rules for passing a tuple as the path argument: if the first element in the path tuple is the empty string (for example ('', 'a', 'b', 'c'), the path is considered absolute and the resource tree traversal will start at the resource tree root object. If the first element in the path tuple is not the empty string (for example ('a', 'b', 'c')), the path is considered relative and resource tree traversal will begin at the resource object supplied to the function as the resource argument. If an empty sequence is passed as path, the resource passed in itself will be returned. No URL-quoting or UTF-8-encoding of individual path segments within the tuple is required (each segment may be any string representing a resource name).

Explanation of the decoding of path segment values during traversal: Each segment is URL-unquoted, and UTF-8 decoded. Each segment is assumed to be encoded using the UTF-8 encoding (or a subset, such as ASCII); a pyramid.exceptions.URLDecodeError is raised if a segment cannot be decoded. If a segment name is empty or if it is ., it is ignored. If a segment name is .., the previous segment is deleted, and the .. is ignored. As a result of this process, the return values view_name, each element in the subpath, each element in traversed, and each element in the virtual_root_path will be decoded strings.

traversal_path(path)[source]

Variant of pyramid.traversal.traversal_path_info() suitable for decoding paths that are URL-encoded.

If this function is passed a string, it must be directly encodeable to ASCII. For example, '/foo' will work but '/<unprintable unicode>' (a string object with characters that cannot be encoded to ASCII) will not. A UnicodeEncodeError will be raised if the string cannot be encoded directly to ASCII.