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.
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
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: |
|
---|
Singular form of key for resource.
Common name for resource.
Plural form of key for resource.
Attribute key associated with the id for this resource.
Attribute key associated with the name for this resource.
The base part of the url for this resource.
The service associated with this resource to find the service URL.
Allow create operation for this resource.
Allow retrieve/get operation for this resource.
Allow update operation for this resource.
Allow delete operation for this resource.
Allow list operation for this resource.
Allow head operation for this resource.
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. |
---|
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. |
---|
Create an instance from an ID or return an existing instance.
Instance creation is done via cls.new.
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.
True if the resource needs to be updated to the remote.
Create a remote resource from its attributes.
Parameters: |
|
---|---|
Returns: | A dict representing the response body. |
Raises: | MethodNotSupported if Resource.allow_create is not set to True. |
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. |
Get a the attributes of a remote resource from an id.
Parameters: |
|
---|---|
Returns: | A dict representing the response body. |
Raises: | MethodNotSupported if Resource.allow_retrieve is not set to True. |
Get an object representing a remote resource from an id.
Parameters: |
|
---|---|
Returns: | A Resource object representing the response body. |
Raises: | MethodNotSupported if Resource.allow_retrieve is not set to True. |
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. |
Get a dictionary representing the headers of a remote resource.
Parameters: |
|
---|---|
Returns: | A dict representing the headers. |
Raises: | MethodNotSupported if Resource.allow_head is not set to True. |
Get an object representing the headers of a remote resource.
Parameters: |
|
---|---|
Returns: | A Resource representing the headers. |
Raises: | MethodNotSupported if Resource.allow_head is not set to True. |
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. |
Update a remote resource with the given attributes.
Parameters: |
|
---|---|
Returns: | A dict representing the response body. |
Raises: | MethodNotSupported if Resource.allow_update is not set to True. |
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. |
Delete a remote resource with the given id.
Parameters: |
|
---|---|
Returns: | None |
Raises: | MethodNotSupported if Resource.allow_delete is not set to True. |
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. |
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: |
|
---|---|
Returns: | A generator of Resource objects. |
Raises: | MethodNotSupported if Resource.allow_list is not set to True. |
Get a one page response.
This method gets starting at marker with a maximum of limit records.
Parameters: |
|
---|---|
Returns: | An array of Resource objects. |
Find a resource by its name or id.
Parameters: |
|
---|---|
Returns: | The Resource object matching the given name or id or None if nothing matches. |
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.