Resources reference

Resource model

The models defined in this file represent the resource JSON description format and provide a layer of abstraction from the raw JSON. The advantages of this are:

  • Pythonic interface (e.g. action.request.operation)
  • Consumers need not change for minor JSON changes (e.g. renamed field)

These models are used both by the resource factory to generate resource classes as well as by the documentation generator.

class ibm_boto3.resources.model.Action(name, definition, resource_defs)[source]

A service operation action.

Parameters
  • name (string) -- The name of the action
  • definition (dict) -- The JSON definition
  • resource_defs (dict) -- All resources defined in the service
class ibm_boto3.resources.model.Collection(name, definition, resource_defs)[source]

A group of resources. See Action.

Parameters
  • name (string) -- The name of the collection
  • definition (dict) -- The JSON definition
  • resource_defs (dict) -- All resources defined in the service
batch_actions[source]

Get a list of batch actions supported by the resource type contained in this action. This is a shortcut for accessing the same information through the resource model.

Return type
list(Action)
class ibm_boto3.resources.model.DefinitionWithParams(definition)[source]

An item which has parameters exposed via the params property. A request has an operation and parameters, while a waiter has a name, a low-level waiter name and parameters.

Parameters
definition (dict) -- The JSON definition
params[source]

Get a list of auto-filled parameters for this request.

Type
list(Parameter)
class ibm_boto3.resources.model.Identifier(name, member_name=None)[source]

A resource identifier, given by its name.

Parameters
name (string) -- The name of the identifier
class ibm_boto3.resources.model.Parameter(target, source, name=None, path=None, value=None, **kwargs)[source]

An auto-filled parameter which has a source and target. For example, the QueueUrl may be auto-filled from a resource's url identifier when making calls to queue.receive_messages.

Parameters
  • target (string) -- The destination parameter name, e.g. QueueUrl
  • source_type (string) -- Where the source is defined.
  • source (string) -- The source name, e.g. Url
class ibm_boto3.resources.model.Request(definition)[source]

A service operation action request.

Parameters
definition (dict) -- The JSON definition
params

Get a list of auto-filled parameters for this request.

Type
list(Parameter)
class ibm_boto3.resources.model.ResourceModel(name, definition, resource_defs)[source]

A model representing a resource, defined via a JSON description format. A resource has identifiers, attributes, actions, sub-resources, references and collections. For more information on resources, see guide_resources.

Parameters
  • name (string) -- The name of this resource, e.g. sqs or Queue
  • definition (dict) -- The JSON definition
  • resource_defs (dict) -- All resources defined in the service
actions[source]

Get a list of actions for this resource.

Type
list(Action)
batch_actions[source]

Get a list of batch actions for this resource.

Type
list(Action)
collections[source]

Get a list of collections for this resource.

Type
list(Collection)
get_attributes(shape)[source]

Get a dictionary of attribute names to original name and shape models that represent the attributes of this resource. Looks like the following:

{
'some_name': ('SomeName', <Shape...>)

}

Parameters
shape (ibm_botocore.model.Shape) -- The underlying shape for this resource.
Return type
dict
Returns
Mapping of resource attributes.
identifiers[source]

Get a list of resource identifiers.

Type
list(Identifier)
load[source]

Get the load action for this resource, if it is defined.

Type
Action or None
load_rename_map(shape=None)[source]

Load a name translation map given a shape. This will set up renamed values for any collisions, e.g. if the shape, an action, and a subresource all are all named foo then the resource will have an action foo, a subresource named Foo and a property named foo_attribute. This is the order of precedence, from most important to least important:

  • Load action (resource.load)
  • Identifiers
  • Actions
  • Subresources
  • References
  • Collections
  • Waiters
  • Attributes (shape members)

Batch actions are only exposed on collections, so do not get modified here. Subresources use upper camel casing, so are unlikely to collide with anything but other subresources.

Creates a structure like this:

renames = {
    ('action', 'id'): 'id_action',
    ('collection', 'id'): 'id_collection',
    ('attribute', 'id'): 'id_attribute'
}

# Get the final name for an action named 'id'
name = renames.get(('action', 'id'), 'id')
Parameters
shape (ibm_botocore.model.Shape) -- The underlying shape for this resource.
references[source]

Get a list of reference resources.

Type
list(Action)
subresources[source]

Get a list of sub-resources.

Type
list(Action)
waiters[source]

Get a list of waiters for this resource.

Type
list(Waiter)
class ibm_boto3.resources.model.ResponseResource(definition, resource_defs)[source]

A resource response to create after performing an action.

Parameters
  • definition (dict) -- The JSON definition
  • resource_defs (dict) -- All resources defined in the service
identifiers[source]

A list of resource identifiers.

Type
list(Identifier)
model[source]

Get the resource model for the response resource.

Type
ResourceModel
class ibm_boto3.resources.model.Waiter(name, definition)[source]

An event waiter specification.

Parameters
  • name (string) -- Name of the waiter
  • definition (dict) -- The JSON definition
PREFIX = 'WaitUntil'
params

Get a list of auto-filled parameters for this request.

Type
list(Parameter)

Request parameters

ibm_boto3.resources.params.build_param_structure(params, target, value, index=None)[source]

This method provides a basic reverse JMESPath implementation that lets you go from a JMESPath-like string to a possibly deeply nested object. The params are mutated in-place, so subsequent calls can modify the same element by its index.

>>> build_param_structure(params, 'test[0]', 1)
>>> print(params)
{'test': [1]}
>>> build_param_structure(params, 'foo.bar[0].baz', 'hello world')
>>> print(params)
{'test': [1], 'foo': {'bar': [{'baz': 'hello, world'}]}}
ibm_boto3.resources.params.create_request_parameters(parent, request_model, params=None, index=None)[source]

Handle request parameters that can be filled in from identifiers, resource data members or constants.

By passing params, you can invoke this method multiple times and build up a parameter dict over time, which is particularly useful for reverse JMESPath expressions that append to lists.

Parameters
  • parent (ServiceResource) -- The resource instance to which this action is attached.
  • request_model (Request) -- The action request model.
  • params (dict) -- If set, then add to this existing dict. It is both edited in-place and returned.
  • index (int) -- The position of an item within a list
Return type

dict

Returns

Pre-filled parameters to be sent to the request operation.

ibm_boto3.resources.params.get_data_member(parent, path)[source]

Get a data member from a parent using a JMESPath search query, loading the parent if required. If the parent cannot be loaded and no data is present then an exception is raised.

Parameters
  • parent (ServiceResource) -- The resource instance to which contains data we are interested in.
  • path (string) -- The JMESPath expression to query
Raises ResourceLoadException

When no data is present and the resource cannot be loaded.

Returns

The queried data or None.

Response handlers

class ibm_boto3.resources.response.RawHandler(search_path)[source]

A raw action response handler. This passed through the response dictionary, optionally after performing a JMESPath search if one has been defined for the action.

Parameters
search_path (string) -- JMESPath expression to search in the response
Return type
dict
Returns
Service response
class ibm_boto3.resources.response.ResourceHandler(search_path, factory, resource_model, service_context, operation_name=None)[source]

Creates a new resource or list of new resources from the low-level response based on the given response resource definition.

Parameters
  • search_path (string) -- JMESPath expression to search in the response
  • factory (ResourceFactory) -- The factory that created the resource class to which this action is attached.
  • resource_model (ResponseResource) -- Response resource model.
  • service_context (ServiceContext) -- Context about the AWS service
  • operation_name (string) -- Name of the underlying service operation, if it exists.
Return type

ServiceResource or list

Returns

New resource instance(s).

handle_response_item(resource_cls, parent, identifiers, resource_data)[source]

Handles the creation of a single response item by setting parameters and creating the appropriate resource instance.

Parameters
  • resource_cls (ServiceResource subclass) -- The resource class to instantiate.
  • parent (ServiceResource) -- The resource instance to which this action is attached.
  • identifiers (dict) -- Map of identifier names to value or values.
  • resource_data (dict or None) -- Data for resource attributes.
Return type

ServiceResource

Returns

New resource instance.

ibm_boto3.resources.response.all_not_none(iterable)[source]

Return True if all elements of the iterable are not None (or if the iterable is empty). This is like the built-in all, except checks against None, so 0 and False are allowable values.

ibm_boto3.resources.response.build_empty_response(search_path, operation_name, service_model)[source]

Creates an appropriate empty response for the type that is expected, based on the service model's shape type. For example, a value that is normally a list would then return an empty list. A structure would return an empty dict, and a number would return None.

Parameters
  • search_path (string) -- JMESPath expression to search in the response
  • operation_name (string) -- Name of the underlying service operation.
  • service_model (ibm_botocore.model.ServiceModel) -- The Botocore service model
Return type

dict, list, or None

Returns

An appropriate empty value

ibm_boto3.resources.response.build_identifiers(identifiers, parent, params=None, raw_response=None)[source]

Builds a mapping of identifier names to values based on the identifier source location, type, and target. Identifier values may be scalars or lists depending on the source type and location.

Parameters
  • identifiers (list) -- List of Parameter definitions
  • parent (ServiceResource) -- The resource instance to which this action is attached.
  • params (dict) -- Request parameters sent to the service.
  • raw_response (dict) -- Low-level operation response.
Return type

list

Returns

An ordered list of (name, value) identifier tuples.

Resource actions

class ibm_boto3.resources.action.BatchAction(action_model, factory=None, service_context=None)[source]

An action which operates on a batch of items in a collection, typically a single page of results from the collection's underlying service operation call. For example, this allows you to delete up to 999 S3 objects in a single operation rather than calling .delete() on each one individually.

Parameters
  • action_model (:py:class`~ibm_boto3.resources.model.Action`) -- The action model.
  • factory (ResourceFactory) -- The factory that created the resource class to which this action is attached.
  • service_context (ServiceContext) -- Context about the AWS service
class ibm_boto3.resources.action.CustomModeledAction(action_name, action_model, function, event_emitter)[source]

A custom, modeled action to inject into a resource.

Parameters
  • action_name (str) -- The name of the action to inject, e.g. 'delete_tags'
  • action_model (dict) -- A JSON definition of the action, as if it were part of the resource model.
  • function (function) -- The function to perform when the action is called. The first argument should be 'self', which will be the resource the function is to be called on.
  • event_emitter (ibm_botocore.hooks.BaseEventHooks) -- The session event emitter.
inject(class_attributes, service_context, event_name, **kwargs)[source]
class ibm_boto3.resources.action.ServiceAction(action_model, factory=None, service_context=None)[source]

A class representing a callable action on a resource, for example sqs.get_queue_by_name(...) or s3.Bucket('foo').delete(). The action may construct parameters from existing resource identifiers and may return either a raw response or a new resource instance.

Parameters
  • action_model (:py:class`~ibm_boto3.resources.model.Action`) -- The action model.
  • factory (ResourceFactory) -- The factory that created the resource class to which this action is attached.
  • service_context (ServiceContext) -- Context about the AWS service
class ibm_boto3.resources.action.WaiterAction(waiter_model, waiter_resource_name)[source]

A class representing a callable waiter action on a resource, for example s3.Bucket('foo').wait_until_bucket_exists(). The waiter action may construct parameters from existing resource identifiers.

Parameters
  • waiter_model (:py:class`~ibm_boto3.resources.model.Waiter`) -- The action waiter.
  • waiter_resource_name (string) -- The name of the waiter action for the resource. It usually begins with a wait_until_

Resource base

class ibm_boto3.resources.base.ResourceMeta(service_name, identifiers=None, client=None, data=None, resource_model=None)[source]

An object containing metadata about a resource.

copy()[source]

Create a copy of this metadata object.

class ibm_boto3.resources.base.ServiceResource(*args, **kwargs)[source]

A base class for resources.

Parameters
client (ibm_botocore.client) -- A low-level Botocore client instance
meta = None

Resource factory

class ibm_boto3.resources.factory.ResourceFactory(emitter)[source]

A factory to create new ServiceResource classes from a ResourceModel. There are two types of lookups that can be done: one on the service itself (e.g. an SQS resource) and another on models contained within the service (e.g. an SQS Queue resource).

load_from_definition(resource_name, single_resource_json_definition, service_context)[source]

Loads a resource from a model, creating a new ServiceResource subclass with the correct properties and methods, named based on the service and resource name, e.g. EC2.Instance.

Parameters
  • resource_name (string) -- Name of the resource to look up. For services, this should match the service_name.
  • single_resource_json_definition (dict) -- The loaded json of a single service resource or resource definition.
  • service_context (ServiceContext) -- Context about the AWS service
Return type

Subclass of ServiceResource

Returns

The service or resource class.