Resource

Base resource class.

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, aka=None, alternate_id=False, list_type=None, coerce_to_default=False, deprecated=False, deprecation_reason=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.

• aka – If set, additional name attribute would be available under.

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

• coerce_to_default – If the Component is None or not present, force the given default to be used. If a default is not given but a type is given, construct an empty version of the type in question.

• deprecated – Indicates if the option is deprecated. If it is, we display a warning message to the user.

• deprecation_reason – Custom deprecation message.

class openstack.resource.Header(name, type=None, default=None, alias=None, aka=None, alternate_id=False, list_type=None, coerce_to_default=False, deprecated=False, deprecation_reason=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.

• aka – If set, additional name attribute would be available under.

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

• coerce_to_default – If the Component is None or not present, force the given default to be used. If a default is not given but a type is given, construct an empty version of the type in question.

• deprecated – Indicates if the option is deprecated. If it is, we display a warning message to the user.

• deprecation_reason – Custom deprecation message.

class openstack.resource.URI(name, type=None, default=None, alias=None, aka=None, alternate_id=False, list_type=None, coerce_to_default=False, deprecated=False, deprecation_reason=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.

• aka – If set, additional name attribute would be available under.

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

• coerce_to_default – If the Component is None or not present, force the given default to be used. If a default is not given but a type is given, construct an empty version of the type in question.

• deprecated – Indicates if the option is deprecated. If it is, we display a warning message to the user.

• deprecation_reason – Custom deprecation message.

The Resource class

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

The base resource

Parameters:

• _synchronized (bool) – This is not intended to be used directly. See new() and existing().

• connection (openstack.connection.Connection) – Reference to the Connection being used. Defaults to None to allow Resource objects to be used without an active Connection, such as in unit tests. Use of self._connection in Resource code should protect itself with a check for None.

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

The ID of this resource.

name

The name of this resource.

location

The OpenStack location of this resource.

base_path = ''

The base part of the URI for this resource.

allow_create = False

Allow create operation for this resource.

allow_fetch = False

Allow get operation for this resource.

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

allow_patch = False

Allow patch operation for this resource.

allow_empty_commit = False

Commits happen without header or body being dirty.

commit_method = 'PUT'

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

create_method = 'POST'

Method for creating a resource (POST, PUT)

commit_jsonpatch = False

Whether commit uses JSON patch format.

requires_id = True

Do calls for this resource require an id

create_requires_id = None

Whether create requires an ID (determined from method if None).

create_exclude_id_from_body = False

Whether create should exclude ID in the body of the request.

has_body = True

Do responses for this resource have bodies

create_returns_body = None

Does create returns a body (if False requires ID), defaults to has_body

microversion = None

API microversion (string or None) this Resource was loaded with

keys() → a set-like object providing a view on D's keys

items() → a set-like object providing a view on D's items

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(connection=None, **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, computed=True, ignore_none=False, original_names=False, _to_munch=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.

• computed (bool) – Include the Computed 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.

• original_names (bool) – When True, use attribute names as they were received from the server.

• _to_munch (bool) – For internal use only. Converts to utils.Munch instead of dict.

Returns:

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

toDict(body=True, headers=True, computed=True, ignore_none=False, original_names=False, _to_munch=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.

• computed (bool) – Include the Computed 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.

• original_names (bool) – When True, use attribute names as they were received from the server.

• _to_munch (bool) – For internal use only. Converts to utils.Munch instead of dict.

Returns:

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

copy(body=True, headers=True, computed=True, ignore_none=False, original_names=False, _to_munch=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.

• computed (bool) – Include the Computed 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.

• original_names (bool) – When True, use attribute names as they were received from the server.

• _to_munch (bool) – For internal use only. Converts to utils.Munch instead of dict.

Returns:

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

create(session, prepend_key=True, base_path=None, *, resource_request_key=None, resource_response_key=None, microversion=None, **params)

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.

• base_path (str) – Base part of the URI for creating resources, if different from base_path.

• resource_request_key (str) – Overrides the usage of self.resource_key when prepending a key to the request body. Ignored if prepend_key is false.

• resource_response_key (str) – Overrides the usage of self.resource_key when processing response bodies. Ignored if prepend_key is false.

• microversion (str) – API version to override the negotiated one.

• params (dict) – Additional params to pass.

Returns:

This Resource instance.

Raises:

MethodNotSupported if Resource.allow_create is not set to True.

classmethod bulk_create(session, data, prepend_key=True, base_path=None, *, microversion=None, **params)

Create multiple remote resources based on this class and data.

Parameters:

• session (Adapter) – The session to use for making this request.

• data – list of dicts, which represent resources to create.

• prepend_key – A boolean indicating whether the resource_key should be prepended in a resource creation request. Default to True.

• base_path (str) – Base part of the URI for creating resources, if different from base_path.

• microversion (str) – API version to override the negotiated one.

• params (dict) – Additional params to pass.

Returns:

A generator of Resource objects.

Raises:

MethodNotSupported if Resource.allow_create is not set to True.

fetch(session, requires_id=True, base_path=None, error_message=None, skip_cache=False, *, resource_response_key=None, microversion=None, **params)

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.

• base_path (str) – Base part of the URI for fetching resources, if different from base_path.

• error_message (str) – An Error message to be returned if requested object does not exist.

• skip_cache (bool) – A boolean indicating whether optional API cache should be skipped for this invocation.

• resource_response_key (str) – Overrides the usage of self.resource_key when processing the response body.

• microversion (str) – API version to override the negotiated one.

• params (dict) – Additional parameters that can be consumed.

Returns:

This Resource instance.

Raises:

MethodNotSupported if Resource.allow_fetch is not set to True.

Raises:

ResourceNotFound if the resource was not found.

head(session, base_path=None, *, microversion=None)

Get headers from a remote resource based on this instance.

Parameters:

• session (Adapter) – The session to use for making this request.

• base_path (str) – Base part of the URI for fetching resources, if different from base_path.

• microversion (str) – API version to override the negotiated one.

Returns:

This Resource instance.

Raises:

MethodNotSupported if Resource.allow_head is not set to True.

Raises:

ResourceNotFound if the resource was not found.

property requires_commit

Whether the next commit() call will do anything.

commit(session, prepend_key=True, has_body=True, retry_on_conflict=None, base_path=None, *, microversion=None, **kwargs)

Commit the state of the instance to the remote resource.

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.

• retry_on_conflict (bool) – Whether to enable retries on HTTP CONFLICT (409). Value of None leaves the Adapter defaults.

• base_path (str) – Base part of the URI for modifying resources, if different from base_path.

• microversion (str) – API version to override the negotiated one.

• kwargs (dict) – Parameters that will be passed to _prepare_request()

Returns:

This Resource instance.

Raises:

MethodNotSupported if Resource.allow_commit is not set to True.

patch(session, patch=None, prepend_key=True, has_body=True, retry_on_conflict=None, base_path=None, *, microversion=None)

Patch the remote resource.

Allows modifying the resource by providing a list of JSON patches to apply to it. The patches can use both the original (server-side) and SDK field names.

Parameters:

• session (Adapter) – The session to use for making this request.

• patch – Additional JSON patch as a list or one patch item. If provided, it is applied on top of any changes to the current resource.

• prepend_key – A boolean indicating whether the resource_key should be prepended in a resource update request. Default to True.

• retry_on_conflict (bool) – Whether to enable retries on HTTP CONFLICT (409). Value of None leaves the Adapter defaults.

• base_path (str) – Base part of the URI for modifying resources, if different from base_path.

• microversion (str) – API version to override the negotiated one.

Returns:

This Resource instance.

Raises:

MethodNotSupported if Resource.allow_patch is not set to True.

delete(session, error_message=None, *, microversion=None, **kwargs)

Delete the remote resource based on this instance.

Parameters:

• session (Adapter) – The session to use for making this request.

• microversion (str) – API version to override the negotiated one.

• kwargs (dict) – Parameters that will be passed to _prepare_request()

Returns:

This Resource instance.

Raises:

MethodNotSupported if Resource.allow_commit is not set to True.

Raises:

ResourceNotFound if the resource was not found.

classmethod list(session, paginated=True, base_path=None, allow_unknown_params=False, *, microversion=None, **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.

• base_path (str) – Base part of the URI for listing resources, if different from base_path.

• allow_unknown_params (bool) – True to accept, but discard unknown query parameters. This allows getting list of ‘filters’ and passing everything known to the server. False will result in validation exception when unknown query parameters are passed.

• microversion (str) – API version to override the negotiated one.

• 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. Parameters supported as filters by the server side are passed in the API call, remaining parameters are applied as filters to the retrieved results.

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, list_base_path=None, *, microversion=None, all_projects=None, **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.

• list_base_path (str) – base_path to be used when need listing resources.

• microversion (str) – API version to override the negotiated one.

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