keystoneauth1.discover 模块¶

用于版本发现的被动组件。

discover.py 中的 Discover 对象包含可以代表您创建对象的函数。这些函数无法从 keystoneauth1 库内部使用，因为您会遇到依赖解析问题。

此文件中的 Discover 对象提供了 Discovery 的查询组件。这包括 url_for 等函数，允许您检索 URL 和版本发现响应中指定的原始数据。

class keystoneauth1.discover.Discover(session: ks_session.Session, url: str, authenticated: bool | None = None)

基类: object

CURRENT_STATUSES = ('stable', 'current', 'supported')

DEPRECATED_STATUSES = ('deprecated',)

EXPERIMENTAL_STATUSES = ('experimental',)

__dict__ = mappingproxy({'__module__': 'keystoneauth1.discover', 'CURRENT_STATUSES': ('stable', 'current', 'supported'), 'DEPRECATED_STATUSES': ('deprecated',), 'EXPERIMENTAL_STATUSES': ('experimental',), '__init__': <function Discover.__init__>, 'raw_version_data': <function Discover.raw_version_data>, 'version_data': <function Discover.version_data>, 'version_string_data': <function Discover.version_string_data>, 'data_for': <function Discover.data_for>, 'url_for': <function Discover.url_for>, 'versioned_data_for': <function Discover.versioned_data_for>, 'versioned_url_for': <function Discover.versioned_url_for>, '__dict__': <attribute '__dict__' of 'Discover' objects>, '__weakref__': <attribute '__weakref__' of 'Discover' objects>, '__doc__': None, '__annotations__': {}})

__doc__ = None

__init__(session: ks_session.Session, url: str, authenticated: bool | None = None)

__module__ = 'keystoneauth1.discover'

__weakref__: 对该对象的弱引用列表

返回给定版本的端点数据。

注意：此方法如果 version 为 None，则会引发 TypeError。它: 是为了向后兼容而保留的。新代码应使用 versioned_data_for 代替。

参数：: version (tuple) – 版本始终是同一主版本的最低版本，因为使用比要求的版本更新的版本不应存在兼容性问题。
返回值:: 与所需版本匹配的 URL 的端点数据（格式在 version_data 中描述）或 None（如果没有匹配）。
返回类型:: dict

raw_version_data(allow_experimental: bool = False, allow_deprecated: bool = True, allow_unknown: bool = False) → list[dict[str, Any]]

从 URL 获取原始版本信息。

原始数据表明仅对数据执行最少的验证处理，因此这里返回的数据将与从端点接收到的数据格式相同。

参数：

allow_experimental (bool) – 允许实验性版本端点。
allow_deprecated (bool) – 允许已弃用的版本端点。
allow_unknown (bool) – 允许状态未识别的端点。

返回值:

从服务器返回的符合条件的端点。

返回类型:

列表

获取某个版本的端点 URL。

注意：此方法如果 version 为 None，则会引发 TypeError。它: 为向后兼容而保留。新代码应使用 versioned_url_for 代替。

参数：: version (tuple) – 版本始终是同一主版本的最低版本，因为使用比要求的版本更新的版本不应存在兼容性问题。
返回值:: 指定版本的 URL，如果没有匹配则返回 None。
返回类型:: str

version_data(reverse: bool = False, *, allow_experimental: bool = False, allow_deprecated: bool = True, allow_unknown: bool = False) → list[VersionData]

获取规范化的版本数据。

以结构化的方式返回版本数据。

参数：: reverse (bool) – 反转列表。reverse=true 意味着返回的列表按版本从新到旧排序。
返回值:: 一个按版本号排序的 VersionData 列表。
返回类型:: list(VersionData)

version_string_data(reverse: bool = False, *, allow_experimental: bool = False, allow_deprecated: bool = True, allow_unknown: bool = False) → list[VersionData]

获取版本为字符串的规范化版本数据。

以结构化的方式返回版本数据。

参数：: reverse (bool) – 反转列表。reverse=true 意味着返回的列表按版本从新到旧排序。
返回值:: 一个按版本号排序的 VersionData 列表。
返回类型:: list(VersionData)

返回 URL 处服务的端点数据。

min_version 和 max_version 可以是字符串或元组。

参数：

url (string) – 如果提供了 url，则将返回 self 链接与 url 匹配的端点数据。
min_version – 可接受的最低端点版本。如果提供了 min_version 而没有 max_version，则 max version 等于‘latest’。如果 min_version 是‘latest’，则 max_version 只能是‘latest’或 None。
max_version – 可接受的最高端点版本。如果提供了 min_version 而没有 max_version，则 max version 等于‘latest’。如果 min_version 是‘latest’，则 max_version 只能是‘latest’或 None。

返回值:

与所需版本匹配的 URL 的端点数据（格式在 version_data 中描述）或 None（如果没有匹配）。

返回类型:

dict

获取某个版本的端点 URL。

min_version 和 max_version 可以是字符串或元组。

参数：

min_version – 可接受的最低版本。如果提供了 min_version 而没有 max_version，则 max version 等于‘latest’。
max_version – 可接受的最高版本。如果提供了 min_version 而没有 max_version，则 max version 等于‘latest’。

返回值:

指定版本的 URL，如果没有匹配则返回 None。

返回类型:

str

基类: object

关于已发现端点的规范化信息。

包含 url、version、microversion、interface 和 region 信息。这本质上是目录和版本发现文档中关于用于选择用户所需端点的端点的数据。它被返回，以便用户可以知道已发现端点具有哪些属性，以防他们的请求允许一系列可能性。

有关更多信息，请参阅 microversion 规范。

https://specs.openstack.org/openstack/api-wg/guidelines/microversion_specification.html

__copy__() → EndpointData: 返回一个新的 EndpointData，基于此 EndpointData。

__dict__ = mappingproxy({'__module__': 'keystoneauth1.discover', '__doc__': 'Normalized information about a discovered endpoint.\n\n Contains url, version, microversion, interface and region information.\n This is essentially the data contained in the catalog and the version\n discovery documents about an endpoint that is used to select the endpoint\n desired by the user. It is returned so that a user can know which qualities\n a discovered endpoint had, in case their request allowed for a range of\n possibilities.\n\n Refer to the microversion specification for more information.\n\n https://specs.openstack.org/openstack/api-wg/guidelines/microversion_specification.html\n ', '__init__': <function EndpointData.__init__>, '__copy__': <function EndpointData.__copy__>, '__str__': <function EndpointData.__str__>, 'url': <property object>, 'get_current_versioned_data': <function EndpointData.get_current_versioned_data>, 'get_versioned_data': <function EndpointData.get_versioned_data>, 'get_all_version_string_data': <function EndpointData.get_all_version_string_data>, '_infer_version_data': <function EndpointData._infer_version_data>, '_set_version_info': <function EndpointData._set_version_info>, '_run_discovery': <function EndpointData._run_discovery>, '_get_discovery_url_choices': <function EndpointData._get_discovery_url_choices>, '+'_get_catalog_discover_hack': <function EndpointData._get_catalog_discover_hack>, '__dict__': <attribute '__dict__' of 'EndpointData' objects>, '__weakref__': <attribute '__weakref__' of 'EndpointData' objects>, '__annotations__': {'_saved_project_id': 'str | None', '+'_catalog_matches_exactly': 'bool', '_disc': 'Discover | None'}})

__doc__ = 'Normalized information about a discovered endpoint.\n\n Contains url, version, microversion, interface and region information.\n This is essentially the data contained in the catalog and the version\n discovery documents about an endpoint that is used to select the endpoint\n desired by the user. It is returned so that a user can know which qualities\n a discovered endpoint had, in case their request allowed for a range of\n possibilities.\n\n Refer to the microversion specification for more information.\n\n https://specs.openstack.org/openstack/api-wg/guidelines/microversion_specification.html\n '

__init__(catalog_url: str | None = None, service_url: str | None = None, service_type: str | None = None, service_name: str | None = None, service_id: str | None = None, region_name: str | None = None, interface: str | None = None, endpoint_id: str | None = None, raw_endpoint: str | None = None, api_version: tuple[int | float, ...] | None = None, major_version: str | None = None, min_microversion: tuple[int | float, ...] | None = None, max_microversion: tuple[int | float, ...] | None = None, next_min_version: str | None = None, not_before: str | None = None, status: str | None = None)

__module__ = 'keystoneauth1.discover'

__str__() → str: 生成一个字符串，如 EndpointData{key=val, …}，用于调试。

__weakref__: 对该对象的弱引用列表

_get_catalog_discover_hack() → str

应用目录 hack 并确定一个无版本端点。

此函数是 keystoneauth1 的内部函数。

返回值:: 一个已通过匹配 service_type 的正则表达式 hack 转换的 URL。

查找版本发现 URL 的潜在位置。

min_version 和 max_version 已经过标准化，因此要么是 None，要么是元组。

_infer_version_data(project_id: str | None = None) → list[VersionData]

返回发现失败时的版本数据字典。

参数：: project_id (字符串) – 当前作用域项目的 ID。用于从目录中删除项目的 URL 组件。（可选）
返回值:: 一个按版本号排序的 VersionData 列表。
返回类型:: list(VersionData)

_run_discovery(session: ks_session.Session, cache: dict[str, Discover] | None, min_version: tuple[int | float, ...] | None, max_version: tuple[int | float, ...] | None, project_id: str | None, allow_version_hack: bool, discover_versions: bool) → None

_set_version_info(session: ks_session.Session, allow: dict[str, Any], cache: dict[str, Discover] | None, allow_version_hack: bool, project_id: str | None, discover_versions: bool, min_version: tuple[int | float, ...] | None, max_version: tuple[int | float, ...] | None) → None

get_all_version_string_data(session: ks_session.Session, project_id: str | None = None) → list[VersionData]

返回发现可以找到的所有版本的数据。

参数：: project_id (字符串) – 当前作用域项目的 ID。用于从目录中删除项目的 URL 组件。（可选）
返回值:: 一个按版本号排序的 VersionData 列表。
返回类型:: list(VersionData)

get_current_versioned_data(session: ks_session.Session, allow: dict[str, Any] | None = None, cache: dict[str, Discover] | None = None, project_id: str | None = None) → EndpointData

在当前端点上运行版本发现。

get_versioned_data 的简化版本，get_current_versioned_data 运行发现，但仅限于已找到的端点。

这在用户想要获取其端点版本信息的一些工作流程中可能很有用。

参数：

session (keystoneauth1.session.Session) – 可以用于通信的会话对象。
allow (dict) – 在发现 API 版本时传递的额外筛选器。（可选）
cache (dict) – 除了缓存到 Session 之外，还用于缓存结果的 dict。（可选）
project_id (字符串) – 当前作用域项目的 ID。用于从目录中删除项目的 URL 组件。（可选）

返回值:

一个包含请求版本数据的新的 EndpointData 对象。

返回类型:

keystoneauth1.discover.EndpointData

引发:

keystoneauth1.exceptions.discovery.DiscoveryFailure – 如果无法发现适当的版本数据。

对服务进行版本发现。

执行版本发现并返回一个包含发现信息的新 EndpointData 对象。

min_version 和 max_version 可以是字符串或元组。

参数：

session (keystoneauth1.session.Session) – 可以用于通信的会话对象。
allow (dict) – 在发现 API 版本时传递的额外筛选器。（可选）
cache (dict) – 除了缓存到 Session 之外，还用于缓存结果的 dict。（可选）
allow_version_hack (bool) – 允许 keystoneauth 破解目录 URL 以支持旧方案。（可选，默认值为 True）
project_id (字符串) – 当前作用域项目的 ID。用于从目录中删除项目的 URL 组件。（可选）
discover_versions (bool) – 即使不需要满足主版本请求，是否从版本发现文档获取版本元数据。（可选，默认为 True）
min_version – 可接受的最低版本。如果提供了 min_version 而没有 max_version，则 max version 等于‘latest’。
max_version – 可接受的最高版本。如果提供了 min_version 而没有 max_version，则 max version 等于‘latest’。

返回值:

一个包含请求版本数据的新的 EndpointData 对象。

返回类型:

keystoneauth1.discover.EndpointData

引发:

keystoneauth1.exceptions.discovery.DiscoveryFailure – 如果无法发现适当的版本数据。

property url: str | None

class keystoneauth1.discover.Status

基类: object

CURRENT = 'CURRENT'

DEPRECATED = 'DEPRECATED'

EXPERIMENTAL = 'EXPERIMENTAL'

KNOWN = ('CURRENT', 'SUPPORTED', 'DEPRECATED', 'EXPERIMENTAL')

SUPPORTED = 'SUPPORTED'

UNKNOWN = 'UNKNOWN'

__dict__ = mappingproxy({'__module__': 'keystoneauth1.discover', 'CURRENT': 'CURRENT', 'SUPPORTED': 'SUPPORTED', 'DEPRECATED': 'DEPRECATED', 'EXPERIMENTAL': 'EXPERIMENTAL', 'UNKNOWN': 'UNKNOWN', 'KNOWN': ('CURRENT', 'SUPPORTED', 'DEPRECATED', 'EXPERIMENTAL'), 'normalize': <classmethod(<function Status.normalize>)>, '__dict__': <attribute '__dict__' of 'Status' objects>, '__weakref__': <attribute '__weakref__' of 'Status' objects>, '__doc__': None, '__annotations__': {}})

__doc__ = None

__module__ = 'keystoneauth1.discover'

__weakref__: 对该对象的弱引用列表

classmethod normalize(raw_status: str) → str

将状态转换为规范状态值。

如果来自版本发现文档的状态与已知值之一不匹配，则将其设置为“UNKNOWN”。

参数：: raw_status (str) – 来自发现文档的状态值。
返回值:: 状态的规范化版本。有效值为 CURRENT、SUPPORTED、DEPRECATED、EXPERIMENTAL 和 UNKNOWN。
返回类型:: str

基类: dict[str, Any]

关于端点的规范化版本数据。

__dict__ = mappingproxy({'__module__': 'keystoneauth1.discover', '__doc__': 'Normalized Version Data about an endpoint.', '__init__': <function VersionData.__init__>, 'version': <property object>, 'url': <property object>, 'collection': <property object>, 'min_microversion': <property object>, 'max_microversion': <property object>, 'status': <property object>, 'raw_status': <property object>, '__orig_bases__': (dict[str, typing.Any],), '__dict__': <attribute '__dict__' of 'VersionData' objects>, '__weakref__': <attribute '__weakref__' of 'VersionData' objects>, '__annotations__': {}})

__doc__ = 'Normalized Version Data about an endpoint.'

__init__(version: tuple[int | float, ...] | str | None, url: str, collection: str | None = None, max_microversion: tuple[int | float, ...] | str | None = None, min_microversion: tuple[int | float, ...] | str | None = None, next_min_version: tuple[int | float, ...] | str | None = None, not_before: str | None = None, status: str = 'CURRENT', raw_status: str | None = None)

__module__ = 'keystoneauth1.discover'

__orig_bases__ = (dict[str, typing.Any],)

__weakref__: 对该对象的弱引用列表

property collection: str | None

发现文档的 URL。

可能为 None。

property max_microversion: tuple[int | float, ...] | None

端点支持的最大微版本。

可能为 None。

property min_microversion: tuple[int | float, ...] | None

端点支持的最小微版本。

可能为 None。

property raw_status: str | None: 服务器提供的状态。

property status: str

状态的规范化版本。

有效值为 CURRENT、SUPPORTED、DEPRECATED 和 EXPERIMENTAL。

property url: str: 端点的 URL。

property version: tuple[int | float, ...] | None: 端点的规范化版本。

class keystoneauth1.discover._VersionHacks

基类: object

用于抽象版本 hack 列表的容器。

这可以简单地作为字典来完成，但之所以这样抽象，是为了更方便地进行测试。

__dict__ = mappingproxy({'__module__': 'keystoneauth1.discover', '__doc__': 'A container to abstract the list of version hacks.\n\n This could be done as simply a dictionary but is abstracted like this to\n make for easier testing.\n ', '__init__': <function _VersionHacks.__init__>, 'add_discover_hack': <function _VersionHacks.add_discover_hack>, 'get_discover_hack': <function _VersionHacks.get_discover_hack>, '__dict__': <attribute '__dict__' of '_VersionHacks' objects>, '__weakref__': <attribute '__weakref__' of '_VersionHacks' objects>, '__annotations__': {'_discovery_data': 'dict[str, list[tuple[re.Pattern[str], str]]]'}})

__doc__ = 'A container to abstract the list of version hacks.\n\n This could be done as simply a dictionary but is abstracted like this to\n make for easier testing.\n '

__init__() → None

__module__ = 'keystoneauth1.discover'

__weakref__: 对该对象的弱引用列表

add_discover_hack(service_type: str, old: Pattern[str], new: str = '') → None

为服务类型添加一个新的 hack。

参数：

service_type (str) – 目录中的 service_type。
old (re.RegexObject) – 要使用的模式。
new (str) – 要替换模式的内容。

get_discover_hack(service_type: str, url: str) → str

应用目录 hack 并确定一个无版本端点。

参数：

service_type (str) – 要查找的服务类型。
url (str) – 来自 service_catalog 的原始 URL。

返回值:

未版本化的 URL 或来自目录的要尝试的 URL。

keystoneauth1.discover._combine_relative_url(discovery_url: str, version_url: str) → str

keystoneauth1.discover._int_or_latest(val: str | float) → int | float

将 val 转换为 int 或特殊值 LATEST。

参数：: val – 可转换为 int 的值，或字符串“latest”，或特殊值 LATEST。
返回值:: 一个 int，或特殊值 LATEST。

keystoneauth1.discover._latest_soft_match(required: tuple[int | float, ...] | None, candidate: tuple[int | float, ...]) → bool

keystoneauth1.discover._normalize_version_args(version: str | int | float | Iterable[str | int | float] | None, min_version: str | int | float | Iterable[str | int | float] | None, max_version: str | int | float | Iterable[str | int | float] | None, service_type: str | None = None) → tuple[tuple[int | float, ...] | None, tuple[int | float, ...] | None]

keystoneauth1.discover._str_or_latest(val: str | int | float) → str

将 val 转换为字符串，处理 LATEST => ‘latest’。

参数：: val – 一个 int 或特殊值 LATEST。
返回值:: val 的字符串表示形式。如果 val 是 LATEST，则返回“latest”。

keystoneauth1.discover._version_from_url(url: str | None) → tuple[int | float, ...] | None

keystoneauth1.discover.add_catalog_discover_hack(service_type: str, old: Pattern[str], new: str) → None

为特定服务添加版本移除规则。

最初，OpenStack 的部署会包含目录中不同服务的版本化端点。例如，身份服务可能看起来像 https://:5000/v2.0。当我们要使用 v3.0 等不同版本时，这会成为一个问题，因为没有办法知道它的位置。我们也无法简单地更改所有服务目录，因此必须有一种方法来处理旧式目录。

此函数为给定的服务类型添加一条规则，即如果 URL 的一部分与 old 中的给定正则表达式匹配，则将其替换为 new 值。这将替换所有旧的实例为新的。因此，它应该包含一个正则表达式锚点。

例如，包含的规则说明：

add_catalog_version_hack('identity', re.compile('/v2.0/?$'), '/')

因此，如果目录检索到的 identity URL 以 /v2.0 或 /v2.0/ 结尾，它应该被简单地替换为 / 来修复用户的目录。

参数：

service_type (str) – 规则将应用于目录中定义的服务类型。
old (re.RegexObject) – 要搜索和替换的正则表达式，如果找到的话。
new (str) – 用于替换模式的新字符串。

keystoneauth1.discover.get_discovery(session: ks_session.Session, url: str, cache: dict[str, Discover] | None = None, authenticated: bool | None = False) → Discover

为 URL 返回发现对象。

检查会话和插件缓存，查看是否已经对 URL 执行过发现，如果是，则返回它，否则创建一个新的发现对象，将其缓存并返回它。

注意：此函数预计由 keystoneauth 使用，不应在正常使用中被用户需要。正常用户应该使用 keystoneauth.session.Session 上的 get_endpoint 或 get_endpoint_data，或 keystoneauth.session.Session 或 keystoneauth.session.Session 上的 endpoint_filters。但是，如果用户因任何原因需要执行直接发现，则应使用此函数，以便使用发现缓存。

参数：

session (keystoneauth1.session.Session) – 用于发现的会话对象。
url (str) – 要查找的 URL。
cache (dict) – 除了在 Session 上缓存结果外，还将用于缓存结果的字典。（可选）默认为 None。
authenticated (bool) – 在发现调用中包含令牌。（可选）默认为 None，如果安装了身份验证插件，将使用令牌。

引发:

keystoneauth1.exceptions.discovery.DiscoveryFailure – 如果由于某种原因查找失败。
keystoneauth1.exceptions.http.HttpError – 来自无效 HTTP 响应的错误。

返回值:

包含查找该 URL 结果的发现对象。

返回类型:

keystoneauth1.discover.Discovery

keystoneauth1.discover.get_version_data(session: ks_session.Session, url: str, authenticated: bool | None = None, version_header: str | None = None) → list[dict[str, Any]]

从 URL 中检索原始版本数据。

返回的是一个字典列表，格式如下：

[
    {
        'status': 'STABLE',
        'id': 'v2.3',
        'links': [
            {'href': 'http://network.example.com/v2.3', 'rel': 'self'},
            {'href': 'http://network.example.com/', 'rel': 'collection'},
        ],
        'min_version': '2.0',
        'max_version': '2.7',
    },
    ...,
]

注意：最大微版本可以通过 max_version 或 version 指定，前者优先于后者。所有 *version 键都是可选的。其他键和 'links' 条目也是允许的，但会被忽略。

参数：

session (keystoneauth1.session.Session) – 可用于通信的 Session 对象。
url (string) – 用于检索数据的端点或发现 URL。
authenticated (bool) – 在发现调用中包含令牌。（可选）默认为 None。
version_header (string) – 为不返回版本信息的服务提供 OpenStack-API-Version 标头，以实现向后兼容。

返回值:

一个包含版本信息的字典列表。

返回类型:

list(dict)

将版本表示形式转换为元组。

示例

以下都产生返回值 (1, 0)

1, '1', 'v1', [1], (1,), ['1'], 1.0, '1.0', 'v1.0', (1, 0)

以下都产生返回值 (1, 20, 3)

'v1.20.3', '1.20.3', (1, 20, 3), ['1', '20', '3']

以下都产生返回值 (LATEST, LATEST)

'latest', 'vlatest', ('latest', 'latest'), (LATEST, LATEST)

以下都产生返回值 (2, LATEST)

'2.latest', 'v2.latest', (2, LATEST), ('2', 'latest')

参数：: version – 版本说明符，形式如下：字符串，可能以 'v' 开头，包含一个或多个数字或字符串 'latest'，用句点分隔。示例：'v1'，'v1.2'，'1.2.3'，'123'，'latest'，'1.latest'，'v1.latest'。整数。这将假定为主要版本，次要版本为 0。浮点数。整数部分假定为主要版本；小数部分为次要版本。非字符串可迭代对象，包括整数、整数字符串、字符串 'latest'，或特殊值 LATEST。示例：(1,)，[1, 2]，('12', '34', '56')，(LATEST,)，(2, 'latest')
返回值:: 一个长度 >= 2 的元组，包含整数和/或 LATEST。
引发:: TypeError – 如果输入版本无法解释。

确定候选版本是否在指定范围内。

参数：

min_version – 可接受的最小版本。None/空表示没有下限。
max_version – 可接受的最大版本。None/空表示没有上限。
candidate – 要测试的候选版本。可能不为 None/空。

返回值:

如果 candidate 在 min_version 和 max_version 之间，则返回 True；否则返回 False。

引发:

ValueError – 如果 candidate 为 None。
TypeError – 如果任何输入无法被规范化。

keystoneauth1.discover.version_match(required: tuple[int | float, ...], candidate: tuple[int | float, ...]) → bool

测试可用版本是否满足所需版本。

要符合要求，版本必须与所需版本具有相同的次要版本，并在次要/补丁级别上至少匹配。

例如，3.3 匹配 3.1 的要求，但 4.1 不匹配。

参数：

required (tuple) – 必须满足的版本。
candidate (tuple) – 要与 required 进行比较的版本。

返回值:

如果 candidate 合适，则返回 True，否则返回 False。

返回类型:

bool

keystoneauth1.discover.version_to_string(version: tuple[int | float, ...]) → str

将版本元组转换为字符串。

参数：: version (tuple) – 以整数元组表示的版本。作为特殊情况，元组的成员可以是 LATEST，它将转换为 'latest'。
返回值:: 以句点分隔的字符串表示的版本。

keystoneauth1.discover 模块

keystoneauth1.discover 模块¶

keystoneauth1 5.12.1.dev2