keystoneclient package

Subpackages

Submodules

keystoneclient.access module

class keystoneclient.access.AccessInfo(*args, **kwargs)

Bases: dict

Encapsulates a raw authentication token from keystone.

Provides helper methods for extracting useful values from that token.

auth_token

Returns the token_id associated with the auth request, to be used in headers for authenticating OpenStack API requests.

Returns:str
auth_url

Returns a tuple of URLs from publicURL and adminURL for the service ‘identity’ from the service catalog associated with the authorization request. If the authentication request wasn’t scoped to a tenant (project), this property will return None.

DEPRECATED: this doesn’t correctly handle region name. You should fetch it from the service catalog yourself.

Returns:tuple of urls
domain_id

Returns the domain id associated with the authentication token.

Returns:str or None (if no domain associated with the token)
domain_name

Returns the domain name associated with the authentication token.

Returns:str or None (if no domain associated with the token)
domain_scoped

Returns true if the authorization token was scoped to a domain.

Returns:bool
expires

Returns the token expiration (as datetime object)

Returns:datetime
classmethod factory(resp=None, body=None, region_name=None, auth_token=None, **kwargs)

Create AccessInfo object given a successful auth response & body or a user-provided dict.

has_service_catalog()

Returns true if the authorization token has a service catalog.

Returns:boolean
is_federated

Returns true if federation was used to get the token.

Returns:boolean
classmethod is_valid(body, **kwargs)

Determines if processing v2 or v3 token given a successful auth body or a user-provided dict.

Returns:true if auth body matches implementing class
Return type:boolean
issued

Returns the token issue time (as datetime object)

Returns:datetime
management_url

Returns the first adminURL for ‘identity’ from the service catalog associated with the authorization request, or None if the authentication request wasn’t scoped to a tenant (project).

DEPRECATED: this doesn’t correctly handle region name. You should fetch it from the service catalog yourself.

Returns:tuple of urls
oauth_access_token_id

Return the access token ID if OAuth authentication used.

Returns:str or None.
oauth_consumer_id

Return the consumer ID if OAuth authentication used.

Returns:str or None.
project_domain_id

Returns the domain id of the project associated with the authentication request.

For v2, it returns ‘default’ if a project is scoped or None which may be different from the keystone configuration.

Returns:str
project_domain_name

Returns the domain name of the project associated with the authentication request.

For v2, it returns ‘Default’ if a project is scoped or None which may be different from the keystone configuration.

Returns:str
project_id

Returns the project ID associated with the authentication request, or None if the authentication request wasn’t scoped to a project.

Returns:str or None (if no project associated with the token)
project_name

Returns the project name associated with the authentication request.

Returns:str or None (if no project associated with the token)
project_scoped
Returns true if the authorization token was scoped to a tenant
(project).
Returns:bool
role_ids

Returns a list of role ids of the user associated with the authentication request.

Returns:a list of strings of role ids
role_names

Returns a list of role names of the user associated with the authentication request.

Returns:a list of strings of role names
scoped
Returns true if the authorization token was scoped to a tenant

(project), and contains a populated service catalog.

This is deprecated, use project_scoped instead.

Returns:bool
tenant_id

Synonym for project_id.

tenant_name

Synonym for project_name.

trust_id

Returns the trust id associated with the authentication token.

Returns:str or None (if no trust associated with the token)
trust_scoped

Returns true if the authorization token was scoped as delegated in a trust, via the OS-TRUST v3 extension.

Returns:bool
trustee_user_id

Returns the trustee user id associated with a trust.

Returns:str or None (if no trust associated with the token)
trustor_user_id

Returns the trustor user id associated with a trust.

Returns:str or None (if no trust associated with the token)
user_domain_id

Returns the domain id of the user associated with the authentication request.

For v2, it always returns ‘default’ which may be different from the Keystone configuration.

Returns:str
user_domain_name

Returns the domain name of the user associated with the authentication request.

For v2, it always returns ‘Default’ which may be different from the Keystone configuration.

Returns:str
user_id

Returns the user id associated with the authentication request.

Returns:str
username

Returns the username associated with the authentication request. Follows the pattern defined in the V2 API of first looking for ‘name’, returning that if available, and falling back to ‘username’ if name is unavailable.

Returns:str
version

Returns the version of the auth token from identity service.

Returns:str
will_expire_soon(stale_duration=None)

Determines if expiration is about to occur.

Returns:true if expiration is within the given duration
Return type:boolean
class keystoneclient.access.AccessInfoV2(*args, **kwargs)

Bases: keystoneclient.access.AccessInfo

An object for encapsulating a raw v2 auth token from identity service.

auth_token
auth_url
domain_id
domain_name
domain_scoped
expires
has_service_catalog()
is_federated
classmethod is_valid(body, **kwargs)
issued
management_url
oauth_access_token_id
oauth_consumer_id
project_domain_id
project_domain_name
project_id
project_name
project_scoped
role_ids
role_names
scoped
trust_id
trust_scoped
trustee_user_id
trustor_user_id
user_domain_id
user_domain_name
user_id
username
class keystoneclient.access.AccessInfoV3(token, *args, **kwargs)

Bases: keystoneclient.access.AccessInfo

An object for encapsulating a raw v3 auth token from identity service.

auth_url
domain_id
domain_name
domain_scoped
expires
has_service_catalog()
is_federated
classmethod is_valid(body, **kwargs)
issued
management_url
oauth_access_token_id
oauth_consumer_id
project_domain_id
project_domain_name
project_id
project_name
project_scoped
role_ids
role_names
scoped
trust_id
trust_scoped
trustee_user_id
trustor_user_id
user_domain_id
user_domain_name
user_id
username

keystoneclient.adapter module

class keystoneclient.adapter.Adapter(*args, **kwargs)

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.

Parameters:
  • session (keystoneclient.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 (tuple) – The version that this API targets.
  • auth (keystoneclient.auth.base.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.
delete(url, **kwargs)
get(url, **kwargs)
get_endpoint(auth=None, **kwargs)

Get an endpoint as provided by the auth plugin.

Parameters:auth (keystoneclient.auth.base.BaseAuthPlugin) – The auth plugin to use for token. Overrides the plugin on the session. (optional)
Raises keystoneclient.exceptions.MissingAuthPlugin:
 if a plugin is not available.
Returns:An endpoint if available or None.
Return type:string
get_project_id(auth=None)

Return the authenticated project_id as provided by the auth plugin.

Parameters:

auth (keystoneclient.auth.base.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:

string

get_token(auth=None)

Return a token as provided by the auth plugin.

Parameters:auth (keystoneclient.auth.base.BaseAuthPlugin) – The auth plugin to use for token. Overrides the plugin on the session. (optional)
Raises keystoneclient.exceptions.AuthorizationFailure:
 if a new token fetch fails.
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 (keystoneclient.auth.base.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:

string

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

Invalidate an authentication plugin.

patch(url, **kwargs)
post(url, **kwargs)
put(url, **kwargs)
request(url, method, **kwargs)
class keystoneclient.adapter.LegacyJsonAdapter(*args, **kwargs)

Bases: keystoneclient.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)

keystoneclient.base module

Base utilities to build API operation managers and objects on top of.

class keystoneclient.base.CrudManager(client)

Bases: keystoneclient.base.Manager

Base manager class for manipulating Keystone entities.

Children of this class are expected to define a collection_key and key.

  • collection_key: Usually a plural noun by convention (e.g. entities); used to refer collections in both URL’s (e.g. /v3/entities) and JSON objects containing a list of member resources (e.g. {‘entities’: [{}, {}, {}]}).
  • key: Usually a singular noun by convention (e.g. entity); used to refer to an individual member of the collection.
base_url = None
build_key_only_query(params_list)

Builds a query that does not include values, just keys.

The Identity API has some calls that define queries without values, this can not be accomplished by using urllib.parse.urlencode(). This method builds a query using only the keys.

build_url(dict_args_in_out=None)

Builds a resource URL for the given kwargs.

Given an example collection where collection_key = ‘entities’ and key = ‘entity’, the following URL’s could be generated.

By default, the URL will represent a collection of entities, e.g.:

/entities

If kwargs contains an entity_id, then the URL will represent a specific member, e.g.:

/entities/{entity_id}

If a base_url is provided, the generated URL will be appended to it.

collection_key = None
create(*args, **kwargs)
delete(*args, **kwargs)
find(*args, **kwargs)

Find a single item with attributes matching **kwargs.

get(*args, **kwargs)
head(*args, **kwargs)
key = None
list(*args, **kwargs)
put(*args, **kwargs)
update(*args, **kwargs)
class keystoneclient.base.Manager(client)

Bases: object

Basic manager type providing common operations.

Managers interact with a particular type of API (servers, flavors, images, etc.) and provide CRUD operations for them.

Parameters:client – instance of BaseClient descendant for HTTP requests
api

Deprecated. Use client instead.

resource_class = None
class keystoneclient.base.ManagerWithFind(client)

Bases: keystoneclient.base.Manager

Manager with additional find()/findall() methods.

find(**kwargs)

Find a single item with attributes matching **kwargs.

This isn’t very efficient: it loads the entire list then filters on the Python side.

findall(**kwargs)

Find all items with attributes matching **kwargs.

This isn’t very efficient: it loads the entire list then filters on the Python side.

list()
class keystoneclient.base.Resource(manager, info, loaded=False)

Bases: keystoneclient.openstack.common.apiclient.base.Resource

Base class for OpenStack resources (tenant, user, etc.).

This is pretty much just a bag for attributes.

delete()
keystoneclient.base.filter_kwargs(f)
keystoneclient.base.filter_none(**kwargs)

Remove any entries from a dictionary where the value is None.

keystoneclient.base.getid(obj)

Return id if argument is a Resource.

Abstracts the common pattern of allowing both an object or an object’s ID (UUID) as a parameter when dealing with relationships.

keystoneclient.baseclient module

class keystoneclient.baseclient.Client(session)

Bases: object

delete(url, **kwargs)
get(url, **kwargs)
head(url, **kwargs)
patch(url, **kwargs)
post(url, **kwargs)
put(url, **kwargs)
request(url, method, **kwargs)

keystoneclient.client module

keystoneclient.client.Client(version=None, unstable=False, session=None, **kwargs)

Factory function to create a new identity service client.

The returned client will be either a V3 or V2 client. Check the version using the version property or the instance’s class (with instanceof).

Parameters:
  • version (tuple) – The required version of the identity API. If specified the client will be selected such that the major version is equivalent and an endpoint provides at least the specified minor version. For example to specify the 3.1 API use (3, 1).
  • unstable (bool) – Accept endpoints not marked as ‘stable’. (optional)
  • session (keystoneclient.session.Session) – A session object to be used for communication. If one is not provided it will be constructed from the provided kwargs. (optional)
  • kwargs – Additional arguments are passed through to the client that is being created.
Returns:

New keystone client object.

Return type:

keystoneclient.v3.client.Client or keystoneclient.v2_0.client.Client

Raises:

keystoneclient.discover module

class keystoneclient.discover.Discover(*args, **kwargs)

Bases: keystoneclient._discover.Discover

A means to discover and create clients depending on the supported API versions on the server.

Querying the server is done on object creation and every subsequent method operates upon the data that was retrieved.

The connection parameters associated with this method are the same format and name as those used by a client (see keystoneclient.v2_0.client.Client and keystoneclient.v3.client.Client). If not overridden in subsequent methods they will also be what is passed to the constructed client.

In the event that auth_url and endpoint is provided then auth_url will be used in accordance with how the client operates.

Parameters:
  • session (keystoneclient.session.Session) – A session object that will be used for communication. Clients will also be constructed with this session.
  • auth_url (string) – Identity service endpoint for authorization. (optional)
  • endpoint (string) – A user-supplied endpoint URL for the identity service. (optional)
  • original_ip (string) – The original IP of the requesting user which will be sent to identity service in a ‘Forwarded’ header. (optional) DEPRECATED: use the session object. This is ignored if a session is provided.
  • debug (boolean) – Enables debug logging of all request and responses to the identity service. default False (optional) DEPRECATED: use the session object. This is ignored if a session is provided.
  • cacert (string) – Path to the Privacy Enhanced Mail (PEM) file which contains the trusted authority X.509 certificates needed to established SSL connection with the identity service. (optional) DEPRECATED: use the session object. This is ignored if a session is provided.
  • key (string) – Path to the Privacy Enhanced Mail (PEM) file which contains the unencrypted client private key needed to established two-way SSL connection with the identity service. (optional) DEPRECATED: use the session object. This is ignored if a session is provided.
  • cert (string) – Path to the Privacy Enhanced Mail (PEM) file which contains the corresponding X.509 client certificate needed to established two-way SSL connection with the identity service. (optional) DEPRECATED: use the session object. This is ignored if a session is provided.
  • insecure (boolean) – Does not perform X.509 certificate validation when establishing SSL connection with identity service. default: False (optional) DEPRECATED: use the session object. This is ignored if a session is provided.
  • authenticated (bool) – Should a token be used to perform the initial discovery operations. default: None (attach a token if an auth plugin is available).
available_versions(**kwargs)

Return a list of identity APIs available on the server and the data associated with them.

DEPRECATED: use raw_version_data()

Parameters:
  • unstable (bool) – Accept endpoints not marked ‘stable’. (optional) DEPRECTED. Equates to setting allow_experimental and allow_unknown to True.
  • allow_experimental (bool) – Allow experimental version endpoints.
  • allow_deprecated (bool) – Allow deprecated version endpoints.
  • allow_unknown (bool) – Allow endpoints with an unrecognised status.
Returns:

A List of dictionaries as presented by the server. Each dict will contain the version and the URL to use for the version. It is a direct representation of the layout presented by the identity API.

create_client(version=None, unstable=False, **kwargs)

Factory function to create a new identity service client.

Parameters:
  • version (tuple) – The required version of the identity API. If specified the client will be selected such that the major version is equivalent and an endpoint provides at least the specified minor version. For example to specify the 3.1 API use (3, 1). (optional)
  • unstable (bool) – Accept endpoints not marked ‘stable’. (optional)
  • kwargs – Additional arguments will override those provided to this object’s constructor.
Returns:

An instantiated identity client object.

Raises:
raw_version_data(unstable=False, **kwargs)

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:
  • unstable (bool) – (deprecated) equates to setting allow_experimental and allow_unknown.
  • 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

Example:

>>> from keystoneclient import discover
>>> disc = discover.Discovery(auth_url='http://localhost:5000')
>>> disc.raw_version_data()
    [{'id': 'v3.0',
        'links': [{'href': u'http://127.0.0.1:5000/v3/',
                   'rel': u'self'}],
      'media-types': [
          {'base': 'application/json',
           'type': 'application/vnd.openstack.identity-v3+json'},
          {'base': 'application/xml',
           'type': 'application/vnd.openstack.identity-v3+xml'}],
      'status': 'stable',
      'updated': '2013-03-06T00:00:00Z'},
     {'id': 'v2.0',
      'links': [{'href': u'http://127.0.0.1:5000/v2.0/',
                 'rel': u'self'},
                {'href': u'...',
                 'rel': u'describedby',
                 'type': u'application/pdf'}],
      'media-types': [
          {'base': 'application/json',
           'type': 'application/vnd.openstack.identity-v2.0+json'},
          {'base': 'application/xml',
           'type': 'application/vnd.openstack.identity-v2.0+xml'}],
      'status': 'stable',
      'updated': '2013-03-06T00:00:00Z'}]
keystoneclient.discover.add_catalog_discover_hack(service_type, old, new)

Adds 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.
keystoneclient.discover.available_versions(url, session=None, **kwargs)

Retrieve raw version data from a url.

keystoneclient.discover.normalize_version_number(version)

Turn a version representation into a tuple.

Takes a string, tuple or float which represent version formats we can handle and converts them into a (major, minor) version tuple that we can actually use for discovery.

e.g. ‘v3.3’ gives (3, 3)
3.1 gives (3, 1)
Parameters:version – Inputted version number to try and convert.
Returns:A usable version tuple
Return type:tuple
Raises TypeError:
 if the inputted version cannot be converted to tuple.
keystoneclient.discover.version_match(required, candidate)

Test that an available version is a suitable match for a 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

keystoneclient.exceptions module

Exception definitions.

exception keystoneclient.exceptions.AuthorizationFailure
exception keystoneclient.exceptions.ClientException
exception keystoneclient.exceptions.HttpError
exception keystoneclient.exceptions.ValidationError
exception keystoneclient.exceptions.Unauthorized
exception keystoneclient.exceptions.CMSError(output)

Bases: exceptions.Exception

Error reading the certificate.

exception keystoneclient.exceptions.CertificateConfigError(output)

Bases: exceptions.Exception

Error reading the certificate.

exception keystoneclient.exceptions.DiscoveryFailure

Bases: keystoneclient.openstack.common.apiclient.exceptions.ClientException

Discovery of client versions failed.

exception keystoneclient.exceptions.EmptyCatalog

Bases: keystoneclient.openstack.common.apiclient.exceptions.EndpointNotFound

The service catalog is empty.

exception keystoneclient.exceptions.InvalidResponse(response)

Bases: keystoneclient.openstack.common.apiclient.exceptions.ClientException

The response from the server is not valid for this request.

exception keystoneclient.exceptions.MethodNotImplemented

Bases: keystoneclient.openstack.common.apiclient.exceptions.ClientException

Method not implemented by the keystoneclient API.

exception keystoneclient.exceptions.MissingAuthPlugin

Bases: keystoneclient.openstack.common.apiclient.exceptions.ClientException

An authenticated request is required but no plugin available.

exception keystoneclient.exceptions.NoMatchingPlugin(name)

Bases: keystoneclient.openstack.common.apiclient.exceptions.ClientException

There were no auth plugins that could be created from the parameters provided.

Parameters:name (str) – The name of the plugin that was attempted to load.
name

The name of the plugin that was attempted to load.

exception keystoneclient.exceptions.SSLError

Bases: keystoneclient.openstack.common.apiclient.exceptions.ConnectionRefused

An SSL error occurred.

exception keystoneclient.exceptions.VersionNotAvailable

Bases: keystoneclient.exceptions.DiscoveryFailure

Discovery failed as the version you requested is not available.

keystoneclient.httpclient module

OpenStack Client interface. Handles the REST calls and responses.

class keystoneclient.httpclient.HTTPClient(*args, **kwargs)

Bases: keystoneclient.baseclient.Client, keystoneclient.auth.base.BaseAuthPlugin

HTTP client

Parameters:
  • user_id (string) – User ID for authentication. (optional)
  • username (string) – Username for authentication. (optional)
  • user_domain_id (string) – User’s domain ID for authentication. (optional)
  • user_domain_name (string) – User’s domain name for authentication. (optional)
  • password (string) – Password for authentication. (optional)
  • domain_id (string) – Domain ID for domain scoping. (optional)
  • domain_name (string) – Domain name for domain scoping. (optional)
  • project_id (string) – Project ID for project scoping. (optional)
  • project_name (string) – Project name for project scoping. (optional)
  • project_domain_id (string) – Project’s domain ID for project scoping. (optional)
  • project_domain_name (string) – Project’s domain name for project scoping. (optional)
  • auth_url (string) – Identity service endpoint for authorization.
  • region_name (string) – Name of a region to select when choosing an endpoint from the service catalog.
  • timeout (integer) – DEPRECATED: use session. (optional)
  • endpoint (string) – A user-supplied endpoint URL for the identity service. Lazy-authentication is possible for API service calls if endpoint is set at instantiation. (optional)
  • token (string) – Token for authentication. (optional)
  • cacert (string) – DEPRECATED: use session. (optional)
  • key (string) – DEPRECATED: use session. (optional)
  • cert (string) – DEPRECATED: use session. (optional)
  • insecure (boolean) – DEPRECATED: use session. (optional)
  • original_ip (string) – DEPRECATED: use session. (optional)
  • debug (boolean) – DEPRECATED: use logging configuration. (optional)
  • auth_ref (dict) – To allow for consumers of the client to manage their own caching strategy, you may initialize a client with a previously captured auth_reference (token). If there are keyword arguments passed that also exist in auth_ref, the value from the argument will take precedence.
  • use_keyring (boolean) – Enables caching auth_ref into keyring. default: False (optional)
  • force_new_token (boolean) – Keyring related parameter, forces request for new token. default: False (optional)
  • stale_duration (integer) – Gap in seconds to determine if token from keyring is about to expire. default: 30 (optional)
  • tenant_name (string) – Tenant name. (optional) The tenant_name keyword argument is deprecated, use project_name instead.
  • tenant_id (string) – Tenant id. (optional) The tenant_id keyword argument is deprecated, use project_id instead.
  • trust_id (string) – Trust ID for trust scoping. (optional)
  • session (keystoneclient.session.Session) – A Session object to be used for communicating with the identity service.
  • service_name (string) – The default service_name for URL discovery. default: None (optional)
  • interface (string) – The default interface for URL discovery. default: admin (optional)
  • endpoint_override (string) – Always use this endpoint URL for requests for this client. (optional)
  • auth (keystoneclient.auth.base.BaseAuthPlugin) – An auth plugin to use instead of the session one. (optional)
  • user_agent (string) – The User-Agent string to set. default: python-keystoneclient (optional)
  • 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. (optional)
auth_token
authenticate(*args, **kwargs)

Authenticate user.

Uses the data provided at instantiation to authenticate against the Identity server. This may use either a username and password or token for authentication. If a tenant name or id was provided then the resulting authenticated client will be scoped to that tenant and contain a service catalog of available endpoints.

With the v2.0 API, if a tenant name or ID is not provided, the authentication token returned will be ‘unscoped’ and limited in capabilities until a fully-scoped token is acquired.

With the v3 API, if a domain name or id was provided then the resulting authenticated client will be scoped to that domain. If a project name or ID is not provided, and the authenticating user has a default project configured, the authentication token returned will be ‘scoped’ to the default project. Otherwise, the authentication token returned will be ‘unscoped’ and limited in capabilities until a fully-scoped token is acquired.

With the v3 API, with the OS-TRUST extension enabled, the trust_id can be provided to allow project-specific role delegation between users

If successful, sets the self.auth_ref and self.auth_token with the returned token. If not already set, will also set self.management_url from the details provided in the token.

Returns:

True if authentication was successful.

Raises:

If keyring is used, token is retrieved from keyring instead. Authentication will only be necessary if any of the following conditions are met:

  • keyring is not used
  • if token is not found in keyring
  • if token retrieved from keyring is expired or about to expired (as determined by stale_duration)
  • if force_new_token is true
delete(url, **kwargs)

Perform an authenticate DELETE request.

This calls request() with method set to DELETE and an authentication token if one is available.

Warning

DEPRECATED: This function is no longer used. It was designed to be used by the managers and the managers now receive an adapter so this function is no longer on the standard request path.

deprecated_adapter_variables = {'region_name': None}
deprecated_session_variables = {'original_ip': None, 'cert': None, 'verify_cert': 'verify', 'timeout': None}
get(url, **kwargs)

Perform an authenticated GET request.

This calls request() with method set to GET and an authentication token if one is available.

Warning

DEPRECATED: This function is no longer used. It was designed to be used by the managers and the managers now receive an adapter so this function is no longer on the standard request path.

get_auth_ref_from_keyring(**kwargs)

Retrieve auth_ref from keyring.

If auth_ref is found in keyring, (keyring_key, auth_ref) is returned. Otherwise, (keyring_key, None) is returned.

Returns:(keyring_key, auth_ref) or (keyring_key, None)
Returns:or (None, None) if use_keyring is not set in the object
get_endpoint(session, interface=None, **kwargs)
get_project_id(session, **kwargs)
get_raw_token_from_identity_service(*args, **kwargs)

Authenticate against the Identity API and get a token.

Not implemented here because auth protocols should be API version-specific.

Expected to authenticate or validate an existing authentication reference already associated with the client. Invoking this call always makes a call to the Identity service.

Returns:(resp, body)
get_token(session, **kwargs)
get_user_id(session, **kwargs)
has_service_catalog()

Returns True if this client provides a service catalog.

head(url, **kwargs)

Perform an authenticated HEAD request.

This calls request() with method set to HEAD and an authentication token if one is available.

Warning

DEPRECATED: This function is no longer used. It was designed to be used by the managers and the managers now receive an adapter so this function is no longer on the standard request path.

management_url
patch(url, **kwargs)

Perform an authenticate PATCH request.

This calls request() with method set to PATCH and an authentication token if one is available.

Warning

DEPRECATED: This function is no longer used. It was designed to be used by the managers and the managers now receive an adapter so this function is no longer on the standard request path.

post(url, **kwargs)

Perform an authenticate POST request.

This calls request() with method set to POST and an authentication token if one is available.

Warning

DEPRECATED: This function is no longer used. It was designed to be used by the managers and the managers now receive an adapter so this function is no longer on the standard request path.

process_token(region_name=None)

Extract and process information from the new auth_ref.

And set the relevant authentication information.

put(url, **kwargs)

Perform an authenticate PUT request.

This calls request() with method set to PUT and an authentication token if one is available.

Warning

DEPRECATED: This function is no longer used. It was designed to be used by the managers and the managers now receive an adapter so this function is no longer on the standard request path.

request(*args, **kwargs)

Send an http request with the specified characteristics.

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

Warning

DEPRECATED: This function is no longer used. It was designed to be used only by the managers and the managers now receive an adapter so this function is no longer on the standard request path.

serialize(entity)
service_catalog

Returns this client’s service catalog.

store_auth_ref_into_keyring(keyring_key)

Store auth_ref into keyring.

tenant_id

Provide read-only backwards compatibility for tenant_id. This is deprecated, use project_id instead.

tenant_name

Provide read-only backwards compatibility for tenant_name. This is deprecated, use project_name instead.

version = None

keystoneclient.i18n module

oslo.i18n integration module.

See http://docs.openstack.org/developer/oslo.i18n/usage.html .

keystoneclient.service_catalog module

class keystoneclient.service_catalog.ServiceCatalog(region_name=None)

Bases: object

Helper methods for dealing with a Keystone Service Catalog.

classmethod factory(resource_dict, token=None, region_name=None)

Create ServiceCatalog object given an auth token.

get_data()

Get the raw catalog structure.

Get the version dependent catalog structure as it is presented within the resource.

Returns:list containing raw catalog data entries or None
get_endpoints(service_type=None, endpoint_type=None, region_name=None, service_name=None)

Fetch and filter endpoints for the specified service(s).

Returns endpoints for the specified service (or all) containing the specified type (or all) and region (or all) and service name.

If there is no name in the service catalog the service_name check will be skipped. This allows compatibility with services that existed before the name was available in the catalog.

get_token()

Fetch token details from service catalog.

Returns a dictionary containing the following:

- `id`: Token's ID
- `expires`: Token's expiration
- `user_id`: Authenticated user's ID
- `tenant_id`: Authorized project's ID
- `domain_id`: Authorized domain's ID
get_urls(*args, **kwargs)

Fetch endpoint urls from the service catalog.

Fetch the endpoints from the service catalog for a particular endpoint attribute. If no attribute is given, return the first endpoint of the specified type.

Parameters:
  • attr (string) – Endpoint attribute name.
  • filter_value (string) – Endpoint attribute value.
  • service_type (string) – Service type of the endpoint.
  • endpoint_type (string) – Type of endpoint. Possible values: public or publicURL, internal or internalURL, admin or adminURL
  • region_name (string) – Region of the endpoint.
  • service_name (string) – The assigned name of the service.
Returns:

tuple of urls or None (if no match found)

region_name
url_for(*args, **kwargs)

Fetch an endpoint from the service catalog.

Fetch the specified endpoint from the service catalog for a particular endpoint attribute. If no attribute is given, return the first endpoint of the specified type.

Valid endpoint types: public or publicURL,
internal or internalURL, admin or ‘adminURL`
Parameters:
  • attr (string) – Endpoint attribute name.
  • filter_value (string) – Endpoint attribute value.
  • service_type (string) – Service type of the endpoint.
  • endpoint_type (string) – Type of endpoint.
  • region_name (string) – Region of the endpoint.
  • service_name (string) – The assigned name of the service.
class keystoneclient.service_catalog.ServiceCatalogV2(resource_dict, region_name=None)

Bases: keystoneclient.service_catalog.ServiceCatalog

An object for encapsulating the service catalog using raw v2 auth token from Keystone.

get_data()
get_token()
get_urls(*args, **kwargs)
classmethod is_valid(resource_dict)
class keystoneclient.service_catalog.ServiceCatalogV3(token, resource_dict, region_name=None)

Bases: keystoneclient.service_catalog.ServiceCatalog

An object for encapsulating the service catalog using raw v3 auth token from Keystone.

get_data()
get_token()
get_urls(*args, **kwargs)
classmethod is_valid(resource_dict)

keystoneclient.session module

class keystoneclient.session.Session(*args, **kwargs)

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 (keystoneclient.auth.base.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 (string) – 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 (string) – A User-Agent header string to use for the request. If not provided a default is used. (optional, defaults to ‘python-keystoneclient’)
  • 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)
DEFAULT_REDIRECT_LIMIT = 30

This property is deprecated.

REDIRECT_STATUSES = (301, 302, 303, 305, 307)

This property is deprecated.

classmethod construct(kwargs)

Handles constructing a session from the older HTTPClient args as well as the new request-style arguments.

Warning

DEPRECATED: This function is purely for bridging the gap between older client arguments and the session arguments that they relate to. It is not intended to be used as a generic Session Factory.

This function purposefully modifies the input kwargs dictionary so that the remaining kwargs dict can be reused and passed on to other functions without session arguments.

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_auth_headers(auth=None, **kwargs)

Return auth headers as provided by the auth plugin.

Parameters:

auth (keystoneclient.auth.base.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

classmethod get_conf_options(*args, **kwargs)

Get the oslo_config options that are needed for a Session.

These may be useful without being registered for config file generation or to manipulate the options before registering them yourself.

The options that are set are:
cafile:The certificate authority filename.
certfile:The client certificate file to present.
keyfile:The key for the client certificate.
insecure:Whether to ignore SSL verification.
timeout:The max time to wait for HTTP connections.
Parameters:deprecated_opts (dict) –

Deprecated options that should be included in the definition of new options. This should be a dict from the name of the new option to a list of oslo.DeprecatedOpts that correspond to the new option. (optional)

For example, to support the ca_file option pointing to the new cafile option name:

old_opt = oslo.cfg.DeprecatedOpt('ca_file', 'old_group')
deprecated_opts={'cafile': [old_opt]}
Returns:A list of oslo_config options.
get_endpoint(auth=None, **kwargs)

Get an endpoint as provided by the auth plugin.

Parameters:auth (keystoneclient.auth.base.BaseAuthPlugin) – The auth plugin to use for token. Overrides the plugin on the session. (optional)
Raises keystoneclient.exceptions.MissingAuthPlugin:
 if a plugin is not available.
Returns:An endpoint if available or None.
Return type:string
get_project_id(auth=None)

Return the authenticated project_id as provided by the auth plugin.

Parameters:

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

Raises:
Returns string:

Current project_id or None if not supported by plugin.

get_token(auth=None)

Return a token as provided by the auth plugin.

Parameters:

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

Raises:
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 (keystoneclient.auth.base.BaseAuthPlugin) – The auth plugin to use for token. Overrides the plugin on the session. (optional)

Raises:
Returns string:

Current user_id or None if not supported by plugin.

head(url, **kwargs)

Perform a HEAD request.

This calls request() with method set to HEAD.

invalidate(auth=None)

Invalidate an authentication plugin.

Parameters:auth (keystoneclient.auth.base.BaseAuthPlugin) – The auth plugin to invalidate. Overrides the plugin on the session. (optional)
classmethod load_from_cli_options(args, **kwargs)

Create a Session object from CLI arguments.

The CLI arguments must have been registered with register_cli_options().

Parameters:args (Namespace) – result of parsed arguments.
Returns:A new session object.
Return type:Session
classmethod load_from_conf_options(conf, group, **kwargs)

Create a session object from an oslo_config object.

The options must have been previously registered with register_conf_options.

Parameters:
  • conf (oslo_config.Cfg) – config object to register with.
  • group (string) – The ini group to register options in.
  • kwargs (dict) – Additional parameters to pass to session construction.
Returns:

A new session object.

Return type:

Session

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.

classmethod process_header(header)

Redacts the secure headers to be logged.

put(url, **kwargs)

Perform a PUT request.

This calls request() with method set to PUT.

static register_cli_options(parser)

Register the argparse arguments that are needed for a session.

Parameters:parser (argparse.ArgumentParser) – parser to add to.
classmethod register_conf_options(*args, **kwargs)

Register the oslo_config options that are needed for a session.

The options that are set are:
cafile:The certificate authority filename.
certfile:The client certificate file to present.
keyfile:The key for the client certificate.
insecure:Whether to ignore SSL verification.
timeout:The max time to wait for HTTP connections.
Parameters:
  • conf (oslo_config.Cfg) – config object to register with.
  • group (string) – The ini group to register options in.
  • deprecated_opts (dict) –

    Deprecated options that should be included in the definition of new options. This should be a dict from the name of the new option to a list of oslo.DeprecatedOpts that correspond to the new option. (optional)

    For example, to support the ca_file option pointing to the new cafile option name:

    old_opt = oslo.cfg.DeprecatedOpt('ca_file', 'old_group')
    deprecated_opts={'cafile': [old_opt]}
    
Returns:

The list of options that was registered.

request(*args, **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 (string) – 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 (string) – The http method to use. (e.g. ‘GET’, ‘POST’)
  • original_ip (string) – 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 (string) – 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. (optional)
  • auth (keystoneclient.auth.base.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 keystoneclient.session default logger will be 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 ‘json’ param. ‘allow_redirects’ is ignored as redirects are handled by the session.
Raises keystoneclient.exceptions.ClientException:
 

For connection failure, or to indicate an error response code.

Returns:

The response to the request.

user_agent = None
class keystoneclient.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.

init_poolmanager(*args, **kwargs)
keystoneclient.session.request(url, method='GET', **kwargs)

keystoneclient.shell module

Command-line interface to the OpenStack Identity API.

class keystoneclient.shell.OpenStackHelpFormatter(prog, indent_increment=2, max_help_position=24, width=None)

Bases: argparse.HelpFormatter

INDENT_BEFORE_ARGUMENTS = 6
MAX_WIDTH_ARGUMENTS = 32
add_arguments(actions)
start_section(heading)
class keystoneclient.shell.OpenStackIdentityShell(parser_class=<class 'argparse.ArgumentParser'>)

Bases: object

auth_check(args)
do_bash_completion(args)

Prints all of the commands and options to stdout.

The keystone.bash_completion script doesn’t have to hard code them.

do_help(args)

Display help about this program or one of its subcommands.

get_api_class(version)
get_base_parser()
get_subcommand_parser(version)
main(argv)
keystoneclient.shell.env(*vars, **kwargs)

Search for the first defined of possibly many env vars

Returns the first environment variable defined in vars, or returns the default defined in kwargs.

keystoneclient.shell.main()

keystoneclient.utils module

keystoneclient.utils.arg(*args, **kwargs)
keystoneclient.utils.find_resource(manager, name_or_id)

Helper for the _find_* methods.

keystoneclient.utils.hash_signed_token(signed_text, mode='md5')
keystoneclient.utils.isunauthenticated(f)

Checks to see if the function is marked as not requiring authentication with the @unauthenticated decorator.

Returns True if decorator is set to True, False otherwise.

class keystoneclient.utils.positional(max_positional_args=None, enforcement='except')

Bases: object

A decorator which enforces only some args may be passed positionally.

This idea and some of the code was taken from the oauth2 client of the google-api client.

This decorator makes it easy to support Python 3 style key-word only parameters. For example, in Python 3 it is possible to write:

def fn(pos1, *, kwonly1, kwonly2=None):
    ...

All named parameters after * must be a keyword:

fn(10, 'kw1', 'kw2')  # Raises exception.
fn(10, kwonly1='kw1', kwonly2='kw2')  # Ok.

To replicate this behaviour with the positional decorator you simply specify how many arguments may be passed positionally. To replicate the example above:

@positional(1)
def fn(pos1, kwonly1=None, kwonly2=None):
    ...

If no default value is provided to a keyword argument, it becomes a required keyword argument:

@positional(0)
def fn(required_kw):
    ...

This must be called with the keyword parameter:

fn()  # Raises exception.
fn(10)  # Raises exception.
fn(required_kw=10)  # Ok.

When defining instance or class methods always remember that in python the first positional argument passed is always the instance so you will need to account for self and cls:

class MyClass(object):

    @positional(2)
    def my_method(self, pos1, kwonly1=None):
        ...

    @classmethod
    @positional(2)
    def my_method(cls, pos1, kwonly1=None):
        ...

If you would prefer not to account for self and cls you can use the method and classmethod helpers which do not consider the initial positional argument. So the following class is exactly the same as the one above:

class MyClass(object):

    @positional.method(1)
    def my_method(self, pos1, kwonly1=None):
        ...

    @positional.classmethod(1)
    def my_method(cls, pos1, kwonly1=None):
        ...

If a value isn’t provided to the decorator then it will enforce that every variable without a default value will be required to be a kwarg:

@positional()
def fn(pos1, kwonly1=None):
    ...

fn(10)  # Ok.
fn(10, 20)  # Raises exception.
fn(10, kwonly1=20)  # Ok.

This behaviour will work with the positional.method and positional.classmethod helper functions as well:

class MyClass(object):

    @positional.classmethod()
    def my_method(cls, pos1, kwonly1=None):
        ...

MyClass.my_method(10)  # Ok.
MyClass.my_method(10, 20)  # Raises exception.
MyClass.my_method(10, kwonly1=20)  # Ok.

For compatibility reasons you may wish to not always raise an exception so a WARN mode is available. Rather than raise an exception a warning message will be logged:

@positional(1, enforcement=positional.WARN):
def fn(pos1, kwonly=1):
   ...

Available modes are:

  • positional.EXCEPT - the default, raise an exception.
  • positional.WARN - log a warning on mistake.
EXCEPT = 'except'
WARN = 'warn'
classmethod classmethod(*args, **kwargs)
classmethod method(max_positional_args=None, enforcement='except')
keystoneclient.utils.pretty_choice_list(l)
keystoneclient.utils.print_dict(d, wrap=0)

pretty table prints dictionaries.

Wrap values to max_length wrap if wrap>0

keystoneclient.utils.print_list(objs, fields, formatters={}, order_by=None)
keystoneclient.utils.prompt_for_password()

Prompt user for password if not provided so the password doesn’t show up in the bash history.

keystoneclient.utils.unauthenticated(f)

Adds ‘unauthenticated’ attribute to decorated function.

Usage:

@unauthenticated
def mymethod(f):
    ...

Module contents

The python bindings for the OpenStack Identity (Keystone) project.

A Client object will allow you to communicate with the Identity server. The recommended way to get a Client object is to use keystoneclient.client.Client(). Client() uses version discovery to create a V3 or V2 client depending on what versions the Identity server supports and what version is requested.

Identity V2 and V3 clients can also be created directly. See keystoneclient.v3.client.Client for the V3 client and keystoneclient.v2_0.client.Client for the V2 client.