How the SDK is organized¶

Resource¶

The openstack.resource.Resource base class is the building block of any service implementation. Resource objects correspond to the resources each service’s REST API works with, so the openstack.compute.v2.server.Server subclass maps to the compute service’s https://openstack:1234/v2/servers resource.

The base Resource contains methods to support the typical CRUD operations supported by REST APIs, and handles the construction of URLs and calling the appropriate HTTP verb on the given Adapter.

Values sent to or returned from the service are implemented as attributes on the Resource subclass with type openstack.resource.prop. The prop is created with the exact name of what the API expects, and can optionally include a type to be validated against on requests. You should choose an attribute name that follows PEP-8, regardless of what the server-side expects, as this prop becomes a mapping between the two.:

is_public = resource.prop('os-flavor-access:is_public', type=bool)

There are six additional attributes which the Resource class checks before making requests to the REST API. allow_create, allow_retreive, allow_update, allow_delete, allow_head, and allow_list are set to True or False, and are checked before making the corresponding method call.

The base_path attribute should be set to the URL which corresponds to this resource. Many base_paths are simple, such as "/servers". For base_paths which are composed of non-static information, Python’s string replacement is used, e.g., base_path = "/servers/%(server_id)s/ips".

resource_key and resources_key are attributes to set when a Resource returns more than one item in a response, or otherwise requires a key to obtain the response value. For example, the Server class sets resource_key = "server" as an individual Server is stored in a dictionary keyed with the singular noun, and resource_keys = "servers" as multiple Servers are stored in a dictionary keyed with the plural noun in the response.

Proxy¶

Each service implements a Proxy class based on Proxy, within the openstack/<program_name>/vX/_proxy.py module. For example, the v2 compute service’s Proxy exists in openstack/compute/v2/_proxy.py.

The Proxy class is based on OpenStackSDKAdapter which is in turn based on Adapter.

class openstack.proxy.Proxy(session=None, task_manager=None, *args, **kwargs)¶

Bases: openstack._adapter.OpenStackSDKAdapter

Represents a service.

wait_for_status(*args, **kwargs)¶

Wait for a resource to be in a particular status.

Parameters:	value (Resource) – The resource to wait on to reach the status. The resource must have a status attribute. status – Desired status of the resource. failures (list) – Statuses that would indicate the transition failed such as ‘ERROR’. interval – Number of seconds to wait between checks. wait – Maximum number of seconds to wait for the change.
Returns:	Method returns resource on success.
Raises:	ResourceTimeout transition to status failed to occur in wait seconds.
Raises:	ResourceFailure resource transitioned to one of the failure states.
Raises:	AttributeError if the resource does not have a status attribute

Deprecated since version 0.9.14: This will be removed in 2.0.0. This is no longer a part of the proxy base, service-specific subclasses should expose this as needed. See resource.wait_for_status for this behavior

wait_for_delete(*args, **kwargs)¶

Wait for the resource to be deleted.

Parameters:	value (Resource) – The resource to wait on to be deleted. interval – Number of seconds to wait between checks. wait – Maximum number of seconds to wait for the delete.
Returns:	Method returns resource on success.
Raises:	ResourceTimeout transition to delete failed to occur in wait seconds.

Deprecated since version 0.9.14: This will be removed in 2.0.0. This is no longer a part of the proxy base, service-specific subclasses should expose this as needed. See resource.wait_for_delete for this behavior

class openstack._adapter.OpenStackSDKAdapter(session=None, task_manager=None, *args, **kwargs)¶

Bases: keystoneauth1.adapter.Adapter

Wrapper around keystoneauth1.adapter.Adapter.

Uses task_manager to run tasks rather than executing them directly. This allows using the nodepool MultiThreaded Rate Limiting TaskManager.

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:	keystoneauth1.exceptions.auth_plugins.MissingAuthPlugin – if a plugin is not available. TypeError – If arguments are invalid
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:	keystoneauth1.exceptions.auth.AuthorizationFailure – if a new token fetch fails. keystoneauth1.exceptions.auth_plugins.MissingAuthPlugin – if a plugin is not available.
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:	keystoneauth1.exceptions.auth.AuthorizationFailure – if a new token fetch fails. keystoneauth1.exceptions.auth_plugins.MissingAuthPlugin – if a plugin is not available.
Returns:	Current user_id or None if not supported by plugin.
Return type:	str

invalidate(auth=None)¶

Invalidate an authentication plugin.

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)

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.

Each service’s Proxy provides a higher-level interface for users to work with via a Connection instance.

Rather than requiring users to maintain their own Adapter and work with lower-level Resource objects, the Proxy interface offers a place to make things easier for the caller.

Each Proxy class implements methods which act on the underlying Resource classes which represent the service. For example:

def list_flavors(self, **params):
    return flavor.Flavor.list(self.session, **params)

This method is operating on the openstack.compute.v2.flavor.Flavor.list method. For the time being, it simply passes on the Adapter maintained by the Proxy, and returns what the underlying Resource.list method does.

The implementations and method signatures of Proxy methods are currently under construction, as we figure out the best way to implement them in a way which will apply nicely across all of the services.

Connection¶

The openstack.connection.Connection class builds atop a openstack.config.cloud_region.CloudRegion object, and provides a higher level interface constructed of Proxy objects from each of the services.

The Connection class’ primary purpose is to act as a high-level interface to this SDK, managing the lower level connecton bits and exposing the Resource objects through their corresponding Proxy object.

If you’ve built proper Resource objects and implemented methods on the corresponding Proxy object, the high-level interface to your service should now be exposed.