Resource

Note: This class is in the process of being applied as the new base class for resources around the OpenStack SDK. Once that has been completed, this module will be drop the 2 suffix and be the only resource module.

Resource

The Resource class is a base class that represent a remote resource. The attributes that comprise a request or response for this resource are specified as class members on the Resource subclass where their values are of a component type, including Body, Header, and URI.

For update management, Resource employs a series of _ComponentManager instances to look after the attributes of that particular component type. This is particularly useful for Body and Header types, so that only the values necessary are sent in requests to the server.

When making requests, each of the managers are looked at to gather the necessary URI, body, and header data to build a request to be sent via keystoneauth’s sessions. Responses from keystoneauth are then converted into this Resource class’ appropriate components and types and then returned to the caller.

Components

class openstack.resource.Body(name, type=None, default=None, alias=None, alternate_id=False, list_type=None, **kwargs)

Body attributes

A typed descriptor for a component that makes up a Resource

Parameters:
  • name – The name this component exists as on the server
  • type – The type this component is expected to be by the server. By default this is None, meaning any value you specify will work. If you specify type=dict and then set a component to a string, __set__ will fail, for example.
  • default – Typically None, but any other default can be set.
  • alias – If set, alternative attribute on object to return.
  • alternate_id – When True, this property is known internally as a value that can be sent with requests that require an ID but when id is not a name the Resource has. This is a relatively uncommon case, and this setting should only be used once per Resource.
  • list_type – If type is list, list_type designates what the type of the elements of the list should be.
class openstack.resource.Header(name, type=None, default=None, alias=None, alternate_id=False, list_type=None, **kwargs)

Header attributes

A typed descriptor for a component that makes up a Resource

Parameters:
  • name – The name this component exists as on the server
  • type – The type this component is expected to be by the server. By default this is None, meaning any value you specify will work. If you specify type=dict and then set a component to a string, __set__ will fail, for example.
  • default – Typically None, but any other default can be set.
  • alias – If set, alternative attribute on object to return.
  • alternate_id – When True, this property is known internally as a value that can be sent with requests that require an ID but when id is not a name the Resource has. This is a relatively uncommon case, and this setting should only be used once per Resource.
  • list_type – If type is list, list_type designates what the type of the elements of the list should be.
class openstack.resource.URI(name, type=None, default=None, alias=None, alternate_id=False, list_type=None, **kwargs)

URI attributes

A typed descriptor for a component that makes up a Resource

Parameters:
  • name – The name this component exists as on the server
  • type – The type this component is expected to be by the server. By default this is None, meaning any value you specify will work. If you specify type=dict and then set a component to a string, __set__ will fail, for example.
  • default – Typically None, but any other default can be set.
  • alias – If set, alternative attribute on object to return.
  • alternate_id – When True, this property is known internally as a value that can be sent with requests that require an ID but when id is not a name the Resource has. This is a relatively uncommon case, and this setting should only be used once per Resource.
  • list_type – If type is list, list_type designates what the type of the elements of the list should be.

The Resource class

class openstack.resource.Resource(_synchronized=False, **attrs)

The base resource

Parameters:_synchronized (bool) – This is not intended to be used directly. See new() and existing().
resource_key = None

Singular form of key for resource.

resources_key = None

Plural form of key for resource.

pagination_key = None

Key used for pagination links

id = None

The ID of this resource.

name = None

The name of this resource.

location = None

The location of this resource.

base_path = ''

The base part of the URI for this resource.

service = None

The service associated with this resource to find the service URL.

allow_create = False

Allow create operation for this resource.

allow_get = False

Allow get operation for this resource.

allow_update = False

Allow update operation for this resource.

allow_delete = False

Allow delete operation for this resource.

allow_list = False

Allow list operation for this resource.

allow_head = False

Allow head operation for this resource.

update_method = 'PUT'

Method for udating a resource (PUT, PATCH, POST)

create_method = 'POST'

Method for creating a resource (POST, PUT)

requires_id = True

Do calls for this resource require an id

has_body = True

Do responses for this resource have bodies

detail_for = None

Is this a detailed version of another Resource

classmethod new(**kwargs)

Create a new instance of this resource.

When creating the instance set the _synchronized parameter of Resource to False to indicate that the resource does not yet exist on the server side. This marks all attributes passed in **kwargs as “dirty” on the resource, and thusly tracked as necessary in subsequent calls such as update().

Parameters:kwargs (dict) – Each of the named arguments will be set as attributes on the resulting Resource object.
classmethod existing(**kwargs)

Create an instance of an existing remote resource.

When creating the instance set the _synchronized parameter of Resource to True to indicate that it represents the state of an existing server-side resource. As such, all attributes passed in **kwargs are considered “clean”, such that an immediate update() call would not generate a body of attributes to be modified on the server.

Parameters:kwargs (dict) – Each of the named arguments will be set as attributes on the resulting Resource object.
to_dict(body=True, headers=True, ignore_none=False)

Return a dictionary of this resource’s contents

Parameters:
  • body (bool) – Include the Body attributes in the returned dictionary.
  • headers (bool) – Include the Header attributes in the returned dictionary.
  • ignore_none (bool) – When True, exclude key/value pairs where the value is None. This will exclude attributes that the server hasn’t returned.
Returns:

A dictionary of key/value pairs where keys are named as they exist as attributes of this class.

create(session, prepend_key=True)

Create a remote resource based on this instance.

Parameters:
  • session (Adapter) – The session to use for making this request.
  • prepend_key – A boolean indicating whether the resource_key should be prepended in a resource creation request. Default to True.
Returns:

This Resource instance.

Raises:

MethodNotSupported if Resource.allow_create is not set to True.

get(session, requires_id=True, error_message=None)

Get a remote resource based on this instance.

Parameters:
  • session (Adapter) – The session to use for making this request.
  • requires_id (boolean) – A boolean indicating whether resource ID should be part of the requested URI.
Returns:

This Resource instance.

Raises:

MethodNotSupported if Resource.allow_get is not set to True.

head(session)

Get headers from a remote resource based on this instance.

Parameters:session (Adapter) – The session to use for making this request.
Returns:This Resource instance.
Raises:MethodNotSupported if Resource.allow_head is not set to True.
update(session, prepend_key=True, has_body=True)

Update the remote resource based on this instance.

Parameters:
  • session (Adapter) – The session to use for making this request.
  • prepend_key – A boolean indicating whether the resource_key should be prepended in a resource update request. Default to True.
Returns:

This Resource instance.

Raises:

MethodNotSupported if Resource.allow_update is not set to True.

delete(session, error_message=None)

Delete the remote resource based on this instance.

Parameters:session (Adapter) – The session to use for making this request.
Returns:This Resource instance.
Raises:MethodNotSupported if Resource.allow_update is not set to True.
classmethod list(session, paginated=False, **params)

This method is a generator which yields resource objects.

This resource object list generator handles pagination and takes query params for response filtering.

Parameters:
  • session (Adapter) – The session to use for making this request.
  • paginated (bool) – True if a GET to this resource returns a paginated series of responses, or False if a GET returns only one page of data. When paginated is False only one page of data will be returned regardless of the API’s support of pagination.
  • params (dict) – These keyword arguments are passed through the _transpose() method to find if any of them match expected query parameters to be sent in the params argument to get(). They are additionally checked against the base_path format string to see if any path fragments need to be filled in by the contents of this argument.
Returns:

A generator of Resource objects.

Raises:

MethodNotSupported if Resource.allow_list is not set to True.

Raises:

InvalidResourceQuery if query contains invalid params.

classmethod find(session, name_or_id, ignore_missing=True, **params)

Find a resource by its name or id.

Parameters:
  • session (Adapter) – The session to use for making this request.
  • name_or_id – This resource’s identifier, if needed by the request. The default is None.
  • ignore_missing (bool) – When set to False ResourceNotFound will be raised when the resource does not exist. When set to True, None will be returned when attempting to find a nonexistent resource.
  • params (dict) – Any additional parameters to be passed into underlying methods, such as to existing() in order to pass on URI parameters.
Returns:

The Resource object matching the given name or id or None if nothing matches.

Raises:

openstack.exceptions.DuplicateResource if more than one resource is found for this request.

Raises:

openstack.exceptions.ResourceNotFound if nothing is found and ignore_missing is False.

Creative Commons Attribution 3.0 License

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