Resources reference - Boto3 1.38.12 documentation (original) (raw)

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:

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

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

A service operation action.

Parameters:

name

(string) The name of the action

path

(string) The JMESPath search path or None

request

(Request) This action’s request or None

resource

(ResponseResource) This action’s resource or None

class boto3.resources.model.Collection(name, definition, resource_defs)[source]

A group of resources. See Action.

Parameters:

property batch_actions

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)

name

(string) The name of the action

path

(string) The JMESPath search path or None

request

(Request) This action’s request or None

resource

(ResponseResource) This action’s resource or None

class 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

property params

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

Type:

list(Parameter)

class boto3.resources.model.Identifier(name, member_name=None)[source]

A resource identifier, given by its name.

Parameters:

name (string) – The name of the identifier

name

(string) The name of the identifier

class 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:

name

(string) The name of the source, if given

path

(string) The JMESPath query of the source

source

(string) Where the source is defined

target

(string) The destination parameter name

value

(string|int|float|bool) The source constant value

class boto3.resources.model.Request(definition)[source]

A service operation action request.

Parameters:

definition (dict) – The JSON definition

operation

(string) The name of the low-level service operation

property params

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

Type:

list(Parameter)

class 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 Resources.

Parameters:

property actions

Get a list of actions for this resource.

Type:

list(Action)

property batch_actions

Get a list of batch actions for this resource.

Type:

list(Action)

property collections

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 (botocore.model.Shape) – The underlying shape for this resource.

Return type:

dict

Returns:

Mapping of resource attributes.

property identifiers

Get a list of resource identifiers.

Type:

list(Identifier)

property load

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 foothen 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:

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 (botocore.model.Shape) – The underlying shape for this resource.

name

(string) The name of this resource

property references

Get a list of reference resources.

Type:

list(Action)

shape

(string) The service shape name for this resource or None

property subresources

Get a list of sub-resources.

Type:

list(Action)

property waiters

Get a list of waiters for this resource.

Type:

list(Waiter)

class boto3.resources.model.ResponseResource(definition, resource_defs)[source]

A resource response to create after performing an action.

Parameters:

property identifiers

A list of resource identifiers.

Type:

list(Identifier)

property model

Get the resource model for the response resource.

Type:

ResourceModel

path

(string) The JMESPath search query or None

type

(string) The name of the response resource type

class boto3.resources.model.Waiter(name, definition)[source]

An event waiter specification.

Parameters:

PREFIX = 'WaitUntil'

name

(string) The name of this waiter

property params

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

Type:

list(Parameter)

waiter_name

(string) The name of the underlying event waiter

Request parameters

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'}]}}

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:

Return type:

dict

Returns:

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

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:

Raises:

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

Returns:

The queried data or None.

Response handlers

class 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 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:

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:

Return type:

ServiceResource

Returns:

New resource instance.

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.

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:

Return type:

dict, list, or None

Returns:

An appropriate empty value

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:

Return type:

list

Returns:

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

Resource actions

class 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:

class boto3.resources.action.CustomModeledAction(action_name, action_model, function, event_emitter)[source]

A custom, modeled action to inject into a resource.

Parameters:

inject(class_attributes, service_context, event_name, **kwargs)[source]

class boto3.resources.action.ServiceAction(action_model, factory=None, service_context=None)[source]

A class representing a callable action on a resource, for examplesqs.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:

class boto3.resources.action.WaiterAction(waiter_model, waiter_resource_name)[source]

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

Parameters:

Resource base

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

An object containing metadata about a resource.

client

(BaseClient) Low-level Botocore client

copy()[source]

Create a copy of this metadata object.

data

(dict) Loaded resource data attributes

identifiers

(list) List of identifier names

service_name

(string) The service name, e.g. ‘s3’

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

A base class for resources.

Parameters:

client (botocore.client) – A low-level Botocore client instance

meta = None

Stores metadata about this resource instance, such as theservice_name, the low-level client and any cached datafrom when the instance was hydrated. For example:

Get a low-level client from a resource instance

client = resource.meta.client response = client.operation(Param='foo')

Print the resource instance's service short name

print(resource.meta.service_name)

See ResourceMeta for more information.

Resource factory

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

A factory to create new ServiceResourceclasses 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 newServiceResource subclass with the correct properties and methods, named based on the service and resource name, e.g. EC2.Instance.

Parameters:

Return type:

Subclass of ServiceResource

Returns:

The service or resource class.