pyramid.traversal

find_interface(resource, class_or_interface)

返回在中找到的第一个资源 lineage 属于 resource 哪一个）如果 class_or_interface 是python类对象，是类或该类的任何子类的实例，或者b）如果 class_or_interface 是一个 interface ，提供指定的接口。返回 None 如果没有资源提供 interface_or_class 可以在世系中找到。这个 resource 通过 must 是 location 意识到。

find_resource(resource, path)

给定资源对象和表示路径的字符串或元组（例如 pyramid.traversal.resource_path() 或 pyramid.traversal.resource_path_tuple() ）返回此应用程序资源树中指定路径处的资源。传入的资源 must 是 location 意识到。如果无法解析路径（如果资源树中的相应节点不存在），则 KeyError 将被提升。

这个函数是 pyramid.traversal.resource_path() 和 pyramid.traversal.resource_path_tuple() ；它可以解析由这些函数之一生成的任何路径字符串或元组。

传递 字符串 作为 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 `` /字符，则路径被视为相对路径，资源树遍历将从作为 ``resource 论点。如果空字符串作为 path ，即 resource 传入的将被返回。资源路径字符串必须按以下方式转义：每个路径段必须是UTF-8编码的，并通过Python的 urllib.quote 。例如, /path/to%20the/La%20Pe%C3%B1a (绝对)或 to%20the/La%20Pe%C3%B1a (相对)。这个 pyramid.traversal.resource_path() 函数生成遵循这些规则的字符串(尽管只有绝对规则)。文本中不能包含任何非ASCII字符。

传递 元组 作为 path 参数：如果路径元组中的第一个元素是空字符串(例如 ('', 'a', 'b', 'c') ，则该路径被视为绝对路径，并且资源树遍历将从资源树根对象开始。如果路径元组中的第一个元素不是空字符串(例如 ('a', 'b', 'c') )，则该路径被视为相对路径，并且资源树遍历将从提供给函数的资源对象开始，作为 resource 论点。如果将空序列作为 path ，即 resource 传入的参数本身将被返回。不需要对元组中的各个路径段进行URL引号(每个段可以是表示资源名称的任何字符串)。生成的资源路径元组 pyramid.traversal.resource_path_tuple() 始终可以通过以下方式解决 find_resource 。

find_root(resource)

在资源树中查找根节点 resource 属于。注意 resource 应该是 location 意识到。请注意，通过访问 request.root 属性。

resource_path(resource, *elements)

返回一个字符串对象，根据其在资源树中的位置表示资源对象的绝对物理路径，例如 /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 `` /``路径字符串中的字符表示路径是绝对路径）。

返回的资源路径字符串将按以下方式进行转义：每个路径段都将编码为UTF-8，并通过Python的 urllib.quote 。例如, /path/to%20the/La%20Pe%C3%B1a 。

这个函数是 pyramid.traversal.find_resource ：它可用于生成路径引用，稍后可通过该函数进行解析。

这个 resource 通过 must 是 location 意识到。

备注

返回的路径字符串中的每个段都将使用 __name__ 它在资源树中表示的资源的属性。这些细分市场中的每一个 应该 为字符串(根据的合同 location -意识)。但是，不执行资源名称的转换或安全检查。例如，如果树中的某个资源具有 __name__ 它(错误地)是一本词典， pyramid.traversal.resource_path() 函数将尝试将其追加到字符串，这将导致 pyramid.exceptions.URLDecodeError 。

备注

这个 root 资源 must 有一个 __name__ 值为或的属性 None 或用于正确生成路径的空字符串。如果根资源具有非空值 __name__ 属性，其名称将前置于生成的路径，而不是单个前导“/”字符。

resource_path_tuple(resource, *elements)

返回一个元组，该元组表示 resource 基于其在资源树中的位置的对象，例如 ('', 'foo', 'bar') . 作为传入的任何位置参数 elements 将作为元素附加到表示资源路径的元组中。例如，如果资源的路径是 ('', 'foo', 'bar') 元素等于 ('a', 'b') ，返回的元组将是 ('', 'foo', 'bar', 'a', 'b') . 这个元组的第一个元素总是空字符串（路径元组中的前导空字符串元素表示路径是绝对的）。

这个函数是 pyramid.traversal.find_resource() ：它可用于生成路径引用，这些路径引用稍后可由该函数解析。

这个 resource 通过 must 是 location 意识到。

备注

返回的路径元组中的每个段将等于 __name__ 它在资源树中表示的资源的属性。这些细分市场中的每一个 应该 为字符串(根据的合同 location -意识)。但是，不执行资源名称的转换或安全检查。例如，如果树中的某个资源具有 __name__ 它(由于错误)是一个字典，则该字典将被放在路径元组中；不会给出警告或错误。

备注

这个 root 资源 must 有一个 __name__ 值为或的属性 None 或要正确生成路径元组的空字符串。如果根资源具有非空值 __name__ 属性，其名称将是生成的路径元组中的第一个元素，而不是空字符串。

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

返回‘路径段’的带引号的表示形式(如字符串 __name__ 资源的属性)作为字符串。如果 segment 传入的是一个字节对象，它被解码为UTF-8字符串。然后使用Python的URL引用结果 urllib.quote 。如果传入的段既不是字节也不是字符串，则会引发错误。的返回值 quote_path_segment 始终是字符串。

您可以传递不需要编码为 safe 此函数的参数。这对应于 safe 参数为 urllib.quote 。

备注

传递给此函数的每个段的返回值都缓存在模块范围的字典中以提高速度：尽可能返回缓存的版本，而不是重新计算引用的版本。但是，在应用程序的整个生命周期内都不会清空缓存。如果您将用户提供的任意字符串传递给此函数(而不是应用程序已知的某个“工作集”中的某个有界值集)，则可能会造成内存泄漏。

virtual_root(resource, request)

提供任何 resource 和A request 对象，返回表示 virtual root 电流的 request . 在中使用虚拟根目录 traversal 基于 Pyramid 申请允许生根。例如，遍历路径处的资源 /cms 将在以下位置找到 http://example.com/ 而不是根植于 http://example.com/cms/ .

如果 resource 传入是通过 traversal 如果 HTTP_X_VHM_ROOT 键在wsgi环境中，此键的值将被视为“虚拟根路径”：该 pyramid.traversal.find_resource() API将用于使用此路径查找虚拟根资源；如果找到该资源，将返回该资源。如果 HTTP_X_VHM_ROOT 密钥不存在于wsgi环境中，物理 root 将返回资源树的。

虚拟根在使用 URL dispatch . 通过URL调度获得的上下文并不真正支持虚拟根目录（每个URL调度上下文都是它自己的物理根目录和虚拟根目录）。但是，如果使用 resource 参数是通过URL调度获得的上下文，传入的资源将无条件返回。

traverse(resource, path)

将资源对象作为 resource 以及表示路径的字符串或元组 path （例如 pyramid.traversal.resource_path() 或 pyramid.traversal.resource_path_tuple() 或价值 request.environ['PATH_INFO'] ，返回带有键的字典 context ， root ， view_name ， subpath ， traversed ， virtual_root 和 virtual_root_path .

返回字典中每个值的定义：

• context ： context (A) resource 对象)通过遍历或URL分派找到。如果 path 传入的是空字符串、 resource 返回传递给此函数的参数。

• root ：位于其上的资源对象 traversal 开始。如果 resource 通过URL分派找到传入的，或者如果 path 传入的是相对的(非绝对的)， resource 返回传递给此函数的参数。

• view_name ： view name 在此期间找到 traversal 或 URL dispatch ；如果 resource 是通过遍历找到的，则这通常是路径段的表示形式，该路径段直接跟随到 context 在 path 。这个 view_name 将是一个字符串。这个 view_name 如果没有跟在后面的元素，则为空字符串 context 路径。例如：如果传递的路径是 /foo/bar ，并且可以在以下位置找到资源对象 /foo (但不是在 /foo/bar )，则“视图名称”将为 'bar' 。如果 resource 是通过URL调度找到的，则 view_name 将为空字符串，除非 traverse 谓词已指定，或者 *traverse 使用路由模式，此时正常遍历规则决定结果。

• subpath ：对于 resource 通过以下途径找到 traversal ，这是在 path 紧随其后的是 view_name (如有的话)。这些项目中的每一项都是一个字符串。如果没有路径段跟在 view_name 则子路径将是空序列。例如：如果传递的路径是 /foo/bar/baz/buz ，并且可以在以下位置找到资源对象 /foo (但不是 /foo/bar )，则“视图名称”将为 'bar' 以及 subpath 将会是 ['baz', 'buz'] 。对于 resource 通过URL分派找到，子路径将是从 *subpath 在匹配的路由模式或空序列中。

• traversed ：从根开始遍历的路径元素序列，以查找 context 过程中的对象 traversal 。这些项目中的每一项都是一个字符串。如果没有遍历路径段来查找 context 对象(例如，如果 path 提供的是空字符串)，则 traversed 值将是空序列。如果 resource 是通过以下方式找到的资源 URL dispatch ，则遍历将为无。

• virtual_root ：表示正在遍历的资源树的“虚拟”根的资源对象 traversal . 见 虚拟主机 用于虚拟根对象的定义。如果没有有效的虚拟主机，并且 path 传来的是绝对的 virtual_root 将是 身体的 根资源对象 traversal 开始）。如果 resource 通过 URL dispatch 或者如果 path 传进来的是亲戚 virtual_root 将始终等于 root 对象（传入的资源）。

• virtual_root_path --如果 traversal 用于查找 resource ，这将是遍历的路径元素序列，以查找 virtual_root 资源。这些项目中的每一项都是一个字符串。如果没有遍历路径段来查找 virtual_root 资源(例如，如果虚拟主机未生效)， traversed 值将为空列表。如果使用URL调度来查找 resource ，这将是 None 。

如果无法解析路径，则 KeyError 将被提升。

传递 字符串 作为 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 `` /字符，则路径被视为相对路径，资源树遍历将从作为 ``resource 论点。如果空字符串作为 path ，即 resource 传入的将被返回。资源路径字符串必须按以下方式转义：每个路径段必须编码为UTF-8，并通过Python的 urllib.quote 。例如, /path/to%20the/La%20Pe%C3%B1a (绝对)或 to%20the/La%20Pe%C3%B1a (相对)。这个 pyramid.traversal.resource_path() 函数生成遵循这些规则的字符串(尽管只有绝对规则)。

传递 元组 作为 path 参数：如果路径元组中的第一个元素是空字符串(例如 ('', 'a', 'b', 'c') ，则该路径被视为绝对路径，并且资源树遍历将从资源树根对象开始。如果路径元组中的第一个元素不是空字符串(例如 ('a', 'b', 'c') )，则该路径被视为相对路径，并且资源树遍历将从提供给函数的资源对象开始，作为 resource 论点。如果将空序列作为 path ，即 resource 传入的参数本身将被返回。不需要对元组中的各个路径段进行URL引用或UTF-8编码(每个段可以是代表资源名称的任何字符串)。

关于解码的解释 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 .. 被忽略。此过程的结果是，返回值 view_name 中的每个元素 subpath 中的每个元素 traversed 中的每个元素 virtual_root_path 将被解码的字符串。

traversal_path(path)

变异体 pyramid.traversal.traversal_path_info() 适用于解码URL编码的路径。

如果向此函数传递字符串，则它 must 可以直接编码为ASCII。例如，‘/foo’可以工作，但‘/<unprintable Unicode>’(字符不能编码为ASCII的字符串对象)不行。一个 UnicodeEncodeError 如果字符串不能直接编码为ASCII，则将引发。