keystoneauth1.discover module¶

The passive components to version discovery.

The Discover object in discover.py contains functions that can create objects on your behalf. These functions are not usable from within the keystoneauth1 library because you will get dependency resolution issues.

The Discover object in this file provides the querying components of Discovery. This includes functions like url_for which allow you to retrieve URLs and the raw data specified in version discovery responses.

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

Bases: 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__: list of weak references to the object (if defined)

Return endpoint data for a version.

NOTE: This method raises a TypeError if version is None. It is: kept for backwards compatability. New code should use versioned_data_for instead.

Parameters:: version (tuple) – The version is always a minimum version in the same major release as there should be no compatibility issues with using a version newer than the one asked for.
Returns:: the endpoint data for a URL that matches the required version (the format is described in version_data) or None if no match.
Return type:: dict

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

Get raw version information from URL.

Raw data indicates that only minimal validation processing is performed on the data, so what is returned here will be the data in the same format it was received from the endpoint.

Parameters:

allow_experimental (bool) – Allow experimental version endpoints.
allow_deprecated (bool) – Allow deprecated version endpoints.
allow_unknown (bool) – Allow endpoints with an unrecognised status.

Returns:

The endpoints returned from the server that match the criteria.

Return type:

list

Get the endpoint url for a version.

NOTE: This method raises a TypeError if version is None. It is: kept for backwards compatability. New code should use versioned_url_for instead.

Parameters:: version (tuple) – The version is always a minimum version in the same major release as there should be no compatibility issues with using a version newer than the one asked for.
Returns:: The url for the specified version or None if no match.
Return type:: str

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

Get normalized version data.

Return version data in a structured way.

Parameters:: reverse (bool) – Reverse the list. reverse=true will mean the returned list is sorted from newest to oldest version.
Returns:: A list of VersionData sorted by version number.
Return type:: list(VersionData)

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

Get normalized version data with versions as strings.

Return version data in a structured way.

Parameters:: reverse (bool) – Reverse the list. reverse=true will mean the returned list is sorted from newest to oldest version.
Returns:: A list of VersionData sorted by version number.
Return type:: list(VersionData)

Return endpoint data for the service at a url.

min_version and max_version can be given either as strings or tuples.

Parameters:

url (string) – If url is given, the data will be returned for the endpoint data that has a self link matching the url.
min_version – The minimum endpoint version that is acceptable. If min_version is given with no max_version it is as if max version is ‘latest’. If min_version is ‘latest’, max_version may only be ‘latest’ or None.
max_version – The maximum endpoint version that is acceptable. If min_version is given with no max_version it is as if max version is ‘latest’. If min_version is ‘latest’, max_version may only be ‘latest’ or None.

Returns:

the endpoint data for a URL that matches the required version (the format is described in version_data) or None if no match.

Return type:

dict

Get the endpoint url for a version.

min_version and max_version can be given either as strings or tuples.

Parameters:

min_version – The minimum version that is acceptable. If min_version is given with no max_version it is as if max version is ‘latest’.
max_version – The maximum version that is acceptable. If min_version is given with no max_version it is as if max version is ‘latest’.

Returns:

The url for the specified version or None if no match.

Return type:

str

Bases: object

Normalized information about a discovered endpoint.

Contains url, version, microversion, interface and region information. This is essentially the data contained in the catalog and the version discovery documents about an endpoint that is used to select the endpoint desired by the user. It is returned so that a user can know which qualities a discovered endpoint had, in case their request allowed for a range of possibilities.

Refer to the microversion specification for more information.

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

__copy__() → EndpointData: Return a new EndpointData based on this one.

__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': 'ty.Optional[str]', '_catalog_matches_exactly': 'bool', '_disc': 'ty.Optional[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__(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: Produce a string like EndpointData{key=val, …}, for debugging.

__weakref__: list of weak references to the object (if defined)

_get_catalog_discover_hack() → str

Apply the catalog hacks and figure out an unversioned endpoint.

This function is internal to keystoneauth1.

Returns:: A url that has been transformed by the regex hacks that match the service_type.

Find potential locations for version discovery URLs.

min_version and max_version are already normalized, so will either be None or a tuple.

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

Return version data dict for when discovery fails.

Parameters:: project_id (string) – ID of the currently scoped project. Used for removing project_id components of URLs from the catalog. (optional)
Returns:: A list of VersionData sorted by version number.
Return type:: 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]

Return version data for all versions discovery can find.

Parameters:: project_id (string) – ID of the currently scoped project. Used for removing project_id components of URLs from the catalog. (optional)
Returns:: A list of VersionData sorted by version number.
Return type:: 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

Run version discovery on the current endpoint.

A simplified version of get_versioned_data, get_current_versioned_data runs discovery but only on the endpoint that has been found already.

It can be useful in some workflows where the user wants version information about the endpoint they have.

Parameters:

session (keystoneauth1.session.Session) – A session object that can be used for communication.
allow (dict) – Extra filters to pass when discovering API versions. (optional)
cache (dict) – A dict to be used for caching results in addition to caching them on the Session. (optional)
project_id (string) – ID of the currently scoped project. Used for removing project_id components of URLs from the catalog. (optional)

Returns:

A new EndpointData with the requested versioned data.

Return type:

keystoneauth1.discover.EndpointData

Raises:

keystoneauth1.exceptions.discovery.DiscoveryFailure – If the appropriate versioned data could not be discovered.

Run version discovery for the service described.

Performs Version Discovery and returns a new EndpointData object with information found.

min_version and max_version can be given either as strings or tuples.

Parameters:

session (keystoneauth1.session.Session) – A session object that can be used for communication.
allow (dict) – Extra filters to pass when discovering API versions. (optional)
cache (dict) – A dict to be used for caching results in addition to caching them on the Session. (optional)
allow_version_hack (bool) – Allow keystoneauth to hack up catalog URLS to support older schemes. (optional, default True)
project_id (string) – ID of the currently scoped project. Used for removing project_id components of URLs from the catalog. (optional)
discover_versions (bool) – Whether to get version metadata from the version discovery document even if it’s not neccessary to fulfill the major version request. (optional, defaults to True)
min_version – The minimum version that is acceptable. If min_version is given with no max_version it is as if max version is ‘latest’.
max_version – The maximum version that is acceptable. If min_version is given with no max_version it is as if max version is ‘latest’.

Returns:

A new EndpointData with the requested versioned data.

Return type:

keystoneauth1.discover.EndpointData

Raises:

keystoneauth1.exceptions.discovery.DiscoveryFailure – If the appropriate versioned data could not be discovered.

property url: str | None

class keystoneauth1.discover.Status

Bases: 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__: list of weak references to the object (if defined)

classmethod normalize(raw_status: str) → str

Turn a status into a canonical status value.

If the status from the version discovery document does not match one of the known values, it will be set to ‘UNKNOWN’.

Parameters:: raw_status (str) – Status value from a discovery document.
Returns:: A canonicalized version of the status. Valid values are CURRENT, SUPPORTED, DEPRECATED, EXPERIMENTAL and UNKNOWN
Return type:: str

Bases: Dict[str, Any]

Normalized Version Data about an endpoint.

__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__': (typing.Dict[str, typing.Any],), '__dict__': <attribute '__dict__' of 'VersionData' objects>, '__weakref__': <attribute '__weakref__' of 'VersionData' objects>, '__parameters__': (), '__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__ = (typing.Dict[str, typing.Any],)

__parameters__ = ()

__weakref__: list of weak references to the object (if defined)

property collection: str | None

The URL for the discovery document.

May be None.

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

The maximum microversion supported by the endpoint.

May be None.

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

The minimum microversion supported by the endpoint.

May be None.

property raw_status: str | None: The status as provided by the server.

property status: str

A canonicalized version of the status.

Valid values are CURRENT, SUPPORTED, DEPRECATED and EXPERIMENTAL.

property url: str: The url for the endpoint.

property version: Tuple[int | float, ...] | None: The normalized version of the endpoint.

class keystoneauth1.discover._VersionHacks

Bases: object

A container to abstract the list of version hacks.

This could be done as simply a dictionary but is abstracted like this to make for easier testing.

__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': 'ty.Dict[str, ty.List[ty.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__: list of weak references to the object (if defined)

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

Add a new hack for a service type.

Parameters:

service_type (str) – The service_type in the catalog.
old (re.RegexObject) – The pattern to use.
new (str) – What to replace the pattern with.

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

Apply the catalog hacks and figure out an unversioned endpoint.

Parameters:

service_type (str) – the service_type to look up.
url (str) – The original url that came from a service_catalog.

Returns:

Either the unversioned url or the one from the catalog to try.

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

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

Convert val to an int or the special value LATEST.

Parameters:: val – An int()-able, or the string ‘latest’, or the special value LATEST.
Returns:: An int, or the special value 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

Convert val to a string, handling LATEST => ‘latest’.

Parameters:: val – An int or the special value LATEST.
Returns:: A string representation of val. If val was LATEST, the return is ‘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

Add a version removal rule for a particular service.

Originally deployments of OpenStack would contain a versioned endpoint in the catalog for different services. E.g. an identity service might look like http://localhost:5000/v2.0. This is a problem when we want to use a different version like v3.0 as there is no way to tell where it is located. We cannot simply change all service catalogs either so there must be a way to handle the older style of catalog.

This function adds a rule for a given service type that if part of the URL matches a given regular expression in old then it will be replaced with the new value. This will replace all instances of old with new. It should therefore contain a regex anchor.

For example the included rule states:

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

so if the catalog retrieves an identity URL that ends with /v2.0 or /v2.0/ then it should replace it simply with / to fix the user’s catalog.

Parameters:

service_type (str) – The service type as defined in the catalog that the rule will apply to.
old (re.RegexObject) – The regular expression to search for and replace if found.
new (str) – The new string to replace the pattern with.

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

Return the discovery object for a URL.

Check the session and the plugin cache to see if we have already performed discovery on the URL and if so return it, otherwise create a new discovery object, cache it and return it.

NOTE: This function is expected to be used by keystoneauth and should not be needed by users part of normal usage. A normal user should use get_endpoint or get_endpoint_data on keystoneauth.session.Session or endpoint_filters on keystoneauth.session.Session or keystoneauth.session.Session. However, should the user need to perform direct discovery for some reason, this function should be used so that the discovery caching is used.

Parameters:

session (keystoneauth1.session.Session) – A session object to discover with.
url (str) – The url to lookup.
cache (dict) – A dict to be used for caching results, in addition to caching them on the Session. (optional) Defaults to None.
authenticated (bool) – Include a token in the discovery call. (optional) Defaults to None, which will use a token if an auth plugin is installed.

Raises:

keystoneauth1.exceptions.discovery.DiscoveryFailure – if for some reason the lookup fails.
keystoneauth1.exceptions.http.HttpError – An error from an invalid HTTP response.

Returns:

A discovery object with the results of looking up that URL.

Return type:

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]]

Retrieve raw version data from a url.

The return is a list of dicts of the form:

[
    {
        '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',
    },
    ...,
]

Note: The maximum microversion may be specified by max_version or version, the former superseding the latter. All *version keys are optional. Other keys and ‘links’ entries are permitted, but ignored.

Parameters:

session (keystoneauth1.session.Session) – A Session object that can be used for communication.
url (string) – Endpoint or discovery URL from which to retrieve data.
authenticated (bool) – Include a token in the discovery call. (optional) Defaults to None.
version_header (string) – provide the OpenStack-API-Version header for services which don’t return version information without it, for backward compatibility.

Returns:

A list of dicts containing version information.

Return type:

list(dict)

Turn a version representation into a tuple.

Examples:

The following all produce a return value of (1, 0):

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

The following all produce a return value of (1, 20, 3):

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

The following all produce a return value of (LATEST, LATEST):

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

The following all produce a return value of (2, LATEST):

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

Parameters:: version – A version specifier in any of the following forms: String, possibly prefixed with ‘v’, containing one or more numbers or the string ‘latest’, separated by periods. Examples: ‘v1’, ‘v1.2’, ‘1.2.3’, ‘123’, ‘latest’, ‘1.latest’, ‘v1.latest’. Integer. This will be assumed to be the major version, with a minor version of 0. Float. The integer part is assumed to be the major version; the decimal part the minor version. Non-string iterable comprising integers, integer strings, the string ‘latest’, or the special value LATEST. Examples: (1,), [1, 2], (‘12’, ‘34’, ‘56’), (LATEST,), (2, ‘latest’)
Returns:: A tuple of len >= 2 comprising integers and/or LATEST.
Raises:: TypeError – If the input version cannot be interpreted.

Determine whether a candidate version is within a specified range.

Parameters:

min_version – The minimum version that is acceptable. None/empty indicates no lower bound.
max_version – The maximum version that is acceptable. None/empty indicates no upper bound.
candidate – Candidate version to test. May not be None/empty.

Returns:

True if candidate is between min_version and max_version; False otherwise.

Raises:

ValueError – If candidate is None.
TypeError – If any input cannot be normalized.

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

Test that an available version satisfies the required version.

To be suitable a version must be of the same major version as required and be at least a match in minor/patch level.

eg. 3.3 is a match for a required 3.1 but 4.1 is not.

Parameters:

required (tuple) – the version that must be met.
candidate (tuple) – the version to test against required.

Returns:

True if candidate is suitable False otherwise.

Return type:

bool

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

Turn a version tuple into a string.

Parameters:: version (tuple) – A version represented as a tuple of ints. As a special case, a tuple member may be LATEST, which translates to ‘latest’.
Returns:: A version represented as a period-delimited string.

keystoneauth1.discover module

keystoneauth1.discover module¶

keystoneauth1 5.9.1.dev1