keystoneauth1 package

Subpackages

Submodules

keystoneauth1.adapter module

class keystoneauth1.adapter.Adapter(session, service_type=None, service_name=None, interface=None, region_name=None, endpoint_override=None, version=None, auth=None, user_agent=None, connect_retries=None, logger=None, allow=None, additional_headers=None, client_name=None, client_version=None, allow_version_hack=None, global_request_id=None, min_version=None, max_version=None, default_microversion=None, status_code_retries=None, retriable_status_codes=None, raise_exc=None, rate_limit=None, concurrency=None, connect_retry_delay=None, status_code_retry_delay=None)

Bases: object

An instance of a session with local variables.

A session is a global object that is shared around amongst many clients. It therefore contains state that is relevant to everyone. There is a lot of state such as the service type and region_name that are only relevant to a particular client that is using the session. An adapter provides a wrapper of client local data around the global session object.

version, min_version, max_version and default_microversion can all be given either as a string or a tuple.

Parameters

  • session (keystoneauth1.session.Session) – The session object to wrap.

  • service_type (str) – The default service_type for URL discovery.

  • service_name (str) – The default service_name for URL discovery.

  • interface (str) – The default interface for URL discovery.

  • region_name (str) – The default region_name for URL discovery.

  • endpoint_override (str) – Always use this endpoint URL for requests for this client.

  • version – The minimum version restricted to a given Major API. Mutually exclusive with min_version and max_version. (optional)

  • auth (keystoneauth1.plugin.BaseAuthPlugin) – An auth plugin to use instead of the session one.

  • user_agent (str) – The User-Agent string to set.

  • connect_retries (int) – The maximum number of retries that should be attempted for connection errors. Default None - use session default which is don’t retry.

  • logger (logging.Logger) – A logging object to use for requests that pass through this adapter.

  • allow (dict) – Extra filters to pass when discovering API versions. (optional)

  • additional_headers (dict) – Additional headers that should be attached to every request passing through the adapter. Headers of the same name specified per request will take priority.

  • client_name (str) – The name of the client that created the adapter. This will be used to create the user_agent.

  • client_version (str) – The version of the client that created the adapter. This will be used to create the user_agent.

  • allow_version_hack (bool) – Allow keystoneauth to hack up catalog URLS to support older schemes. (optional, default True)

  • global_request_id (str) – A global_request_id (in the form of req-$uuid) that will be passed on all requests. Enables cross project request id tracking.

  • min_version – The minimum major version of a given API, intended to be used as the lower bound of a range with max_version. Mutually exclusive with version. If min_version is given with no max_version it is as if max version is ‘latest’. (optional)

  • max_version – The maximum major version of a given API, intended to be used as the upper bound of a range with min_version. Mutually exclusive with version. (optional)

  • default_microversion – The default microversion value to send with API requests. While microversions are a per-request feature, a user may know they want to default to sending a specific value. (optional)

  • status_code_retries (int) – The maximum number of retries that should be attempted for retriable HTTP status codes (optional, defaults to 0 - never retry).

  • retriable_status_codes (list) – List of HTTP status codes that should be retried (optional, defaults to HTTP 503, has no effect when status_code_retries is 0).

  • raise_exc (bool) – If True, requests returning failing HTTP responses will raise an exception; if False, the response is returned. This can be overridden on a per-request basis via the kwarg of the same name.

  • rate_limit (float) – A client-side rate limit to impose on requests made through this adapter in requests per second. For instance, a rate_limit of 2 means to allow no more than 2 requests per second, and a rate_limit of 0.5 means to allow no more than 1 request every two seconds. (optional, defaults to None, which means no rate limiting will be applied).

  • concurrency (int) – How many simultaneous http requests this Adapter can be used for. (optional, defaults to None, which means no limit).

  • connect_retry_delay (float) – Delay (in seconds) between two connect retries (if enabled). By default exponential retry starting with 0.5 seconds up to a maximum of 60 seconds is used.

  • status_code_retry_delay (float) – Delay (in seconds) between two status code retries (if enabled). By default exponential retry starting with 0.5 seconds up to a maximum of 60 seconds is used.

client_name = None
client_version = None
delete(url, **kwargs)
get(url, **kwargs)
get_all_version_data(interface='public', region_name=None)

Get data about all versions of a service.

Parameters

  • interface – Type of endpoint to get version data for. Can be a single value or a list of values. A value of None indicates that all interfaces should be queried. (optional, defaults to public)

  • region_name (string) – Region of endpoints to get version data for. A valueof None indicates that all regions should be queried. (optional, defaults to None)

Returns

A dictionary keyed by region_name with values containing dictionaries keyed by interface with values being a list of VersionData.

get_api_major_version(auth=None, **kwargs)

Get the major API version as provided by the auth plugin.

Parameters

auth (keystoneauth1.plugin.BaseAuthPlugin) – The auth plugin to use for token. Overrides the plugin on the session. (optional)

Raises

keystoneauth1.exceptions.auth_plugins.MissingAuthPlugin – if a plugin is not available.

Returns

The major version of the API of the service discovered.

Return type

tuple or None

get_endpoint(auth=None, **kwargs)

Get an endpoint as provided by the auth plugin.

Parameters

auth (keystoneauth1.plugin.BaseAuthPlugin) – The auth plugin to use for token. Overrides the plugin on the session. (optional)

Raises

keystoneauth1.exceptions.auth_plugins.MissingAuthPlugin – if a plugin is not available.

Returns

An endpoint if available or None.

Return type

str

get_endpoint_data(auth=None)

Get the endpoint data for this Adapter’s endpoint.

Parameters

auth (keystoneauth1.plugin.BaseAuthPlugin) – The auth plugin to use for token. Overrides the plugin on the session. (optional)

Raises
Returns

Endpoint data if available or None.

Return type

keystoneauth1.discover.EndpointData

get_project_id(auth=None)

Return the authenticated project_id as provided by the auth plugin.

Parameters

auth (keystoneauth1.plugin.BaseAuthPlugin) – The auth plugin to use for token. Overrides the plugin on the session. (optional)

Raises
Returns

Current project_id or None if not supported by plugin.

Return type

str

get_token(auth=None)

Return a token as provided by the auth plugin.

Parameters

auth (keystoneauth1.plugin.BaseAuthPlugin) – The auth plugin to use for token. Overrides the plugin on the session. (optional)

Raises

keystoneauth1.exceptions.auth.AuthorizationFailure – if a new token fetch fails.

Returns

A valid token.

Return type

str

get_user_id(auth=None)

Return the authenticated user_id as provided by the auth plugin.

Parameters

auth (keystoneauth1.plugin.BaseAuthPlugin) – The auth plugin to use for token. Overrides the plugin on the session. (optional)

Raises
Returns

Current user_id or None if not supported by plugin.

Return type

str

head(url, **kwargs)
invalidate(auth=None)

Invalidate an authentication plugin.

patch(url, **kwargs)
post(url, **kwargs)
put(url, **kwargs)
classmethod register_argparse_arguments(parser, service_type=None)

Attach arguments to a given argparse Parser for Adapters.

Parameters

  • parser (argparse.ArgumentParser) – The argparse parser to attach options to.

  • service_type (str) – Default service_type value. (optional)

classmethod register_service_argparse_arguments(parser, service_type)

Attach arguments to a given argparse Parser for Adapters.

Parameters

  • parser (argparse.ArgumentParser) – The argparse parser to attach options to.

  • service_type (str) – Name of a service to generate additional arguments for.

request(url, method, **kwargs)
class keystoneauth1.adapter.LegacyJsonAdapter(session, service_type=None, service_name=None, interface=None, region_name=None, endpoint_override=None, version=None, auth=None, user_agent=None, connect_retries=None, logger=None, allow=None, additional_headers=None, client_name=None, client_version=None, allow_version_hack=None, global_request_id=None, min_version=None, max_version=None, default_microversion=None, status_code_retries=None, retriable_status_codes=None, raise_exc=None, rate_limit=None, concurrency=None, connect_retry_delay=None, status_code_retry_delay=None)

Bases: keystoneauth1.adapter.Adapter

Make something that looks like an old HTTPClient.

A common case when using an adapter is that we want an interface similar to the HTTPClients of old which returned the body as JSON as well.

You probably don’t want this if you are starting from scratch.

request(*args, **kwargs)
keystoneauth1.adapter.register_adapter_argparse_arguments(*args, **kwargs)
keystoneauth1.adapter.register_service_adapter_argparse_arguments(*args, **kwargs)

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

keystoneauth1.noauth module

class keystoneauth1.noauth.NoAuth(endpoint=None)

Bases: keystoneauth1.plugin.BaseAuthPlugin

A provider that will always use no auth.

This is useful to unify session/adapter loading for services that might be deployed in standalone/noauth mode.

get_endpoint(session, **kwargs)

Return the supplied endpoint.

Using this plugin the same endpoint is returned regardless of the parameters passed to the plugin. endpoint_override overrides the endpoint specified when constructing the plugin.

get_token(session, **kwargs)

Obtain a token.

How the token is obtained is up to the plugin. If it is still valid it may be re-used, retrieved from cache or invoke an authentication request against a server.

There are no required kwargs. They are passed directly to the auth plugin and they are implementation specific.

Returning None will indicate that no token was able to be retrieved.

This function is misplaced as it should only be required for auth plugins that use the ‘X-Auth-Token’ header. However due to the way plugins evolved this method is required and often called to trigger an authentication request on a new plugin.

When implementing a new plugin it is advised that you implement this method, however if you don’t require the ‘X-Auth-Token’ header override the get_headers method instead.

Parameters

session (keystoneauth1.session.Session) – A session object so the plugin can make HTTP calls.

Returns

A token to use.

Return type

string

keystoneauth1.plugin module

class keystoneauth1.plugin.BaseAuthPlugin

Bases: object

The basic structure of an authentication plugin.

Note

See Authentication Plugins for a description of plugins provided by this library.

get_api_major_version(session, endpoint_override=None, **kwargs)

Get the major API version from the endpoint.

Parameters

  • session (keystoneauth1.session.Session) – A session object that can be used for communication.

  • endpoint_override (str) – URL to use for version discovery.

  • kwargs – Ignored.

Raises

keystoneauth1.exceptions.http.HttpError – An error from an invalid HTTP response.

Returns

Valid EndpointData or None if not available.

Return type

keystoneauth1.discover.EndpointData or None

get_auth_state()

Retrieve the current authentication state for the plugin.

Retrieve any internal state that represents the authenticated plugin.

This should not fetch any new data if it is not present.

Raises

NotImplementedError – if the plugin does not support this feature.

Returns

raw python data (which can be JSON serialized) that can be moved into another plugin (of the same type) to have the same authenticated state.

Return type

object or None if unauthenticated.

get_cache_id()

Fetch an identifier that uniquely identifies the auth options.

The returned identifier need not be decomposable or otherwise provide anyway to recreate the plugin. It should not contain sensitive data in plaintext.

This string MUST change if any of the parameters that are used to uniquely identity this plugin change.

If get_cache_id returns a str value suggesting that caching is supported then get_auth_cache and set_auth_cache must also be implemented.

Returns

A unique string for the set of options

Return type

str or None if this is unsupported or unavailable.

get_connection_params(session, **kwargs)

Return any additional connection parameters required for the plugin.

Parameters

session (keystoneauth1.session.Session) – The session object that the auth_plugin belongs to.

Returns

Headers that are set to authenticate a message or None for failure. Note that when checking this value that the empty dict is a valid, non-failure response.

Return type

dict

get_endpoint(session, **kwargs)

Return an endpoint for the client.

There are no required keyword arguments to get_endpoint as a plugin implementation should use best effort with the information available to determine the endpoint. However there are certain standard options that will be generated by the clients and should be used by plugins:

  • service_type: what sort of service is required.

  • service_name: the name of the service in the catalog.

  • interface: what visibility the endpoint should have.

  • region_name: the region the endpoint exists in.

Parameters

session (keystoneauth1.session.Session) – The session object that the auth_plugin belongs to.

Returns

The base URL that will be used to talk to the required service or None if not available.

Return type

string

get_endpoint_data(session, endpoint_override=None, discover_versions=True, **kwargs)

Return a valid endpoint data for a the service.

Parameters

  • session (keystoneauth1.session.Session) – A session object that can be used for communication.

  • endpoint_override (str) – URL to use for version discovery.

  • discover_versions (bool) – Whether to get version metadata from the version discovery document even if it major api version info can be inferred from the url. (optional, defaults to True)

  • kwargs – Ignored.

Raises

keystoneauth1.exceptions.http.HttpError – An error from an invalid HTTP response.

Returns

Valid EndpointData or None if not available.

Return type

keystoneauth1.discover.EndpointData or None

get_headers(session, **kwargs)

Fetch authentication headers for message.

This is a more generalized replacement of the older get_token to allow plugins to specify different or additional authentication headers to the OpenStack standard ‘X-Auth-Token’ header.

How the authentication headers are obtained is up to the plugin. If the headers are still valid they may be re-used, retrieved from cache or the plugin may invoke an authentication request against a server.

The default implementation of get_headers calls the get_token method to enable older style plugins to continue functioning unchanged. Subclasses should feel free to completely override this function to provide the headers that they want.

There are no required kwargs. They are passed directly to the auth plugin and they are implementation specific.

Returning None will indicate that no token was able to be retrieved and that authorization was a failure. Adding no authentication data can be achieved by returning an empty dictionary.

Parameters

session (keystoneauth1.session.Session) – The session object that the auth_plugin belongs to.

Returns

Headers that are set to authenticate a message or None for failure. Note that when checking this value that the empty dict is a valid, non-failure response.

Return type

dict

get_project_id(session, **kwargs)

Return the project id that we are authenticated to.

Wherever possible the project id should be inferred from the token however there are certain URLs and other places that require access to the currently authenticated project id.

Parameters

session (keystoneauth1.session.Session) – A session object so the plugin can make HTTP calls.

Returns

A project identifier or None if one is not available.

Return type

str

get_sp_auth_url(session, sp_id, **kwargs)

Return auth_url from the Service Provider object.

This url is used for obtaining unscoped federated token from remote cloud.

Parameters

sp_id (string) – ID of the Service Provider to be queried.

Returns

A Service Provider auth_url or None if one is not available.

Return type

str

get_sp_url(session, sp_id, **kwargs)

Return sp_url from the Service Provider object.

This url is used for passing SAML2 assertion to the remote cloud.

Parameters

sp_id (str) – ID of the Service Provider to be queried.

Returns

A Service Provider sp_url or None if one is not available.

Return type

str

get_token(session, **kwargs)

Obtain a token.

How the token is obtained is up to the plugin. If it is still valid it may be re-used, retrieved from cache or invoke an authentication request against a server.

There are no required kwargs. They are passed directly to the auth plugin and they are implementation specific.

Returning None will indicate that no token was able to be retrieved.

This function is misplaced as it should only be required for auth plugins that use the ‘X-Auth-Token’ header. However due to the way plugins evolved this method is required and often called to trigger an authentication request on a new plugin.

When implementing a new plugin it is advised that you implement this method, however if you don’t require the ‘X-Auth-Token’ header override the get_headers method instead.

Parameters

session (keystoneauth1.session.Session) – A session object so the plugin can make HTTP calls.

Returns

A token to use.

Return type

string

get_user_id(session, **kwargs)

Return a unique user identifier of the plugin.

Wherever possible the user id should be inferred from the token however there are certain URLs and other places that require access to the currently authenticated user id.

Parameters

session (keystoneauth1.session.Session) – A session object so the plugin can make HTTP calls.

Returns

A user identifier or None if one is not available.

Return type

str

invalidate()

Invalidate the current authentication data.

This should result in fetching a new token on next call.

A plugin may be invalidated if an Unauthorized HTTP response is returned to indicate that the token may have been revoked or is otherwise now invalid.

Returns

True if there was something that the plugin did to invalidate. This means that it makes sense to try again. If nothing happens returns False to indicate give up.

Return type

bool

set_auth_state(data)

Install existing authentication state for a plugin.

Take the output of get_auth_state and install that authentication state into the current authentication plugin.

Raises

NotImplementedError – if the plugin does not support this feature.

keystoneauth1.service_token module

class keystoneauth1.service_token.ServiceTokenAuthWrapper(user_auth, service_auth)

Bases: keystoneauth1.plugin.BaseAuthPlugin

get_connection_params(*args, **kwargs)

Return any additional connection parameters required for the plugin.

Parameters

session (keystoneauth1.session.Session) – The session object that the auth_plugin belongs to.

Returns

Headers that are set to authenticate a message or None for failure. Note that when checking this value that the empty dict is a valid, non-failure response.

Return type

dict

get_endpoint(*args, **kwargs)

Return an endpoint for the client.

There are no required keyword arguments to get_endpoint as a plugin implementation should use best effort with the information available to determine the endpoint. However there are certain standard options that will be generated by the clients and should be used by plugins:

  • service_type: what sort of service is required.

  • service_name: the name of the service in the catalog.

  • interface: what visibility the endpoint should have.

  • region_name: the region the endpoint exists in.

Parameters

session (keystoneauth1.session.Session) – The session object that the auth_plugin belongs to.

Returns

The base URL that will be used to talk to the required service or None if not available.

Return type

string

get_headers(session, **kwargs)

Fetch authentication headers for message.

This is a more generalized replacement of the older get_token to allow plugins to specify different or additional authentication headers to the OpenStack standard ‘X-Auth-Token’ header.

How the authentication headers are obtained is up to the plugin. If the headers are still valid they may be re-used, retrieved from cache or the plugin may invoke an authentication request against a server.

The default implementation of get_headers calls the get_token method to enable older style plugins to continue functioning unchanged. Subclasses should feel free to completely override this function to provide the headers that they want.

There are no required kwargs. They are passed directly to the auth plugin and they are implementation specific.

Returning None will indicate that no token was able to be retrieved and that authorization was a failure. Adding no authentication data can be achieved by returning an empty dictionary.

Parameters

session (keystoneauth1.session.Session) – The session object that the auth_plugin belongs to.

Returns

Headers that are set to authenticate a message or None for failure. Note that when checking this value that the empty dict is a valid, non-failure response.

Return type

dict

get_project_id(*args, **kwargs)

Return the project id that we are authenticated to.

Wherever possible the project id should be inferred from the token however there are certain URLs and other places that require access to the currently authenticated project id.

Parameters

session (keystoneauth1.session.Session) – A session object so the plugin can make HTTP calls.

Returns

A project identifier or None if one is not available.

Return type

str

get_sp_auth_url(*args, **kwargs)

Return auth_url from the Service Provider object.

This url is used for obtaining unscoped federated token from remote cloud.

Parameters

sp_id (string) – ID of the Service Provider to be queried.

Returns

A Service Provider auth_url or None if one is not available.

Return type

str

get_sp_url(*args, **kwargs)

Return sp_url from the Service Provider object.

This url is used for passing SAML2 assertion to the remote cloud.

Parameters

sp_id (str) – ID of the Service Provider to be queried.

Returns

A Service Provider sp_url or None if one is not available.

Return type

str

get_token(*args, **kwargs)

Obtain a token.

How the token is obtained is up to the plugin. If it is still valid it may be re-used, retrieved from cache or invoke an authentication request against a server.

There are no required kwargs. They are passed directly to the auth plugin and they are implementation specific.

Returning None will indicate that no token was able to be retrieved.

This function is misplaced as it should only be required for auth plugins that use the ‘X-Auth-Token’ header. However due to the way plugins evolved this method is required and often called to trigger an authentication request on a new plugin.

When implementing a new plugin it is advised that you implement this method, however if you don’t require the ‘X-Auth-Token’ header override the get_headers method instead.

Parameters

session (keystoneauth1.session.Session) – A session object so the plugin can make HTTP calls.

Returns

A token to use.

Return type

string

get_user_id(*args, **kwargs)

Return a unique user identifier of the plugin.

Wherever possible the user id should be inferred from the token however there are certain URLs and other places that require access to the currently authenticated user id.

Parameters

session (keystoneauth1.session.Session) – A session object so the plugin can make HTTP calls.

Returns

A user identifier or None if one is not available.

Return type

str

invalidate()

Invalidate the current authentication data.

This should result in fetching a new token on next call.

A plugin may be invalidated if an Unauthorized HTTP response is returned to indicate that the token may have been revoked or is otherwise now invalid.

Returns

True if there was something that the plugin did to invalidate. This means that it makes sense to try again. If nothing happens returns False to indicate give up.

Return type

bool

keystoneauth1.session module

class keystoneauth1.session.NoOpSemaphore

Bases: object

Empty context manager for use as a default semaphore.

class keystoneauth1.session.RequestTiming(method, url, elapsed)

Bases: object

Contains timing information for an HTTP interaction.

elapsed = None

Elapsed time information

method = None

HTTP method used for the call (GET, POST, etc)

url = None

URL against which the call was made

class keystoneauth1.session.Session(auth=None, session=None, original_ip=None, verify=True, cert=None, timeout=None, user_agent=None, redirect=30, additional_headers=None, app_name=None, app_version=None, additional_user_agent=None, discovery_cache=None, split_loggers=None, collect_timing=False, rate_semaphore=None)

Bases: object

Maintains client communication state and common functionality.

As much as possible the parameters to this class reflect and are passed directly to the requests library.

Parameters

  • auth (keystoneauth1.plugin.BaseAuthPlugin) – An authentication plugin to authenticate the session with. (optional, defaults to None)

  • session (requests.Session) – A requests session object that can be used for issuing requests. (optional)

  • original_ip (str) – The original IP of the requesting user which will be sent to identity service in a ‘Forwarded’ header. (optional)

  • verify – The verification arguments to pass to requests. These are of the same form as requests expects, so True or False to verify (or not) against system certificates or a path to a bundle or CA certs to check against or None for requests to attempt to locate and use certificates. (optional, defaults to True)

  • cert – A client certificate to pass to requests. These are of the same form as requests expects. Either a single filename containing both the certificate and key or a tuple containing the path to the certificate then a path to the key. (optional)

  • timeout (float) – A timeout to pass to requests. This should be a numerical value indicating some amount (or fraction) of seconds or 0 for no timeout. (optional, defaults to 0)

  • user_agent (str) – A User-Agent header string to use for the request. If not provided, a default of DEFAULT_USER_AGENT is used, which contains the keystoneauth1 version as well as those of the requests library and which Python is being used. When a non-None value is passed, it will be prepended to the default.

  • redirect (int/bool) – Controls the maximum number of redirections that can be followed by a request. Either an integer for a specific count or True/False for forever/never. (optional, default to 30)

  • additional_headers (dict) – Additional headers that should be attached to every request passing through the session. Headers of the same name specified per request will take priority.

  • app_name (str) – The name of the application that is creating the session. This will be used to create the user_agent.

  • app_version (str) – The version of the application creating the session. This will be used to create the user_agent.

  • additional_user_agent (list) – A list of tuple of name, version that will be added to the user agent. This can be used by libraries that are part of the communication process.

  • discovery_cache (dict) – A dict to be used for caching of discovery information. This is normally managed transparently, but if the user wants to share a single cache across multiple sessions that do not share an auth plugin, it can be provided here. (optional, defaults to None which means automatically manage)

  • split_loggers (bool) – Split the logging of requests across multiple loggers instead of just one. Defaults to False.

  • collect_timing (bool) – Whether or not to collect per-method timing information for each API call. (optional, defaults to False)

  • rate_semaphore – Semaphore to be used to control concurrency and rate limiting of requests. (optional, defaults to no concurrency or rate control)

property adapters
delete(url, **kwargs)

Perform a DELETE request.

This calls request() with method set to DELETE.

get(url, **kwargs)

Perform a GET request.

This calls request() with method set to GET.

get_all_version_data(auth=None, interface='public', region_name=None, service_type=None, **kwargs)

Get version data for all services in the catalog.

Parameters

  • auth (keystoneauth1.plugin.BaseAuthPlugin) – The auth plugin to use for token. Overrides the plugin on the session. (optional)

  • interface – Type of endpoint to get version data for. Can be a single value or a list of values. A value of None indicates that all interfaces should be queried. (optional, defaults to public)

  • region_name (string) – Region of endpoints to get version data for. A valueof None indicates that all regions should be queried. (optional, defaults to None)

  • service_type (string) – Limit the version data to a single service. (optional, defaults to None)

Returns

A dictionary keyed by region_name with values containing dictionaries keyed by interface with values being a list of ~keystoneauth1.discover.VersionData.

get_api_major_version(auth=None, **kwargs)

Get the major API version as provided by the auth plugin.

Parameters

auth (keystoneauth1.plugin.BaseAuthPlugin) – The auth plugin to use for token. Overrides the plugin on the session. (optional)

Raises

keystoneauth1.exceptions.auth_plugins.MissingAuthPlugin – if a plugin is not available.

Returns

The major version of the API of the service discovered.

Return type

tuple or None

get_auth_connection_params(auth=None, **kwargs)

Return auth connection params as provided by the auth plugin.

An auth plugin may specify connection parameters to the request like providing a client certificate for communication.

We restrict the values that may be returned from this function to prevent an auth plugin overriding values unrelated to connection parmeters. The values that are currently accepted are:

  • cert: a path to a client certificate, or tuple of client certificate and key pair that are used with this request.

  • verify: a boolean value to indicate verifying SSL certificates against the system CAs or a path to a CA file to verify with.

These values are passed to the requests library and further information on accepted values may be found there.

Parameters

auth (keystoneauth1.plugin.BaseAuthPlugin) – The auth plugin to use for tokens. Overrides the plugin on the session. (optional)

Raises
Returns

Authentication headers or None for failure.

Return type

dict

get_auth_headers(auth=None, **kwargs)

Return auth headers as provided by the auth plugin.

Parameters

auth (keystoneauth1.plugin.BaseAuthPlugin) – The auth plugin to use for token. Overrides the plugin on the session. (optional)

Raises
Returns

Authentication headers or None for failure.

Return type

dict

get_endpoint(auth=None, **kwargs)

Get an endpoint as provided by the auth plugin.

Parameters

auth (keystoneauth1.plugin.BaseAuthPlugin) – The auth plugin to use for token. Overrides the plugin on the session. (optional)

Raises

keystoneauth1.exceptions.auth_plugins.MissingAuthPlugin – if a plugin is not available.

Returns

An endpoint if available or None.

Return type

string

get_endpoint_data(auth=None, **kwargs)

Get endpoint data as provided by the auth plugin.

Parameters

auth (keystoneauth1.plugin.BaseAuthPlugin) – The auth plugin to use for token. Overrides the plugin on the session. (optional)

Raises
Returns

Endpoint data if available or None.

Return type

keystoneauth1.discover.EndpointData

get_project_id(auth=None)

Return the authenticated project_id as provided by the auth plugin.

Parameters

auth (keystoneauth1.plugin.BaseAuthPlugin) – The auth plugin to use for token. Overrides the plugin on the session. (optional)

Raises
Returns

Current project_id or None if not supported by plugin.

Return type

str

get_timings()

Return collected API timing information.

Returns

List of RequestTiming objects.

get_token(auth=None)

Return a token as provided by the auth plugin.

Parameters

auth (keystoneauth1.plugin.BaseAuthPlugin) – The auth plugin to use for token. Overrides the plugin on the session. (optional)

Raises

Warning

DEPRECATED: This assumes that the only header that is used to authenticate a message is X-Auth-Token. This may not be correct. Use get_auth_headers() instead.

Returns

A valid token.

Return type

string

get_user_id(auth=None)

Return the authenticated user_id as provided by the auth plugin.

Parameters

auth (keystoneauth1.plugin.BaseAuthPlugin) – The auth plugin to use for token. Overrides the plugin on the session. (optional)

Raises
Returns

Current user_id or None if not supported by plugin.

Return type

str

head(url, **kwargs)

Perform a HEAD request.

This calls request() with method set to HEAD.

invalidate(auth=None)

Invalidate an authentication plugin.

Parameters

auth (keystoneauth1.plugin.BaseAuthPlugin) – The auth plugin to invalidate. Overrides the plugin on the session. (optional)

mount(scheme, adapter)
patch(url, **kwargs)

Perform a PATCH request.

This calls request() with method set to PATCH.

post(url, **kwargs)

Perform a POST request.

This calls request() with method set to POST.

put(url, **kwargs)

Perform a PUT request.

This calls request() with method set to PUT.

request(url, method, json=None, original_ip=None, user_agent=None, redirect=None, authenticated=None, endpoint_filter=None, auth=None, requests_auth=None, raise_exc=True, allow_reauth=True, log=True, endpoint_override=None, connect_retries=0, logger=None, allow=None, client_name=None, client_version=None, microversion=None, microversion_service_type=None, status_code_retries=0, retriable_status_codes=None, rate_semaphore=None, global_request_id=None, connect_retry_delay=None, status_code_retry_delay=None, **kwargs)

Send an HTTP request with the specified characteristics.

Wrapper around requests.Session.request to handle tasks such as setting headers, JSON encoding/decoding, and error handling.

Arguments that are not handled are passed through to the requests library.

Parameters

  • url (str) – Path or fully qualified URL of HTTP request. If only a path is provided then endpoint_filter must also be provided such that the base URL can be determined. If a fully qualified URL is provided then endpoint_filter will be ignored.

  • method (str) – The http method to use. (e.g. ‘GET’, ‘POST’)

  • original_ip (str) – Mark this request as forwarded for this ip. (optional)

  • headers (dict) – Headers to be included in the request. (optional)

  • json – Some data to be represented as JSON. (optional)

  • user_agent (str) – A user_agent to use for the request. If present will override one present in headers. (optional)

  • redirect (int/bool) – the maximum number of redirections that can be followed by a request. Either an integer for a specific count or True/False for forever/never. (optional)

  • connect_retries (int) – the maximum number of retries that should be attempted for connection errors. (optional, defaults to 0 - never retry).

  • authenticated (bool) – True if a token should be attached to this request, False if not or None for attach if an auth_plugin is available. (optional, defaults to None)

  • endpoint_filter (dict) – Data to be provided to an auth plugin with which it should be able to determine an endpoint to use for this request. If not provided then URL is expected to be a fully qualified URL. (optional)

  • endpoint_override (str) – The URL to use instead of looking up the endpoint in the auth plugin. This will be ignored if a fully qualified URL is provided but take priority over an endpoint_filter. This string may contain the values %(project_id)s and %(user_id)s to have those values replaced by the project_id/user_id of the current authentication. (optional)

  • auth (keystoneauth1.plugin.BaseAuthPlugin) – The auth plugin to use when authenticating this request. This will override the plugin that is attached to the session (if any). (optional)

  • requests_auth (requests.auth.AuthBase) – A requests library auth plugin that cannot be passed via kwarg because the auth kwarg collides with our own auth plugins. (optional)

  • raise_exc (bool) – If True then raise an appropriate exception for failed HTTP requests. If False then return the request object. (optional, default True)

  • allow_reauth (bool) – Allow fetching a new token and retrying the request on receiving a 401 Unauthorized response. (optional, default True)

  • log (bool) – If True then log the request and response data to the debug log. (optional, default True)

  • logger (logging.Logger) – The logger object to use to log request and responses. If not provided the keystoneauth1.session default logger will be used.

  • allow (dict) – Extra filters to pass when discovering API versions. (optional)

  • microversion – Microversion to send for this request. microversion can be given as a string or a tuple. (optional)

  • microversion_service_type (str) – The service_type to be sent in the microversion header, if a microversion is given. Defaults to the value of service_type from endpoint_filter if one exists. If endpoint_filter is not provided or does not have a service_type, microversion is given and microversion_service_type is not provided, an exception will be raised.

  • status_code_retries (int) – the maximum number of retries that should be attempted for retriable HTTP status codes (optional, defaults to 0 - never retry).

  • retriable_status_codes (list) – list of HTTP status codes that should be retried (optional, defaults to HTTP 503, has no effect when status_code_retries is 0).

  • rate_semaphore – Semaphore to be used to control concurrency and rate limiting of requests. (optional, defaults to no concurrency or rate control)

  • global_request_id – Value for the X-Openstack-Request-Id header.

  • connect_retry_delay (float) – Delay (in seconds) between two connect retries (if enabled). By default exponential retry starting with 0.5 seconds up to a maximum of 60 seconds is used.

  • status_code_retry_delay (float) – Delay (in seconds) between two status code retries (if enabled). By default exponential retry starting with 0.5 seconds up to a maximum of 60 seconds is used.

  • kwargs –

    any other parameter that can be passed to requests.Session.request() (such as headers). Except:

    • data will be overwritten by the data in the json param.

    • allow_redirects is ignored as redirects are handled by the session.

Raises

keystoneauth1.exceptions.base.ClientException – For connection failure, or to indicate an error response code.

Returns

The response to the request.

reset_timings()

Clear API timing information.

user_agent = None
class keystoneauth1.session.TCPKeepAliveAdapter(pool_connections=10, pool_maxsize=10, max_retries=0, pool_block=False)

Bases: requests.adapters.HTTPAdapter

The custom adapter used to set TCP Keep-Alive on all connections.

This Adapter also preserves the default behaviour of Requests which disables Nagle’s Algorithm. See also: https://blogs.msdn.com/b/windowsazurestorage/archive/2010/06/25/nagle-s-algorithm-is-not-friendly-towards-small-requests.aspx

init_poolmanager(*args, **kwargs)

Initializes a urllib3 PoolManager.

This method should not be called from user code, and is only exposed for use when subclassing the HTTPAdapter.

Parameters

  • connections – The number of urllib3 connection pools to cache.

  • maxsize – The maximum number of connections to save in the pool.

  • block – Block when no free connections are available.

  • pool_kwargs – Extra keyword arguments used to initialize the Pool Manager.

keystoneauth1.token_endpoint module

class keystoneauth1.token_endpoint.Token(endpoint, token)

Bases: keystoneauth1.plugin.BaseAuthPlugin

A provider that will always use the given token and endpoint.

This is really only useful for testing and in certain CLI cases where you have a known endpoint and admin token that you want to use.

get_auth_ref(session, **kwargs)

Return the authentication reference of an auth plugin.

Parameters

session (keystoneauth1.session.session) – A session object to be used for communication

get_endpoint(session, **kwargs)

Return the supplied endpoint.

Using this plugin the same endpoint is returned regardless of the parameters passed to the plugin.

get_endpoint_data(session, endpoint_override=None, discover_versions=True, **kwargs)

Return a valid endpoint data for a the service.

Parameters

  • session (keystoneauth1.session.Session) – A session object that can be used for communication.

  • endpoint_override (str) – URL to use for version discovery other than the endpoint stored in the plugin. (optional, defaults to None)

  • discover_versions (bool) – Whether to get version metadata from the version discovery document even if it major api version info can be inferred from the url. (optional, defaults to True)

  • kwargs – Ignored.

Raises

keystoneauth1.exceptions.http.HttpError – An error from an invalid HTTP response.

Returns

Valid EndpointData or None if not available.

Return type

keystoneauth1.discover.EndpointData or None

get_token(session)

Obtain a token.

How the token is obtained is up to the plugin. If it is still valid it may be re-used, retrieved from cache or invoke an authentication request against a server.

There are no required kwargs. They are passed directly to the auth plugin and they are implementation specific.

Returning None will indicate that no token was able to be retrieved.

This function is misplaced as it should only be required for auth plugins that use the ‘X-Auth-Token’ header. However due to the way plugins evolved this method is required and often called to trigger an authentication request on a new plugin.

When implementing a new plugin it is advised that you implement this method, however if you don’t require the ‘X-Auth-Token’ header override the get_headers method instead.

Parameters

session (keystoneauth1.session.Session) – A session object so the plugin can make HTTP calls.

Returns

A token to use.

Return type

string

Module contents