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.resource2.
Body
(name, type=None, default=None, alternate_id=False)¶ 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.
- 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.
-
class
openstack.resource2.
Header
(name, type=None, default=None, alternate_id=False)¶ 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.
- 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.
-
class
openstack.resource2.
URI
(name, type=None, default=None, alternate_id=False)¶ 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.
- 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.
The Resource class¶
-
class
openstack.resource2.
Resource
(_synchronized=False, **attrs)¶ The base resource
Parameters: _synchronized (bool) – This is not intended to be used directly. See new()
andexisting()
.-
resource_key
= None¶ Singular form of key for resource.
-
resources_key
= None¶ Plural form of key for resource.
-
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.
-
patch_update
= False¶ Use PATCH for update operations on this resource.
-
put_create
= False¶ Use PUT for create operations on this resource.
-
classmethod
new
(**kwargs)¶ Create a new instance of this resource.
When creating the instance set the
_synchronized
parameter ofResource
toFalse
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 asupdate()
.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 ofResource
toTrue
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 immediateupdate()
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: 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 (
Session
) – 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
ifResource.allow_create
is not set toTrue
.- session (
-
get
(session, requires_id=True)¶ Get a remote resource based on this instance.
Parameters: - session (
Session
) – 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
ifResource.allow_get
is not set toTrue
.- session (
-
head
(session)¶ Get headers from a remote resource based on this instance.
Parameters: session ( Session
) – The session to use for making this request.Returns: This Resource
instance.Raises: MethodNotSupported
ifResource.allow_head
is not set toTrue
.
-
update
(session, prepend_key=True, has_body=True)¶ Update the remote resource based on this instance.
Parameters: - session (
Session
) – 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
ifResource.allow_update
is not set toTrue
.- session (
-
delete
(session)¶ Delete the remote resource based on this instance.
Parameters: session ( Session
) – The session to use for making this request.Returns: This Resource
instance.Raises: MethodNotSupported
ifResource.allow_update
is not set toTrue
.
-
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 (
Session
) – The session to use for making this request. - paginated (bool) –
True
if a GET to this resource returns a paginated series of responses, orFalse
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 toget()
. They are additionally checked against thebase_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
ifResource.allow_list
is not set toTrue
.- session (
-
classmethod
find
(session, name_or_id, ignore_missing=True, **params)¶ Find a resource by its name or id.
Parameters: - session (
Session
) – 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 toTrue
, 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 isFalse
.- session (
-