Resource¶

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.