(機械翻訳) pyramid.traversal

find_interface(resource, class_or_interface)

a） `` class_or_interface``がPythonクラスオブジェクトである場合、そのクラスのインスタンスか、そのクラスのサブクラスかb） `` class_or_interface``が：term： interface`であれば、指定されたインタフェースを提供します。系統で ` interface_or_class``を提供するリソースが見つからない場合に `` None``を返します。 *で渡される ``リソース ``は：term： `location`を意識していなければなりません。

find_resource(resource, path)

リソースオブジェクトと、パスを表す文字列またはタプル（例えば：func： pyramid.traversal.resource_path`または：func： pyramid.traversal.resource_path_tuple`の戻り値）を指定すると、このアプリケーションのリソースツリー内のリソースを返します指定されたパスにある。渡されるリソースは、term： `location`を意識して*指定する必要があります。パスを解決できない場合（リソースツリー内の各ノードが存在しない場合）、a：exc： `KeyError`が発生します。

この関数は：func： pyramid.traversal.resource_path`と：func： pyramid.traversal.resource_path_tuple`の論理的な逆です。これらの関数のいずれかによって生成されたパス文字列またはタプルを解決できます。

*文字列*を `` path``引数として渡すためのルール：パス文字列の最初の文字が `` / ``文字の場合、パスは絶対パスとみなされ、リソースツリーの探索はルートリソースから始まります。パス文字列の最初の文字が `` / ``でなければ、そのパスは相対パスとみなされ、 `` resource``引数として関数に渡されたリソースオブジェクトからリソースツリーの探索が始まります。空の文字列が `` path``として渡されると、渡された `` resource``が返されます。リソースパス文字列は、次のようにエスケープする必要があります。各UnicodeパスセグメントはUTF-8としてエンコードする必要があり、各パスセグメントはPythonの：mod： urllib.quote`でエスケープする必要があります。たとえば、 ` / path / to％20the / La％20Pe％C3％B1a``（絶対）または ``％20the / La％20Pe％C3％B1a``（相対）です。 ：func： `pyramid.traversal.resource_path`関数は、これらの規則に従う文字列を生成します（ただし絶対パスのみです）。

Rules for passing text (Unicode) as the path argument are the same as those for a string. In particular, the text may not have any nonascii characters in it.

パスのタプルの最初の要素が空の文字列であれば（例えば ``（ ''、 'a'、 'b'、 'c'） ` ``（ 'a'、 'b'、 'c'）のような空の文字列でなければ、リソースツリーのルートオブジェクトからリソースツリーのトラバーサルが開始されます。 '） ``） ``） ``のように、パスは相対的なものとみなされ、 `` resource``引数として関数に与えられたリソースオブジェクトからリソースツリーの探索が始まります。タプル内の個々のパスセグメントのURLクォートまたはUTF-8エンコーディングは必要ありません（各セグメントは、リソース名を表す任意の文字列またはユニコードオブジェクトです）。 ：func： pyramid.traversal.resource_path_tuple`は常に `find_resource``で解決できます。

find_root(resource)

`` resource``が属するリソースツリー内のルートノードを探します。 `` resource``は：term： location`を意識していなければなりません。ルートリソースは ` request.root``属性にアクセスすることでリクエストオブジェクトで利用できることに注意してください。

resource_path(resource, *elements)

リソースツリーの位置に基づいてリソースオブジェクトの絶対的な物理パスを表す文字列オブジェクトを返します。たとえば、 `` / foo / bar``です。 `` elements``として渡された任意の位置引数は、パスのセグメントとしてリソースパスの末尾に追加されます。たとえば、リソースのパスが `` / foo / bar``で、 `` elements``が （ 'a'、 'b'） ``と等しい場合、返される文字列は `` / foo / bar / a / b。文字列の最初の文字は常に `` / ``文字になります（パス文字列の先頭の `` / ``文字はパスが絶対パスであることを表します）。

返されるリソースパス文字列は次のようにエスケープされます。各ユニコードパスセグメントはUTF-8としてエンコードされ、各パスセグメントはPythonの：mod： `urllib.quote`でエスケープされます。例えば、 "/ path / to％20the / La％20Pe％C3％B1a"となります。

この関数は、mod： `pyramid.traversal.find_resource`の論理的な逆です：パス参照を生成するために使用することができます。パス参照は、後でその関数を介して解決することができます。

*で渡される ``リソース ``は：term： `location`を意識していなければなりません。

注釈

返されるパス文字列の各セグメントは、リソースツリー内で表すリソースの `` __name__``属性を使用します。これらの各セグメント*は、（term： location-awarenessの契約に従って）ユニコードまたは文字列オブジェクトでなければなりません。ただし、リソース名の変換や安全性チェックは行われません。たとえば、ツリー内のリソースの1つが（エラーによって）辞書である `` __name__``を持つ場合、：func： `pyramid.traversal.resource_path`関数はそれを文字列に追加しようとします。 a：exc： `pyramid.exceptions.URLDecodeError`を引き起こします。

注釈

：term： root`リソース*は None``の値を持つ __name__``属性、またはパスが正しく生成されるための空の文字列を持たなければなりません。ルートリソースが非ヌルの ` __name__``属性を持つ場合、その名前は単一の先頭の '/'文字ではなく、生成されたパスの先頭に追加されます。

resource_path_tuple(resource, *elements)

``（ '、' foo '、' bar '） のようにリソースツリー内の位置に基づいて resource``オブジェクトの絶対的な物理パスを表すタプルを返します。 ` elements``として渡された任意の位置引数は、リソースパスを表すタプルの要素として追加されます。たとえば、リソースのパスが ``（ ''、 'foo'、 'bar'） ``で要素が ``（ 'a'、b '） ``の場合、返されるタプルは ``（' '、' foo '、' bar '、' a '、' b '） ``を指定します。このタプルの最初の要素は、常に空の文字列になります（パスタプルの先頭の空の文字列要素は、パスが絶対パスであることを表します）。

この関数は：func： `pyramid.traversal.find_resource`の論理的な逆です：それは後でその関数で解決できるパス参照を生成するために使用できます。

*で渡される ``リソース ``は：term： `location`を意識していなければなりません。

注釈

返されるパスタプルの各セグメントは、それがリソースツリー内で表すリソースの `` __name__``属性と等しくなります。これらの各セグメント*は、（term： location-awarenessの契約に従って）ユニコードまたは文字列オブジェクトでなければなりません。ただし、リソース名の変換や安全性チェックは行われません。たとえば、ツリー内のリソースの1つが（エラーによって）辞書である `` __name__``を持つ場合、その辞書はパスタプルに配置されます。警告またはエラーは表示されません。

注釈

：term： root`リソース*は、 None``の値を持つ __name__``属性、またはパスタプルが正しく生成されるための空の文字列を持たなければなりません。ルートリソースが非ヌルの ` __name__``属性を持つ場合、その名前は空の文字列ではなく、生成されたパスタプルの最初の要素になります。

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

virtual_root(resource, request)

any：term： resource`とa：term： request`オブジェクトを提供すると、current：term： request`の：term： virtual root`を表すリソースオブジェクトを返します。 ：term： traversal`ベースの仮想ルートを使用する：app： Pyramid`アプリケーションがルートを許可します。たとえば、トラバーサルパス `` / cms``のリソースは `` http：// example.com / cms / ``でルートするのではなく、 `` http：// example.com / `` 。

渡された `` resource``が：term： traversal`で取得されたコンテキストで、 HTTP_X_VHM_ROOT``キーがWSGI環境にある場合、このキーの値は '仮想ルートパス'：func： `pyramid.traversal.find_resource APIがこのパスを使って仮想ルートリソースを見つけるために使われます。リソースが見つかった場合は、それが返されます。もし `` HTTP_X_VHM_ROOT``キーがWSGI環境になければ、代わりにリソースツリーのphysical：term： `ルート`が返されます。

仮想ルートは、term： URL dispatch`を使用するアプリケーションではまったく役に立ちません。 URLディスパッチによって得られたコンテキストは、事実上ルートされていることを実際にはサポートしていません（各URLディスパッチコンテキストは、それ自身の物理ルートと仮想ルートの両方です）。しかし、このAPIがURLディスパッチを介して取得されたコンテキストである ` resource``引数で呼び出された場合、渡されたリソースは無条件に返されます。

traverse(resource, path)

リソースオブジェクトを `` resource``とし、パスを `` path``（例えば：func： pyramid.traversal.resource_path`や：func： pyramid.traversalの戻り値など）として表す文字列またはタプルを与えます。 `` context``、 `` root``、 `` view_name``、 `` subpath``などのキーを持つ辞書を返します。 `` traversed``、 `` virtual_root``、 `` virtual_root_path``の3つです。

返される辞書の各値の定義：

• `` context``：：term： context`（a：term： resource`オブジェクト）はトラバーサルまたはURLディスパッチによって見つかりました。渡された `` path``が空文字列の場合、この関数に渡された `` resource``引数の値が返されます。
• `` root``：term： traversal`が始まるリソースオブジェクトです。渡された ` resource``がurlディスパッチによって見つかった場合、または渡された `` path``が相対的（非絶対的）な場合、この関数に渡された `` resource``引数の値が返されます。
• `` view_name``：term： traversal`または：term： url dispatch`の間に見つかった：term： view name;トラバーサルを介して `` resource``が見つかった場合、これは通常 `` path``の `` context``へのパスの直後にあるパスセグメントの表現です。 `` view_name``は、Unicodeオブジェクトまたは空文字列になります。 `` context``パスに続く要素がない場合、 `` view_name``は空文字列になります。例：渡されたパスが `` / foo / bar``で、リソースオブジェクトが `` / foo``（ただし `` / foo / bar``ではなく）にある場合、 'view name'は「ウバール」です。 urldispatchで `` resource``が見つかった場合、view_nameは見つかった経路が登録された名前になります。
• `` subpath``：term： traversal`を介して見つかる リソース の場合、これは view_name``（もしあれば）の後ろにある path``にあるパスセグメントのシーケンスです。これらの各項目は、Unicodeオブジェクトです。 ` view_name``に続くパスセグメントがない場合、サブパスは空のシーケンスになります。例：渡されたパスが `` / foo / bar / baz / buz``であり、リソースオブジェクトが `` / foo``（しかし `` / foo / bar``ではなく）で見つかった場合、 'view名前は `` u'bar'``、：term： subpath`は [u'baz '、u'buz'] となります。 url dispatchを介して見つけられる ` resource``の場合、サブパスはルートパターンマッチまたは空のシーケンスで `` * subpath``から識別される一連の値になります。
• `` traversed``： `` traversal``の間に `` context``オブジェクトを見つけるために、ルートから横断されたパス要素のシーケンスです。これらの各項目は、Unicodeオブジェクトです。 `` context``オブジェクトを見つけるためにパスセグメントがトラバースされていない場合（例えば、 `` path``が空文字列の場合）、 `` traversed``値は空のシーケンスになります。 `` resource``が：term： `url dispatch`で見つかったリソースであれば、traversedはNoneになります。
• `` virtual_root``：term： traversal`の間にトラバースされるリソースツリーの '仮想'ルートを表すリソースオブジェクト。仮想ルートオブジェクトの定義については：ref： `vhosting_chapter`を参照してください。仮想ホスティングが有効でなく、渡された ` path``が絶対パスであれば、 `` virtual_root``は* physical *ルートリソースオブジェクト（：term： traversal`が始まるオブジェクト）になります。 ：term： `URL dispatch`で渡された resource``が渡された場合、または path``が相対パスで渡された場合、 virtual_root``は `root``オブジェクトリソースが渡されました）。
• `` virtual_root_path`` - ：term： traversal`が resource``を見つけるために使われた場合、 virtual_root``リソースを見つけるために横断されたパス要素のシーケンスになります。これらの各項目は、Unicodeオブジェクトです。 ` virtual_root``リソースを見つけるためにパスセグメントがトラバースされていない場合（例えば仮想ホスティングが有効でない場合）、 `` traversed``の値は空のリストになります。 url dispatchを使って `` resource``を見つけた場合、これは `` None``になります。

パスを解決できない場合は、：exc： `KeyError`が発生します。

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 Unicode path segment must be encoded as UTF-8 and each path segment must 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 or unicode object representing a resource name).

Explanation of the conversion of path segment values to Unicode during traversal: Each segment is URL-unquoted, and decoded into Unicode. 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 Unicode as opposed to a string, and will be URL-decoded.

traversal_path(path)

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

If this function is passed a Unicode object instead of a sequence of bytes as path, that Unicode object must directly encodeable to ASCII. For example, u'/foo' will work but u'/<unprintable unicode>' (a Unicode object with characters that cannot be encoded to ascii) will not. A UnicodeEncodeError will be raised if the Unicode cannot be encoded directly to ASCII.