pyramid.traversal
¶
- find_interface(resource, class_or_interface)[ソース]¶
Return the first resource found in the lineage of
resource
which, a) ifclass_or_interface
is a Python class object, is an instance of the class or any subclass of that class or b) ifclass_or_interface
is a interface, provides the specified interface. ReturnNone
if no resource providinginterface_or_class
can be found in the lineage. Theresource
passed in must be location-aware.
- find_resource(resource, path)[ソース]¶
Given a resource object and a string or tuple representing a path (such as the return value of
pyramid.traversal.resource_path()
orpyramid.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), aKeyError
will be raised.This function is the logical inverse of
pyramid.traversal.resource_path()
andpyramid.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 theresource
argument. If an empty string is passed aspath
, theresource
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'surllib.quote
. For example,/path/to%20the/La%20Pe%C3%B1a
(absolute) orto%20the/La%20Pe%C3%B1a
(relative). Thepyramid.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 theresource
argument. If an empty sequence is passed aspath
, theresource
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 bypyramid.traversal.resource_path_tuple()
can always be resolved byfind_resource
.
- find_root(resource)[ソース]¶
Find the root node in the resource tree to which
resource
belongs. Note thatresource
should be location-aware. Note that the root resource is available in the request object by accessing therequest.root
attribute.
- resource_path(resource, *elements)[ソース]¶
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 aselements
will be appended as path segments to the end of the resource path. For instance, if the resource's path is/foo/bar
andelements
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.注釈
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, thepyramid.traversal.resource_path()
function will attempt to append it to a string and it will cause apyramid.exceptions.URLDecodeError
.注釈
The root resource must have a
__name__
attribute with a value of eitherNone
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)[ソース]¶
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 aselements
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.注釈
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.注釈
The root resource must have a
__name__
attribute with a value of eitherNone
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="~!$&'()*+,;=:@")[ソース]¶
Return a quoted representation of a 'path segment' (such as the string
__name__
attribute of a resource) as a string. If thesegment
passed in is a bytes object, it is decoded as a UTF-8 string. The result is then URL-quoted using Python'surllib.quote
. If the segment passed in is not bytes nor a string, an error will be raised. The return value ofquote_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 thesafe
argument tourllib.quote
.注釈
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)[ソース]¶
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 athttp://example.com/
instead of rooting it athttp://example.com/cms/
.If the
resource
passed in is a context obtained via traversal, and if theHTTP_X_VHM_ROOT
key is in the WSGI environment, the value of this key will be treated as a 'virtual root path': thepyramid.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 theHTTP_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)[ソース]¶
Given a resource object as
resource
and a string or tuple representing a path aspath
(such as the return value ofpyramid.traversal.resource_path()
orpyramid.traversal.resource_path_tuple()
or the value ofrequest.environ['PATH_INFO']
), return a dictionary with the keyscontext
,root
,view_name
,subpath
,traversed
,virtual_root
, andvirtual_root_path
.A definition of each value in the returned dictionary:
context
: The context (a resource object) found via traversal or URL dispatch. If thepath
passed in is the empty string, the value of theresource
argument passed to this function is returned.root
: The resource object at which traversal begins. If theresource
passed in was found via URL dispatch or if thepath
passed in was relative (non-absolute), the value of theresource
argument passed to this function is returned.view_name
: The view name found during traversal or URL dispatch; if theresource
was found via traversal, this is usually a representation of the path segment which directly follows the path to thecontext
in thepath
. Theview_name
will be a string. Theview_name
will be the empty string if there is no element which follows thecontext
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 theresource
was found via URL dispatch, theview_name
will be the empty string unless thetraverse
predicate was specified or the*traverse
route pattern was used, at which point normal traversal rules dictate the result.subpath
: For aresource
found via traversal, this is a sequence of path segments found in thepath
that follow theview_name
(if any). Each of these items is a string. If no path segments follow theview_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 aresource
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 thecontext
object during traversal. Each of these items is a string. If no path segments were traversed to find thecontext
object (e.g. if thepath
provided is the empty string), thetraversed
value will be the empty sequence. If theresource
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 thepath
passed in was absolute, thevirtual_root
will be the physical root resource object (the object at which traversal begins). If theresource
passed in was found via URL dispatch or if thepath
passed in was relative, thevirtual_root
will always equal theroot
object (the resource passed in).virtual_root_path
-- If traversal was used to find theresource
, this will be the sequence of path elements traversed to find thevirtual_root
resource. Each of these items is a string. If no path segments were traversed to find thevirtual_root
resource (e.g. if virtual hosting is not in effect), thetraversed
value will be the empty list. If URL dispatch was used to find theresource
, this will beNone
.
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 theresource
argument. If an empty string is passed aspath
, theresource
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'surllib.quote
. For example,/path/to%20the/La%20Pe%C3%B1a
(absolute) orto%20the/La%20Pe%C3%B1a
(relative). Thepyramid.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 theresource
argument. If an empty sequence is passed aspath
, theresource
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); apyramid.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 valuesview_name
, each element in thesubpath
, each element intraversed
, and each element in thevirtual_root_path
will be decoded strings.
- traversal_path(path)[ソース]¶
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.