Resource

The Resource class is a base class that represent a remote resource. Attributes of the resource are defined by the responses from the server rather than in code so that we don’t have to try and keep up with all possible attributes and extensions. This may be changed in the future.

The prop class is a helper for definiting properties in a resource.

For update management, Resource maintains a dirty list so when updating an object only the attributes that have actually been changed are sent to the server.

There is also some support here for lazy loading that needs improvement.

There are plenty of examples of use of this class in the SDK code.

The prop class

class openstack.resource.prop(name, alias=None, type=None, default=None)

A helper for defining properties in a resource.

A prop defines some known attributes within a resource’s values. For example we know a User resource will have a name:

>>> class User(Resource):
...     name = prop('name')
...
>>> u = User()
>>> u.name = 'John Doe'
>>> print u['name']
John Doe

User objects can now be accessed via the User().name attribute. The ‘name’ value we pass as an attribute is the name of the attribute in the message. This means that you don’t need to use the same name for your attribute as will be set within the object. For example:

>>> class User(Resource):
...     name = prop('userName')
...
>>> u = User()
>>> u.name = 'John Doe'
>>> print u['userName']
John Doe

There is limited validation ability in props.

You can validate the type of values that are set:

>>> class User(Resource):
...     name = prop('userName')
...     age = prop('age', type=int)
...
>>> u = User()
>>> u.age = 'thirty'
TypeError: Invalid type for attr age

By specifying an alias attribute name, that alias will be read when the primary attribute name does not appear within the resource:

>>> class User(Resource):
...     name = prop('address', alias='location')
...
>>> u = User(location='Far Away')
>>> print u['address']
Far Away

The Resource class

class openstack.resource.Resource(attrs=None, loaded=False)

Construct a Resource to interact with a service’s REST API.

The Resource class offers two class methods to construct resource objects, which are preferrable to entering through this initializer. See Resource.new() and Resource.existing().

Parameters:
  • attrs (dict) – The attributes to set when constructing this Resource.
  • loaded (bool) – True if this Resource exists on the server, False if it does not.
resource_key = None

Singular form of key for resource.

resource_name = None

Common name for resource.

resources_key = None

Plural form of key for resource.

id_attribute = 'id'

Attribute key associated with the id for this resource.

name_attribute = 'name'

Attribute key associated with the name for this resource.

base_path = ''

The base part of the url 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_retrieve = False

Allow retrieve/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.

classmethod new(**kwargs)

Create a new instance of this resource.

Internally set flags such that it is marked as not present on the server.

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.

It is marked as an exact replication of a resource present on a server.

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

Create an instance from an ID or return an existing instance.

Instance creation is done via cls.new.

id

The identifier associated with this resource.

The true value of the id property comes from the attribute set as id_attribute. For example, a container’s name may be the appropirate identifier, so id_attribute = "name" would be set on the Resource, and Resource.name would be conveniently accessible through id.

is_dirty

True if the resource needs to be updated to the remote.

classmethod create_by_id(session, attrs, resource_id=None, path_args=None)

Create a remote resource from its attributes.

Parameters:
  • session (Session) – The session to use for making this request.
  • attrs (dict) – The attributes to be sent in the body of the request.
  • resource_id – This resource’s identifier, if needed by the request. The default is None.
  • path_args (dict) – A dictionary of arguments to construct a compound URL. See How path_args are used for details.
Returns:

A dict representing the response body.

Raises:

MethodNotSupported if Resource.allow_create is not set to True.

create(session)

Create a remote resource from this instance.

Parameters:session (Session) – The session to use for making this request.
Returns:This Resource instance.
Raises:MethodNotSupported if Resource.allow_create is not set to True.
classmethod get_data_by_id(session, resource_id, path_args=None, include_headers=False)

Get a the attributes of a remote resource from an id.

Parameters:
  • session (Session) – The session to use for making this request.
  • resource_id – This resource’s identifier, if needed by the request. The default is None.
  • path_args (dict) – A dictionary of arguments to construct a compound URL. See How path_args are used for details.
  • include_headers (bool) – True if header data should be included in the response body, False if not.
Returns:

A dict representing the response body.

Raises:

MethodNotSupported if Resource.allow_retrieve is not set to True.

classmethod get_by_id(session, resource_id, path_args=None, include_headers=False)

Get an object representing a remote resource from an id.

Parameters:
  • session (Session) – The session to use for making this request.
  • resource_id – This resource’s identifier, if needed by the request. The default is None.
  • path_args (dict) – A dictionary of arguments to construct a compound URL. See How path_args are used for details.
  • include_headers (bool) – True if header data should be included in the response body, False if not.
Returns:

A Resource object representing the response body.

Raises:

MethodNotSupported if Resource.allow_retrieve is not set to True.

get(session, include_headers=False)

Get the remote resource associated with this instance.

Parameters:session (Session) – The session to use for making this request.
Returns:This Resource instance.
Raises:MethodNotSupported if Resource.allow_retrieve is not set to True.
classmethod head_data_by_id(session, resource_id, path_args=None)

Get a dictionary representing the headers of a remote resource.

Parameters:
  • session (Session) – The session to use for making this request.
  • resource_id – This resource’s identifier, if needed by the request. The default is None.
  • path_args (dict) – A dictionary of arguments to construct a compound URL. See How path_args are used for details.
Returns:

A dict representing the headers.

Raises:

MethodNotSupported if Resource.allow_head is not set to True.

classmethod head_by_id(session, resource_id, path_args=None)

Get an object representing the headers of a remote resource.

Parameters:
  • session (Session) – The session to use for making this request.
  • resource_id – This resource’s identifier, if needed by the request. The default is None.
  • path_args (dict) – A dictionary of arguments to construct a compound URL. See How path_args are used for details.
Returns:

A Resource representing the headers.

Raises:

MethodNotSupported if Resource.allow_head is not set to True.

head(session)

Get the remote resource headers associated with this instance.

Parameters:session (Session) – The session to use for making this request.
Returns:This Resource instance.
Raises:MethodNotSupported if Resource.allow_head is not set to True.
classmethod update_by_id(session, resource_id, attrs, path_args=None)

Update a remote resource with the given attributes.

Parameters:
  • session (Session) – The session to use for making this request.
  • resource_id – This resource’s identifier, if needed by the request. The default is None.
  • attrs (dict) – The attributes to be sent in the body of the request.
  • path_args (dict) – A dictionary of arguments to construct a compound URL. See How path_args are used for details.
Returns:

A dict representing the response body.

Raises:

MethodNotSupported if Resource.allow_update is not set to True.

update(session)

Update the remote resource associated with this instance.

Parameters:session (Session) – The session to use for making this request.
Returns:This Resource instance.
Raises:MethodNotSupported if Resource.allow_update is not set to True.
classmethod delete_by_id(session, resource_id, path_args=None)

Delete a remote resource with the given id.

Parameters:
  • session (Session) – The session to use for making this request.
  • resource_id – This resource’s identifier, if needed by the request. The default is None.
  • path_args (dict) – A dictionary of arguments to construct a compound URL. See How path_args are used for details.
Returns:

None

Raises:

MethodNotSupported if Resource.allow_delete is not set to True.

delete(session)

Delete the remote resource associated with this instance.

Parameters:session (Session) – The session to use for making this request.
Returns:None
Raises:MethodNotSupported if Resource.allow_update is not set to True.
classmethod list(session, limit=None, marker=None, path_args=None, **params)

Get a response that is a list of potentially paginated objects.

This method starts at limit and marker (both defaulting to None), advances the marker to the last item received in each response, and continues making requests for more resources until no results are returned.

Parameters:
  • session (Session) – The session to use for making this request.
  • limit – The maximum amount of results to retrieve. The default is None, which means no limit will be set, and the underlying API will return its default amount of responses.
  • marker – The position in the list to begin requests from. The type of value to use for marker depends on the API being called.
  • path_args (dict) – A dictionary of arguments to construct a compound URL. See How path_args are used for details.
  • params (dict) – Parameters to be passed into the underlying get() method.
Returns:

A generator of Resource objects.

Raises:

MethodNotSupported if Resource.allow_list is not set to True.

classmethod page(session, limit, marker=None, path_args=None, **params)

Get a one page response.

This method gets starting at marker with a maximum of limit records.

Parameters:
  • session (Session) – The session to use for making this request.
  • limit – The maximum amount of results to retrieve.
  • marker – The position in the list to begin requests from. The type of value to use for marker depends on the API being called.
  • path_args (dict) – A dictionary of arguments to construct a compound URL. See How path_args are used for details.
  • params (dict) – Parameters to be passed into the underlying get() method.
Returns:

An array of Resource objects.

classmethod find(session, name_or_id, path_args=None)

Find a resource by its name or id.

Parameters:
  • session (Session) – The session to use for making this request.
  • resource_id – This resource’s identifier, if needed by the request. The default is None.
  • path_args (dict) – A dictionary of arguments to construct a compound URL. See How path_args are used for details.
Returns:

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

How path_args are used

As Resources often contain compound Resource.base_paths, meaning the path is constructed from more than just that string, the various request methods need a way to fill in the missing parts. That’s where path_args come in.

For example:

class ServerIP(resource.Resource):
    base_path = "/servers/%(server_id)s/ips"

Making a GET request to obtain server IPs requires the ID of the server to check. This is handled by passing {"server_id": "12345"} as the path_args argument when calling Resource.get_by_id(). From there, the method uses Python’s string interpolation to fill in the server_id piece of the URL, and then makes the request.

Table Of Contents

Previous topic

Identity v3 Authorization Plugin

Next topic

ServiceFilter

This Page