Resource¶

Components¶

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

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

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

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.

service = None¶

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

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

has_body = True¶

Do responses for this resource have bodies

microversion = None¶

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

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

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 munch.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 munch.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 munch.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)¶

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.
Returns:	This Resource instance.
Raises:	MethodNotSupported if Resource.allow_create is not set to True.

fetch(session, requires_id=True, base_path=None, 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. 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.
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)¶

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.
Returns:	This Resource instance.
Raises:	MethodNotSupported if Resource.allow_head is not set to True.
Raises:	ResourceNotFound if the resource was not found.

commit(session, prepend_key=True, has_body=True, retry_on_conflict=None, base_path=None)¶

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.
Returns:	This Resource instance.
Raises:	MethodNotSupported if Resource.allow_commit 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_commit is not set to True.
Raises:	ResourceNotFound if the resource was not found.

classmethod list(session, paginated=True, base_path=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. 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.