keystoneauth1.discover module

updated: 2022-09-23 07:24

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: dict

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.

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

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.

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=False, **kwargs)¶

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=False, **kwargs)¶

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)

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

dict

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

str

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’.

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

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.

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

list(dict)

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.

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)¶

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.

updated: 2022-09-23 07:24

Except where otherwise noted, this document is licensed under Creative Commons Attribution 3.0 License. See all OpenStack Legal Documents.