Note

You are viewing the documentation for an older version of boto (boto2).

Boto3, the next version of Boto, is now stable and recommended for general use. It can be used side-by-side with Boto in the same project, so it is easy to start using Boto3 in your existing projects as well as new projects. Going forward, API updates and all new feature work will be focused on Boto3.

For more information, see the documentation for boto3.

DynamoDB

boto.dynamodb

boto.dynamodb.connect_to_region(region_name, **kw_params)
boto.dynamodb.regions()

Get all available regions for the Amazon DynamoDB service.

Return type:list
Returns:A list of boto.regioninfo.RegionInfo

boto.dynamodb.layer1

class boto.dynamodb.layer1.Layer1(aws_access_key_id=None, aws_secret_access_key=None, is_secure=True, port=None, proxy=None, proxy_port=None, debug=0, security_token=None, region=None, validate_certs=True, validate_checksums=True, profile_name=None)

This is the lowest-level interface to DynamoDB. Methods at this layer map directly to API requests and parameters to the methods are either simple, scalar values or they are the Python equivalent of the JSON input as defined in the DynamoDB Developer’s Guide. All responses are direct decoding of the JSON response bodies to Python data structures via the json or simplejson modules.

Variables:throughput_exceeded_events – An integer variable that keeps a running total of the number of ThroughputExceeded responses this connection has received from Amazon DynamoDB.
ConditionalCheckFailedError = 'ConditionalCheckFailedException'

The error response returned when a conditional check fails

DefaultRegionName = 'us-east-1'

The default region name for DynamoDB API.

NumberRetries = 10

The number of times an error is retried.

ResponseError

alias of boto.exception.DynamoDBResponseError

ServiceName = 'DynamoDB'

The name of the Service

SessionExpiredError = 'com.amazon.coral.service#ExpiredTokenException'

The error response returned when session token has expired

ThruputError = 'ProvisionedThroughputExceededException'

The error response returned when provisioned throughput is exceeded

ValidationError = 'ValidationException'

The error response returned when an item is invalid in some way

Version = '20111205'

DynamoDB API version.

batch_get_item(request_items, object_hook=None)

Return a set of attributes for a multiple items in multiple tables using their primary keys.

Parameters:request_items (dict) – A Python version of the RequestItems data structure defined by DynamoDB.
batch_write_item(request_items, object_hook=None)

This operation enables you to put or delete several items across multiple tables in a single API call.

Parameters:request_items (dict) – A Python version of the RequestItems data structure defined by DynamoDB.
create_table(table_name, schema, provisioned_throughput)

Add a new table to your account. The table name must be unique among those associated with the account issuing the request. This request triggers an asynchronous workflow to begin creating the table. When the workflow is complete, the state of the table will be ACTIVE.

Parameters:
  • table_name (str) – The name of the table to create.
  • schema (dict) – A Python version of the KeySchema data structure as defined by DynamoDB
  • provisioned_throughput (dict) – A Python version of the ProvisionedThroughput data structure defined by DynamoDB.
delete_item(table_name, key, expected=None, return_values=None, object_hook=None)

Delete an item and all of it’s attributes by primary key. You can perform a conditional delete by specifying an expected rule.

Parameters:
  • table_name (str) – The name of the table containing the item.
  • key (dict) – A Python version of the Key data structure defined by DynamoDB.
  • expected (dict) – A Python version of the Expected data structure defined by DynamoDB.
  • return_values (str) – Controls the return of attribute name-value pairs before then were changed. Possible values are: None or ‘ALL_OLD’. If ‘ALL_OLD’ is specified and the item is overwritten, the content of the old item is returned.
delete_table(table_name)

Deletes the table and all of it’s data. After this request the table will be in the DELETING state until DynamoDB completes the delete operation.

Parameters:table_name (str) – The name of the table to delete.
describe_table(table_name)

Returns information about the table including current state of the table, primary key schema and when the table was created.

Parameters:table_name (str) – The name of the table to describe.
get_item(table_name, key, attributes_to_get=None, consistent_read=False, object_hook=None)

Return a set of attributes for an item that matches the supplied key.

Parameters:
  • table_name (str) – The name of the table containing the item.
  • key (dict) – A Python version of the Key data structure defined by DynamoDB.
  • attributes_to_get (list) – A list of attribute names. If supplied, only the specified attribute names will be returned. Otherwise, all attributes will be returned.
  • consistent_read (bool) – If True, a consistent read request is issued. Otherwise, an eventually consistent request is issued.
list_tables(limit=None, start_table=None)

Returns a dictionary of results. The dictionary contains a TableNames key whose value is a list of the table names. The dictionary could also contain a LastEvaluatedTableName key whose value would be the last table name returned if the complete list of table names was not returned. This value would then be passed as the start_table parameter on a subsequent call to this method.

Parameters:
  • limit (int) – The maximum number of tables to return.
  • start_table (str) – The name of the table that starts the list. If you ran a previous list_tables and not all results were returned, the response dict would include a LastEvaluatedTableName attribute. Use that value here to continue the listing.
make_request(action, body='', object_hook=None)
Raises:DynamoDBExpiredTokenError if the security token expires.
put_item(table_name, item, expected=None, return_values=None, object_hook=None)

Create a new item or replace an old item with a new item (including all attributes). If an item already exists in the specified table with the same primary key, the new item will completely replace the old item. You can perform a conditional put by specifying an expected rule.

Parameters:
  • table_name (str) – The name of the table in which to put the item.
  • item (dict) – A Python version of the Item data structure defined by DynamoDB.
  • expected (dict) – A Python version of the Expected data structure defined by DynamoDB.
  • return_values (str) – Controls the return of attribute name-value pairs before then were changed. Possible values are: None or ‘ALL_OLD’. If ‘ALL_OLD’ is specified and the item is overwritten, the content of the old item is returned.
query(table_name, hash_key_value, range_key_conditions=None, attributes_to_get=None, limit=None, consistent_read=False, scan_index_forward=True, exclusive_start_key=None, object_hook=None, count=False)

Perform a query of DynamoDB. This version is currently punting and expecting you to provide a full and correct JSON body which is passed as is to DynamoDB.

Parameters:
  • table_name (str) – The name of the table to query.
  • key – A DynamoDB-style HashKeyValue.
  • range_key_conditions (dict) – A Python version of the RangeKeyConditions data structure.
  • attributes_to_get (list) – A list of attribute names. If supplied, only the specified attribute names will be returned. Otherwise, all attributes will be returned.
  • limit (int) – The maximum number of items to return.
  • count (bool) – If True, Amazon DynamoDB returns a total number of items for the Query operation, even if the operation has no matching items for the assigned filter.
  • consistent_read (bool) – If True, a consistent read request is issued. Otherwise, an eventually consistent request is issued.
  • scan_index_forward (bool) – Specified forward or backward traversal of the index. Default is forward (True).
  • exclusive_start_key (list or tuple) – Primary key of the item from which to continue an earlier query. This would be provided as the LastEvaluatedKey in that query.
scan(table_name, scan_filter=None, attributes_to_get=None, limit=None, exclusive_start_key=None, object_hook=None, count=False)

Perform a scan of DynamoDB. This version is currently punting and expecting you to provide a full and correct JSON body which is passed as is to DynamoDB.

Parameters:
  • table_name (str) – The name of the table to scan.
  • scan_filter (dict) – A Python version of the ScanFilter data structure.
  • attributes_to_get (list) – A list of attribute names. If supplied, only the specified attribute names will be returned. Otherwise, all attributes will be returned.
  • limit (int) – The maximum number of items to evaluate.
  • count (bool) – If True, Amazon DynamoDB returns a total number of items for the Scan operation, even if the operation has no matching items for the assigned filter.
  • exclusive_start_key (list or tuple) – Primary key of the item from which to continue an earlier query. This would be provided as the LastEvaluatedKey in that query.
update_item(table_name, key, attribute_updates, expected=None, return_values=None, object_hook=None)

Edits an existing item’s attributes. You can perform a conditional update (insert a new attribute name-value pair if it doesn’t exist, or replace an existing name-value pair if it has certain expected attribute values).

Parameters:
  • table_name (str) – The name of the table.
  • key (dict) – A Python version of the Key data structure defined by DynamoDB which identifies the item to be updated.
  • attribute_updates (dict) – A Python version of the AttributeUpdates data structure defined by DynamoDB.
  • expected (dict) – A Python version of the Expected data structure defined by DynamoDB.
  • return_values (str) – Controls the return of attribute name-value pairs before then were changed. Possible values are: None or ‘ALL_OLD’. If ‘ALL_OLD’ is specified and the item is overwritten, the content of the old item is returned.
update_table(table_name, provisioned_throughput)

Updates the provisioned throughput for a given table.

Parameters:
  • table_name (str) – The name of the table to update.
  • provisioned_throughput (dict) – A Python version of the ProvisionedThroughput data structure defined by DynamoDB.

boto.dynamodb.layer2

class boto.dynamodb.layer2.Layer2(aws_access_key_id=None, aws_secret_access_key=None, is_secure=True, port=None, proxy=None, proxy_port=None, debug=0, security_token=None, region=None, validate_certs=True, dynamizer=<class 'boto.dynamodb.types.LossyFloatDynamizer'>, profile_name=None)
batch_get_item(batch_list)

Return a set of attributes for a multiple items in multiple tables using their primary keys.

Parameters:batch_list (boto.dynamodb.batch.BatchList) – A BatchList object which consists of a list of boto.dynamoddb.batch.Batch objects. Each Batch object contains the information about one batch of objects that you wish to retrieve in this request.
batch_write_item(batch_list)

Performs multiple Puts and Deletes in one batch.

Parameters:batch_list (boto.dynamodb.batch.BatchWriteList) – A BatchWriteList object which consists of a list of boto.dynamoddb.batch.BatchWrite objects. Each Batch object contains the information about one batch of objects that you wish to put or delete.
build_key_from_values(schema, hash_key, range_key=None)

Build a Key structure to be used for accessing items in Amazon DynamoDB. This method takes the supplied hash_key and optional range_key and validates them against the schema. If there is a mismatch, a TypeError is raised. Otherwise, a Python dict version of a Amazon DynamoDB Key data structure is returned.

Parameters:
  • hash_key (int|float|str|unicode|Binary) – The hash key of the item you are looking for. The type of the hash key should match the type defined in the schema.
  • range_key (int|float|str|unicode|Binary) – The range key of the item your are looking for. This should be supplied only if the schema requires a range key. The type of the range key should match the type defined in the schema.
create_schema(hash_key_name, hash_key_proto_value, range_key_name=None, range_key_proto_value=None)

Create a Schema object used when creating a Table.

Parameters:
  • hash_key_name (str) – The name of the HashKey for the schema.
  • hash_key_proto_value (int|long|float|str|unicode|Binary) – A sample or prototype of the type of value you want to use for the HashKey. Alternatively, you can also just pass in the Python type (e.g. int, float, etc.).
  • range_key_name (str) – The name of the RangeKey for the schema. This parameter is optional.
  • range_key_proto_value (int|long|float|str|unicode|Binary) – A sample or prototype of the type of value you want to use for the RangeKey. Alternatively, you can also pass in the Python type (e.g. int, float, etc.) This parameter is optional.
create_table(name, schema, read_units, write_units)

Create a new Amazon DynamoDB table.

Parameters:
  • name (str) – The name of the desired table.
  • schema (boto.dynamodb.schema.Schema) – The Schema object that defines the schema used by this table.
  • read_units (int) – The value for ReadCapacityUnits.
  • write_units (int) – The value for WriteCapacityUnits.
Return type:

boto.dynamodb.table.Table

Returns:

A Table object representing the new Amazon DynamoDB table.

delete_item(item, expected_value=None, return_values=None)

Delete the item from Amazon DynamoDB.

Parameters:
  • item (boto.dynamodb.item.Item) – The Item to delete from Amazon DynamoDB.
  • expected_value (dict) – A dictionary of name/value pairs that you expect. This dictionary should have name/value pairs where the name is the name of the attribute and the value is either the value you are expecting or False if you expect the attribute not to exist.
  • return_values (str) – Controls the return of attribute name-value pairs before then were changed. Possible values are: None or ‘ALL_OLD’. If ‘ALL_OLD’ is specified and the item is overwritten, the content of the old item is returned.
delete_table(table)

Delete this table and all items in it. After calling this the Table objects status attribute will be set to ‘DELETING’.

Parameters:table (boto.dynamodb.table.Table) – The Table object that is being deleted.
describe_table(name)

Retrieve information about an existing table.

Parameters:name (str) – The name of the desired table.
dynamize_attribute_updates(pending_updates)

Convert a set of pending item updates into the structure required by Layer1.

dynamize_expected_value(expected_value)

Convert an expected_value parameter into the data structure required for Layer1.

dynamize_item(item)
dynamize_last_evaluated_key(last_evaluated_key)

Convert a last_evaluated_key parameter into the data structure required for Layer1.

dynamize_range_key_condition(range_key_condition)

Convert a layer2 range_key_condition parameter into the structure required by Layer1.

dynamize_scan_filter(scan_filter)

Convert a layer2 scan_filter parameter into the structure required by Layer1.

get_item(table, hash_key, range_key=None, attributes_to_get=None, consistent_read=False, item_class=<class 'boto.dynamodb.item.Item'>)

Retrieve an existing item from the table.

Parameters:
  • table (boto.dynamodb.table.Table) – The Table object from which the item is retrieved.
  • hash_key (int|long|float|str|unicode|Binary) – The HashKey of the requested item. The type of the value must match the type defined in the schema for the table.
  • range_key (int|long|float|str|unicode|Binary) – The optional RangeKey of the requested item. The type of the value must match the type defined in the schema for the table.
  • attributes_to_get (list) – A list of attribute names. If supplied, only the specified attribute names will be returned. Otherwise, all attributes will be returned.
  • consistent_read (bool) – If True, a consistent read request is issued. Otherwise, an eventually consistent request is issued.
  • item_class (Class) – Allows you to override the class used to generate the items. This should be a subclass of boto.dynamodb.item.Item
get_table(name)

Retrieve the Table object for an existing table.

Parameters:name (str) – The name of the desired table.
Return type:boto.dynamodb.table.Table
Returns:A Table object representing the table.
list_tables(limit=None)

Return a list of the names of all tables associated with the current account and region.

Parameters:limit (int) – The maximum number of tables to return.
lookup(name)

Retrieve the Table object for an existing table.

Parameters:name (str) – The name of the desired table.
Return type:boto.dynamodb.table.Table
Returns:A Table object representing the table.
new_batch_list()

Return a new, empty boto.dynamodb.batch.BatchList object.

new_batch_write_list()

Return a new, empty boto.dynamodb.batch.BatchWriteList object.

put_item(item, expected_value=None, return_values=None)

Store a new item or completely replace an existing item in Amazon DynamoDB.

Parameters:
  • item (boto.dynamodb.item.Item) – The Item to write to Amazon DynamoDB.
  • expected_value (dict) – A dictionary of name/value pairs that you expect. This dictionary should have name/value pairs where the name is the name of the attribute and the value is either the value you are expecting or False if you expect the attribute not to exist.
  • return_values (str) – Controls the return of attribute name-value pairs before then were changed. Possible values are: None or ‘ALL_OLD’. If ‘ALL_OLD’ is specified and the item is overwritten, the content of the old item is returned.
query(table, hash_key, range_key_condition=None, attributes_to_get=None, request_limit=None, max_results=None, consistent_read=False, scan_index_forward=True, exclusive_start_key=None, item_class=<class 'boto.dynamodb.item.Item'>, count=False)

Perform a query on the table.

Parameters:
  • table (boto.dynamodb.table.Table) – The Table object that is being queried.
  • hash_key (int|long|float|str|unicode|Binary) – The HashKey of the requested item. The type of the value must match the type defined in the schema for the table.
  • range_key_condition (boto.dynamodb.condition.Condition) –

    A Condition object. Condition object can be one of the following types:

    EQ|LE|LT|GE|GT|BEGINS_WITH|BETWEEN

    The only condition which expects or will accept two values is ‘BETWEEN’, otherwise a single value should be passed to the Condition constructor.

  • attributes_to_get (list) – A list of attribute names. If supplied, only the specified attribute names will be returned. Otherwise, all attributes will be returned.
  • request_limit (int) – The maximum number of items to retrieve from Amazon DynamoDB on each request. You may want to set a specific request_limit based on the provisioned throughput of your table. The default behavior is to retrieve as many results as possible per request.
  • max_results (int) – The maximum number of results that will be retrieved from Amazon DynamoDB in total. For example, if you only wanted to see the first 100 results from the query, regardless of how many were actually available, you could set max_results to 100 and the generator returned from the query method will only yeild 100 results max.
  • consistent_read (bool) – If True, a consistent read request is issued. Otherwise, an eventually consistent request is issued.
  • scan_index_forward (bool) – Specified forward or backward traversal of the index. Default is forward (True).
  • count (bool) – If True, Amazon DynamoDB returns a total number of items for the Query operation, even if the operation has no matching items for the assigned filter. If count is True, the actual items are not returned and the count is accessible as the count attribute of the returned object.
  • exclusive_start_key (list or tuple) – Primary key of the item from which to continue an earlier query. This would be provided as the LastEvaluatedKey in that query.
  • item_class (Class) – Allows you to override the class used to generate the items. This should be a subclass of boto.dynamodb.item.Item
Return type:

boto.dynamodb.layer2.TableGenerator

scan(table, scan_filter=None, attributes_to_get=None, request_limit=None, max_results=None, exclusive_start_key=None, item_class=<class 'boto.dynamodb.item.Item'>, count=False)

Perform a scan of DynamoDB.

Parameters:
  • table (boto.dynamodb.table.Table) – The Table object that is being scanned.
  • scan_filter (A dict) –

    A dictionary where the key is the attribute name and the value is a boto.dynamodb.condition.Condition object. Valid Condition objects include:

    • EQ - equal (1)
    • NE - not equal (1)
    • LE - less than or equal (1)
    • LT - less than (1)
    • GE - greater than or equal (1)
    • GT - greater than (1)
    • NOT_NULL - attribute exists (0, use None)
    • NULL - attribute does not exist (0, use None)
    • CONTAINS - substring or value in list (1)
    • NOT_CONTAINS - absence of substring or value in list (1)
    • BEGINS_WITH - substring prefix (1)
    • IN - exact match in list (N)
    • BETWEEN - >= first value, <= second value (2)
  • attributes_to_get (list) – A list of attribute names. If supplied, only the specified attribute names will be returned. Otherwise, all attributes will be returned.
  • request_limit (int) – The maximum number of items to retrieve from Amazon DynamoDB on each request. You may want to set a specific request_limit based on the provisioned throughput of your table. The default behavior is to retrieve as many results as possible per request.
  • max_results (int) – The maximum number of results that will be retrieved from Amazon DynamoDB in total. For example, if you only wanted to see the first 100 results from the query, regardless of how many were actually available, you could set max_results to 100 and the generator returned from the query method will only yeild 100 results max.
  • count (bool) – If True, Amazon DynamoDB returns a total number of items for the Scan operation, even if the operation has no matching items for the assigned filter. If count is True, the actual items are not returned and the count is accessible as the count attribute of the returned object.
  • exclusive_start_key (list or tuple) – Primary key of the item from which to continue an earlier query. This would be provided as the LastEvaluatedKey in that query.
  • item_class (Class) – Allows you to override the class used to generate the items. This should be a subclass of boto.dynamodb.item.Item
Return type:

boto.dynamodb.layer2.TableGenerator

table_from_schema(name, schema)

Create a Table object from a schema.

This method will create a Table object without making any API calls. If you know the name and schema of the table, you can use this method instead of get_table.

Example usage:

table = layer2.table_from_schema(
    'tablename',
    Schema.create(hash_key=('foo', 'N')))
Parameters:
Return type:

boto.dynamodb.table.Table

Returns:

A Table object representing the table.

update_item(item, expected_value=None, return_values=None)

Commit pending item updates to Amazon DynamoDB.

Parameters:
  • item (boto.dynamodb.item.Item) – The Item to update in Amazon DynamoDB. It is expected that you would have called the add_attribute, put_attribute and/or delete_attribute methods on this Item prior to calling this method. Those queued changes are what will be updated.
  • expected_value (dict) – A dictionary of name/value pairs that you expect. This dictionary should have name/value pairs where the name is the name of the attribute and the value is either the value you are expecting or False if you expect the attribute not to exist.
  • return_values (str) – Controls the return of attribute name/value pairs before they were updated. Possible values are: None, ‘ALL_OLD’, ‘UPDATED_OLD’, ‘ALL_NEW’ or ‘UPDATED_NEW’. If ‘ALL_OLD’ is specified and the item is overwritten, the content of the old item is returned. If ‘ALL_NEW’ is specified, then all the attributes of the new version of the item are returned. If ‘UPDATED_NEW’ is specified, the new versions of only the updated attributes are returned.
update_throughput(table, read_units, write_units)

Update the ProvisionedThroughput for the Amazon DynamoDB Table.

Parameters:
  • table (boto.dynamodb.table.Table) – The Table object whose throughput is being updated.
  • read_units (int) – The new value for ReadCapacityUnits.
  • write_units (int) – The new value for WriteCapacityUnits.
use_decimals(use_boolean=False)

Use the decimal.Decimal type for encoding/decoding numeric types.

By default, ints/floats are used to represent numeric types (‘N’, ‘NS’) received from DynamoDB. Using the Decimal type is recommended to prevent loss of precision.

class boto.dynamodb.layer2.TableGenerator(table, callable, remaining, item_class, kwargs)

This is an object that wraps up the table_generator function. The only real reason to have this is that we want to be able to accumulate and return the ConsumedCapacityUnits element that is part of each response.

Variables:
  • last_evaluated_key – A sequence representing the key(s) of the item last evaluated, or None if no additional results are available.
  • remaining – The remaining quantity of results requested.
  • table – The table to which the call was made.
consumed_units

Returns a float representing the ConsumedCapacityUnits accumulated.

count

The total number of items retrieved thus far. This value changes with iteration and even when issuing a call with count=True, it is necessary to complete the iteration to assert an accurate count value.

next_response()

Issue a call and return the result. You can invoke this method while iterating over the TableGenerator in order to skip to the next “page” of results.

response

The current response to the call from DynamoDB.

scanned_count

As above, but representing the total number of items scanned by DynamoDB, without regard to any filters.

boto.dynamodb.table

class boto.dynamodb.table.Table(layer2, response)

An Amazon DynamoDB table.

Variables:
  • name – The name of the table.
  • create_time – The date and time that the table was created.
  • status – The current status of the table. One of: ‘ACTIVE’, ‘UPDATING’, ‘DELETING’.
  • schema – A boto.dynamodb.schema.Schema object representing the schema defined for the table.
  • item_count – The number of items in the table. This value is set only when the Table object is created or refreshed and may not reflect the actual count.
  • size_bytes – Total size of the specified table, in bytes. Amazon DynamoDB updates this value approximately every six hours. Recent changes might not be reflected in this value.
  • read_units – The ReadCapacityUnits of the tables Provisioned Throughput.
  • write_units – The WriteCapacityUnits of the tables Provisioned Throughput.
  • schema – The Schema object associated with the table.
Parameters:
batch_get_item(keys, attributes_to_get=None)

Return a set of attributes for a multiple items from a single table using their primary keys. This abstraction removes the 100 Items per batch limitations as well as the “UnprocessedKeys” logic.

Parameters:
  • keys (list) – A list of scalar or tuple values. Each element in the list represents one Item to retrieve. If the schema for the table has both a HashKey and a RangeKey, each element in the list should be a tuple consisting of (hash_key, range_key). If the schema for the table contains only a HashKey, each element in the list should be a scalar value of the appropriate type for the table schema. NOTE: The maximum number of items that can be retrieved for a single operation is 100. Also, the number of items retrieved is constrained by a 1 MB size limit.
  • attributes_to_get (list) – A list of attribute names. If supplied, only the specified attribute names will be returned. Otherwise, all attributes will be returned.
Returns:

A TableBatchGenerator (generator) object which will iterate over all results

Return type:

boto.dynamodb.table.TableBatchGenerator

classmethod create_from_schema(layer2, name, schema)

Create a Table object.

If you know the name and schema of your table, you can create a Table object without having to make any API calls (normally an API call is made to retrieve the schema of a table).

Example usage:

table = Table.create_from_schema(
    boto.connect_dynamodb(),
    'tablename',
    Schema.create(hash_key=('keyname', 'N')))
Parameters:
Return type:

boto.dynamodb.table.Table

Returns:

A Table object representing the table.

create_time
delete()

Delete this table and all items in it. After calling this the Table objects status attribute will be set to ‘DELETING’.

get_item(hash_key, range_key=None, attributes_to_get=None, consistent_read=False, item_class=<class 'boto.dynamodb.item.Item'>)

Retrieve an existing item from the table.

Parameters:
  • hash_key (int|long|float|str|unicode|Binary) – The HashKey of the requested item. The type of the value must match the type defined in the schema for the table.
  • range_key (int|long|float|str|unicode|Binary) – The optional RangeKey of the requested item. The type of the value must match the type defined in the schema for the table.
  • attributes_to_get (list) – A list of attribute names. If supplied, only the specified attribute names will be returned. Otherwise, all attributes will be returned.
  • consistent_read (bool) – If True, a consistent read request is issued. Otherwise, an eventually consistent request is issued.
  • item_class (Class) – Allows you to override the class used to generate the items. This should be a subclass of boto.dynamodb.item.Item
has_item(hash_key, range_key=None, consistent_read=False)

Checks the table to see if the Item with the specified hash_key exists. This may save a tiny bit of time/bandwidth over a straight get_item() if you have no intention to touch the data that is returned, since this method specifically tells Amazon not to return anything but the Item’s key.

Parameters:
  • hash_key (int|long|float|str|unicode|Binary) – The HashKey of the requested item. The type of the value must match the type defined in the schema for the table.
  • range_key (int|long|float|str|unicode|Binary) – The optional RangeKey of the requested item. The type of the value must match the type defined in the schema for the table.
  • consistent_read (bool) – If True, a consistent read request is issued. Otherwise, an eventually consistent request is issued.
Return type:

bool

Returns:

True if the Item exists, False if not.

item_count
lookup(hash_key, range_key=None, attributes_to_get=None, consistent_read=False, item_class=<class 'boto.dynamodb.item.Item'>)

Retrieve an existing item from the table.

Parameters:
  • hash_key (int|long|float|str|unicode|Binary) – The HashKey of the requested item. The type of the value must match the type defined in the schema for the table.
  • range_key (int|long|float|str|unicode|Binary) – The optional RangeKey of the requested item. The type of the value must match the type defined in the schema for the table.
  • attributes_to_get (list) – A list of attribute names. If supplied, only the specified attribute names will be returned. Otherwise, all attributes will be returned.
  • consistent_read (bool) – If True, a consistent read request is issued. Otherwise, an eventually consistent request is issued.
  • item_class (Class) – Allows you to override the class used to generate the items. This should be a subclass of boto.dynamodb.item.Item
name
new_item(hash_key=None, range_key=None, attrs=None, item_class=<class 'boto.dynamodb.item.Item'>)

Return an new, unsaved Item which can later be PUT to Amazon DynamoDB.

This method has explicit (but optional) parameters for the hash_key and range_key values of the item. You can use these explicit parameters when calling the method, such as:

>>> my_item = my_table.new_item(hash_key='a', range_key=1,
                            attrs={'key1': 'val1', 'key2': 'val2'})
>>> my_item
{u'bar': 1, u'foo': 'a', 'key1': 'val1', 'key2': 'val2'}

Or, if you prefer, you can simply put the hash_key and range_key in the attrs dictionary itself, like this:

>>> attrs = {'foo': 'a', 'bar': 1, 'key1': 'val1', 'key2': 'val2'}
>>> my_item = my_table.new_item(attrs=attrs)
>>> my_item
{u'bar': 1, u'foo': 'a', 'key1': 'val1', 'key2': 'val2'}

The effect is the same.

Parameters:
  • hash_key (int|long|float|str|unicode|Binary) – The HashKey of the new item. The type of the value must match the type defined in the schema for the table.
  • range_key (int|long|float|str|unicode|Binary) – The optional RangeKey of the new item. The type of the value must match the type defined in the schema for the table.
  • attrs (dict) – A dictionary of key value pairs used to populate the new item.
  • item_class (Class) – Allows you to override the class used to generate the items. This should be a subclass of boto.dynamodb.item.Item
query(hash_key, *args, **kw)

Perform a query on the table.

Parameters:
  • hash_key (int|long|float|str|unicode|Binary) – The HashKey of the requested item. The type of the value must match the type defined in the schema for the table.
  • range_key_condition (boto.dynamodb.condition.Condition) –

    A Condition object. Condition object can be one of the following types:

    EQ|LE|LT|GE|GT|BEGINS_WITH|BETWEEN

    The only condition which expects or will accept two values is ‘BETWEEN’, otherwise a single value should be passed to the Condition constructor.

  • attributes_to_get (list) – A list of attribute names. If supplied, only the specified attribute names will be returned. Otherwise, all attributes will be returned.
  • request_limit (int) – The maximum number of items to retrieve from Amazon DynamoDB on each request. You may want to set a specific request_limit based on the provisioned throughput of your table. The default behavior is to retrieve as many results as possible per request.
  • max_results (int) – The maximum number of results that will be retrieved from Amazon DynamoDB in total. For example, if you only wanted to see the first 100 results from the query, regardless of how many were actually available, you could set max_results to 100 and the generator returned from the query method will only yeild 100 results max.
  • consistent_read (bool) – If True, a consistent read request is issued. Otherwise, an eventually consistent request is issued.
  • scan_index_forward (bool) – Specified forward or backward traversal of the index. Default is forward (True).
  • exclusive_start_key (list or tuple) – Primary key of the item from which to continue an earlier query. This would be provided as the LastEvaluatedKey in that query.
  • count (bool) – If True, Amazon DynamoDB returns a total number of items for the Query operation, even if the operation has no matching items for the assigned filter. If count is True, the actual items are not returned and the count is accessible as the count attribute of the returned object.
  • item_class (Class) – Allows you to override the class used to generate the items. This should be a subclass of boto.dynamodb.item.Item
read_units
refresh(wait_for_active=False, retry_seconds=5)

Refresh all of the fields of the Table object by calling the underlying DescribeTable request.

Parameters:
  • wait_for_active (bool) – If True, this command will not return until the table status, as returned from Amazon DynamoDB, is ‘ACTIVE’.
  • retry_seconds (int) – If wait_for_active is True, this parameter controls the number of seconds of delay between calls to update_table in Amazon DynamoDB. Default is 5 seconds.
scan(*args, **kw)

Scan through this table, this is a very long and expensive operation, and should be avoided if at all possible.

Parameters:
  • scan_filter (A dict) –

    A dictionary where the key is the attribute name and the value is a boto.dynamodb.condition.Condition object. Valid Condition objects include:

    • EQ - equal (1)
    • NE - not equal (1)
    • LE - less than or equal (1)
    • LT - less than (1)
    • GE - greater than or equal (1)
    • GT - greater than (1)
    • NOT_NULL - attribute exists (0, use None)
    • NULL - attribute does not exist (0, use None)
    • CONTAINS - substring or value in list (1)
    • NOT_CONTAINS - absence of substring or value in list (1)
    • BEGINS_WITH - substring prefix (1)
    • IN - exact match in list (N)
    • BETWEEN - >= first value, <= second value (2)
  • attributes_to_get (list) – A list of attribute names. If supplied, only the specified attribute names will be returned. Otherwise, all attributes will be returned.
  • request_limit (int) – The maximum number of items to retrieve from Amazon DynamoDB on each request. You may want to set a specific request_limit based on the provisioned throughput of your table. The default behavior is to retrieve as many results as possible per request.
  • max_results (int) – The maximum number of results that will be retrieved from Amazon DynamoDB in total. For example, if you only wanted to see the first 100 results from the query, regardless of how many were actually available, you could set max_results to 100 and the generator returned from the query method will only yeild 100 results max.
  • count (bool) – If True, Amazon DynamoDB returns a total number of items for the Scan operation, even if the operation has no matching items for the assigned filter. If count is True, the actual items are not returned and the count is accessible as the count attribute of the returned object.
  • exclusive_start_key (list or tuple) – Primary key of the item from which to continue an earlier query. This would be provided as the LastEvaluatedKey in that query.
  • item_class (Class) – Allows you to override the class used to generate the items. This should be a subclass of boto.dynamodb.item.Item
Returns:

A TableGenerator (generator) object which will iterate over all results

Return type:

boto.dynamodb.layer2.TableGenerator

schema
size_bytes
status
update_from_response(response)

Update the state of the Table object based on the response data received from Amazon DynamoDB.

update_throughput(read_units, write_units)

Update the ProvisionedThroughput for the Amazon DynamoDB Table.

Parameters:
  • read_units (int) – The new value for ReadCapacityUnits.
  • write_units (int) – The new value for WriteCapacityUnits.
write_units
class boto.dynamodb.table.TableBatchGenerator(table, keys, attributes_to_get=None, consistent_read=False)

A low-level generator used to page through results from batch_get_item operations.

Variables:consumed_units – An integer that holds the number of ConsumedCapacityUnits accumulated thus far for this generator.

boto.dynamodb.schema

class boto.dynamodb.schema.Schema(schema_dict)

Represents a DynamoDB schema.

Variables:
  • hash_key_name – The name of the hash key of the schema.
  • hash_key_type – The DynamoDB type specification for the hash key of the schema.
  • range_key_name – The name of the range key of the schema or None if no range key is defined.
  • range_key_type – The DynamoDB type specification for the range key of the schema or None if no range key is defined.
  • dict – The underlying Python dictionary that needs to be passed to Layer1 methods.
classmethod create(hash_key, range_key=None)

Convenience method to create a schema object.

Example usage:

schema = Schema.create(hash_key=('foo', 'N'))
schema2 = Schema.create(hash_key=('foo', 'N'),
                        range_key=('bar', 'S'))
Parameters:
  • hash_key (tuple) – A tuple of (hash_key_name, hash_key_type)
  • hash_key – A tuple of (range_key_name, range_key_type)
dict
hash_key_name
hash_key_type
range_key_name
range_key_type

boto.dynamodb.item

class boto.dynamodb.item.Item(table, hash_key=None, range_key=None, attrs=None)

An item in Amazon DynamoDB.

Variables:
  • hash_key – The HashKey of this item.
  • range_key – The RangeKey of this item or None if no RangeKey is defined.
  • hash_key_name – The name of the HashKey associated with this item.
  • range_key_name – The name of the RangeKey associated with this item.
  • table – The Table this item belongs to.
add_attribute(attr_name, attr_value)

Queue the addition of an attribute to an item in DynamoDB. This will eventually result in an UpdateItem request being issued with an update action of ADD when the save method is called.

Parameters:
  • attr_name (str) – Name of the attribute you want to alter.
  • attr_value (int|long|float|set) – Value which is to be added to the attribute.
delete(expected_value=None, return_values=None)

Delete the item from DynamoDB.

Parameters:
  • expected_value (dict) – A dictionary of name/value pairs that you expect. This dictionary should have name/value pairs where the name is the name of the attribute and the value is either the value you are expecting or False if you expect the attribute not to exist.
  • return_values (str) – Controls the return of attribute name-value pairs before then were changed. Possible values are: None or ‘ALL_OLD’. If ‘ALL_OLD’ is specified and the item is overwritten, the content of the old item is returned.
delete_attribute(attr_name, attr_value=None)

Queue the deletion of an attribute from an item in DynamoDB. This call will result in a UpdateItem request being issued with update action of DELETE when the save method is called.

Parameters:
  • attr_name (str) – Name of the attribute you want to alter.
  • attr_value (set) – A set of values to be removed from the attribute. This parameter is optional. If None, the whole attribute is removed from the item.
hash_key
hash_key_name
put(expected_value=None, return_values=None)

Store a new item or completely replace an existing item in Amazon DynamoDB.

Parameters:
  • expected_value (dict) – A dictionary of name/value pairs that you expect. This dictionary should have name/value pairs where the name is the name of the attribute and the value is either the value you are expecting or False if you expect the attribute not to exist.
  • return_values (str) – Controls the return of attribute name-value pairs before then were changed. Possible values are: None or ‘ALL_OLD’. If ‘ALL_OLD’ is specified and the item is overwritten, the content of the old item is returned.
put_attribute(attr_name, attr_value)

Queue the putting of an attribute to an item in DynamoDB. This call will result in an UpdateItem request being issued with the update action of PUT when the save method is called.

Parameters:
  • attr_name (str) – Name of the attribute you want to alter.
  • attr_value (int|long|float|str|set) – New value of the attribute.
range_key
range_key_name
save(expected_value=None, return_values=None)

Commits pending updates to Amazon DynamoDB.

Parameters:
  • expected_value (dict) – A dictionary of name/value pairs that you expect. This dictionary should have name/value pairs where the name is the name of the attribute and the value is either the value you are expecting or False if you expect the attribute not to exist.
  • return_values (str) – Controls the return of attribute name/value pairs before they were updated. Possible values are: None, ‘ALL_OLD’, ‘UPDATED_OLD’, ‘ALL_NEW’ or ‘UPDATED_NEW’. If ‘ALL_OLD’ is specified and the item is overwritten, the content of the old item is returned. If ‘ALL_NEW’ is specified, then all the attributes of the new version of the item are returned. If ‘UPDATED_NEW’ is specified, the new versions of only the updated attributes are returned.

boto.dynamodb.batch

class boto.dynamodb.batch.Batch(table, keys, attributes_to_get=None, consistent_read=False)

Used to construct a BatchGet request.

Variables:
  • table – The Table object from which the item is retrieved.
  • keys – A list of scalar or tuple values. Each element in the list represents one Item to retrieve. If the schema for the table has both a HashKey and a RangeKey, each element in the list should be a tuple consisting of (hash_key, range_key). If the schema for the table contains only a HashKey, each element in the list should be a scalar value of the appropriate type for the table schema. NOTE: The maximum number of items that can be retrieved for a single operation is 100. Also, the number of items retrieved is constrained by a 1 MB size limit.
  • attributes_to_get – A list of attribute names. If supplied, only the specified attribute names will be returned. Otherwise, all attributes will be returned.
  • consistent_read – Specify whether or not to use a consistent read. Defaults to False.
to_dict()

Convert the Batch object into the format required for Layer1.

class boto.dynamodb.batch.BatchList(layer2)

A subclass of a list object that contains a collection of boto.dynamodb.batch.Batch objects.

add_batch(table, keys, attributes_to_get=None, consistent_read=False)

Add a Batch to this BatchList.

Parameters:
  • table (boto.dynamodb.table.Table) – The Table object in which the items are contained.
  • keys (list) – A list of scalar or tuple values. Each element in the list represents one Item to retrieve. If the schema for the table has both a HashKey and a RangeKey, each element in the list should be a tuple consisting of (hash_key, range_key). If the schema for the table contains only a HashKey, each element in the list should be a scalar value of the appropriate type for the table schema. NOTE: The maximum number of items that can be retrieved for a single operation is 100. Also, the number of items retrieved is constrained by a 1 MB size limit.
  • attributes_to_get (list) – A list of attribute names. If supplied, only the specified attribute names will be returned. Otherwise, all attributes will be returned.
resubmit()

Resubmit the batch to get the next result set. The request object is rebuild from scratch meaning that all batch added between submit and resubmit will be lost.

Note: This method is experimental and subject to changes in future releases

submit()
to_dict()

Convert a BatchList object into format required for Layer1.

class boto.dynamodb.batch.BatchWrite(table, puts=None, deletes=None)

Used to construct a BatchWrite request. Each BatchWrite object represents a collection of PutItem and DeleteItem requests for a single Table.

Variables:
  • table – The Table object from which the item is retrieved.
  • puts – A list of boto.dynamodb.item.Item objects that you want to write to DynamoDB.
  • deletes – A list of scalar or tuple values. Each element in the list represents one Item to delete. If the schema for the table has both a HashKey and a RangeKey, each element in the list should be a tuple consisting of (hash_key, range_key). If the schema for the table contains only a HashKey, each element in the list should be a scalar value of the appropriate type for the table schema.
to_dict()

Convert the Batch object into the format required for Layer1.

class boto.dynamodb.batch.BatchWriteList(layer2)

A subclass of a list object that contains a collection of boto.dynamodb.batch.BatchWrite objects.

add_batch(table, puts=None, deletes=None)

Add a BatchWrite to this BatchWriteList.

Parameters:
  • table (boto.dynamodb.table.Table) – The Table object in which the items are contained.
  • puts (list of boto.dynamodb.item.Item objects) – A list of items that you want to write to DynamoDB.
  • deletes (A list) – A list of scalar or tuple values. Each element in the list represents one Item to delete. If the schema for the table has both a HashKey and a RangeKey, each element in the list should be a tuple consisting of (hash_key, range_key). If the schema for the table contains only a HashKey, each element in the list should be a scalar value of the appropriate type for the table schema.
submit()
to_dict()

Convert a BatchWriteList object into format required for Layer1.

boto.dynamodb.types

Some utility functions to deal with mapping Amazon DynamoDB types to Python types and vice-versa.

class boto.dynamodb.types.Binary(value)
encode()
class boto.dynamodb.types.Dynamizer

Control serialization/deserialization of types.

This class controls the encoding of python types to the format that is expected by the DynamoDB API, as well as taking DynamoDB types and constructing the appropriate python types.

If you want to customize this process, you can subclass this class and override the encoding/decoding of specific types. For example:

'foo'      (Python type)
    |
    v
encode('foo')
    |
    v
_encode_s('foo')
    |
    v
{'S': 'foo'}  (Encoding sent to/received from DynamoDB)
    |
    V
decode({'S': 'foo'})
    |
    v
_decode_s({'S': 'foo'})
    |
    v
'foo'     (Python type)
decode(attr)

Takes the format returned by DynamoDB and constructs the appropriate python type.

encode(attr)

Encodes a python type to the format expected by DynamoDB.

class boto.dynamodb.types.LossyFloatDynamizer

Use float/int instead of Decimal for numeric types.

This class is provided for backwards compatibility. Instead of using Decimals for the ‘N’, ‘NS’ types it uses ints/floats.

This class is deprecated and its usage is not encouraged, as doing so may result in loss of precision. Use the Dynamizer class instead.

class boto.dynamodb.types.NonBooleanDynamizer

Casting boolean type to numeric types.

This class is provided for backward compatibility.

boto.dynamodb.types.convert_binary(n)
boto.dynamodb.types.convert_num(s)
boto.dynamodb.types.dynamize_value(val)

Take a scalar Python value and return a dict consisting of the Amazon DynamoDB type specification and the value that needs to be sent to Amazon DynamoDB. If the type of the value is not supported, raise a TypeError

boto.dynamodb.types.float_to_decimal(f)
boto.dynamodb.types.get_dynamodb_type(val, use_boolean=True)

Take a scalar Python value and return a string representing the corresponding Amazon DynamoDB type. If the value passed in is not a supported type, raise a TypeError.

boto.dynamodb.types.is_binary(n)
boto.dynamodb.types.is_num(n, boolean_as_int=True)
boto.dynamodb.types.is_str(n)
boto.dynamodb.types.item_object_hook(dct)

A custom object hook for use when decoding JSON item bodys. This hook will transform Amazon DynamoDB JSON responses to something that maps directly to native Python types.

boto.dynamodb.types.serialize_num(val)

Cast a number to a string and perform validation to ensure no loss of precision.