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, url, authenticated=None)
Bases:
object
- CURRENT_STATUSES = ('stable', 'current', 'supported')
- DEPRECATED_STATUSES = ('deprecated',)
- EXPERIMENTAL_STATUSES = ('experimental',)
- data_for(version, **kwargs)
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
- raw_version_data(allow_experimental=False, allow_deprecated=True, allow_unknown=False)
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.
- url_for(version, **kwargs)
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.
- version_data(reverse=False, **kwargs)
Get normalized version data.
Return version data in a structured way.
- version_string_data(reverse=False, **kwargs)
Get normalized version data with versions as strings.
Return version data in a structured way.
- versioned_data_for(url=None, min_version=None, max_version=None, **kwargs)
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
- versioned_url_for(min_version=None, max_version=None, **kwargs)
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
- class keystoneauth1.discover.EndpointData(catalog_url=None, service_url=None, service_type=None, service_name=None, service_id=None, region_name=None, interface=None, endpoint_id=None, raw_endpoint=None, api_version=None, major_version=None, min_microversion=None, max_microversion=None, next_min_version=None, not_before=None, status=None)
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.
- get_all_version_string_data(session, project_id=None)
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, allow=None, cache=None, project_id=None)
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.
- get_versioned_data(session, allow=None, cache=None, allow_version_hack=True, project_id=None, discover_versions=True, min_version=None, max_version=None)
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
- class keystoneauth1.discover.Status
Bases:
object
- CURRENT = 'CURRENT'
- DEPRECATED = 'DEPRECATED'
- EXPERIMENTAL = 'EXPERIMENTAL'
- KNOWN = ('CURRENT', 'SUPPORTED', 'DEPRECATED', 'EXPERIMENTAL')
- SUPPORTED = 'SUPPORTED'
- UNKNOWN = 'UNKNOWN'
- classmethod normalize(raw_status)
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’.
- class keystoneauth1.discover.VersionData(version, url, collection=None, max_microversion=None, min_microversion=None, next_min_version=None, not_before=None, status='CURRENT', raw_status=None)
Bases:
dict
Normalized Version Data about an endpoint.
- property collection
The URL for the discovery document.
May be None.
- property max_microversion
The maximum microversion supported by the endpoint.
May be None.
- property min_microversion
The minimum microversion supported by the endpoint.
May be None.
- property raw_status
The status as provided by the server.
- property status
A canonicalized version of the status.
Valid values are CURRENT, SUPPORTED, DEPRECATED and EXPERIMENTAL.
- property url
The url for the endpoint.
- property version
The normalized version of the endpoint.
- keystoneauth1.discover.add_catalog_discover_hack(service_type, old, new)
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.
- keystoneauth1.discover.get_discovery(session, url, cache=None, authenticated=False)
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, url, authenticated=None)
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.
- Returns
A list of dicts containing version information.
- Return type
- keystoneauth1.discover.normalize_version_number(version)
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.
- keystoneauth1.discover.version_between(min_version, max_version, candidate)
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, candidate)
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.
- keystoneauth1.discover.version_to_string(version)
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.