Mercurial > repos > shellac > sam_consensus_v3
diff env/lib/python3.9/site-packages/boto/dynamodb2/layer1.py @ 0:4f3585e2f14b draft default tip
"planemo upload commit 60cee0fc7c0cda8592644e1aad72851dec82c959"
| author | shellac |
|---|---|
| date | Mon, 22 Mar 2021 18:12:50 +0000 |
| parents | |
| children |
line wrap: on
line diff
--- /dev/null Thu Jan 01 00:00:00 1970 +0000 +++ b/env/lib/python3.9/site-packages/boto/dynamodb2/layer1.py Mon Mar 22 18:12:50 2021 +0000 @@ -0,0 +1,2904 @@ +# Copyright (c) 2014 Amazon.com, Inc. or its affiliates. All Rights Reserved +# +# Permission is hereby granted, free of charge, to any person obtaining a +# copy of this software and associated documentation files (the +# "Software"), to deal in the Software without restriction, including +# without limitation the rights to use, copy, modify, merge, publish, dis- +# tribute, sublicense, and/or sell copies of the Software, and to permit +# persons to whom the Software is furnished to do so, subject to the fol- +# lowing conditions: +# +# The above copyright notice and this permission notice shall be included +# in all copies or substantial portions of the Software. +# +# THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS +# OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABIL- +# ITY, FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT +# SHALL THE AUTHOR BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER LIABILITY, +# WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, +# OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS +# IN THE SOFTWARE. +# +from binascii import crc32 + +import boto +from boto.compat import json +from boto.connection import AWSQueryConnection +from boto.regioninfo import RegionInfo +from boto.exception import JSONResponseError +from boto.dynamodb2 import exceptions + + +class DynamoDBConnection(AWSQueryConnection): + """ + Amazon DynamoDB + **Overview** + + This is the Amazon DynamoDB API Reference. This guide provides + descriptions and samples of the low-level DynamoDB API. For + information about DynamoDB application development, go to the + `Amazon DynamoDB Developer Guide`_. + + Instead of making the requests to the low-level DynamoDB API + directly from your application, we recommend that you use the AWS + Software Development Kits (SDKs). The easy-to-use libraries in the + AWS SDKs make it unnecessary to call the low-level DynamoDB API + directly from your application. The libraries take care of request + authentication, serialization, and connection management. For more + information, go to `Using the AWS SDKs with DynamoDB`_ in the + Amazon DynamoDB Developer Guide . + + If you decide to code against the low-level DynamoDB API directly, + you will need to write the necessary code to authenticate your + requests. For more information on signing your requests, go to + `Using the DynamoDB API`_ in the Amazon DynamoDB Developer Guide . + + The following are short descriptions of each low-level API action, + organized by function. + + **Managing Tables** + + + + CreateTable - Creates a table with user-specified provisioned + throughput settings. You must designate one attribute as the hash + primary key for the table; you can optionally designate a second + attribute as the range primary key. DynamoDB creates indexes on + these key attributes for fast data access. Optionally, you can + create one or more secondary indexes, which provide fast data + access using non-key attributes. + + DescribeTable - Returns metadata for a table, such as table + size, status, and index information. + + UpdateTable - Modifies the provisioned throughput settings for a + table. Optionally, you can modify the provisioned throughput + settings for global secondary indexes on the table. + + ListTables - Returns a list of all tables associated with the + current AWS account and endpoint. + + DeleteTable - Deletes a table and all of its indexes. + + + For conceptual information about managing tables, go to `Working + with Tables`_ in the Amazon DynamoDB Developer Guide . + + **Reading Data** + + + + GetItem - Returns a set of attributes for the item that has a + given primary key. By default, GetItem performs an eventually + consistent read; however, applications can specify a strongly + consistent read instead. + + BatchGetItem - Performs multiple GetItem requests for data items + using their primary keys, from one table or multiple tables. The + response from BatchGetItem has a size limit of 16 MB and returns a + maximum of 100 items. Both eventually consistent and strongly + consistent reads can be used. + + Query - Returns one or more items from a table or a secondary + index. You must provide a specific hash key value. You can narrow + the scope of the query using comparison operators against a range + key value, or on the index key. Query supports either eventual or + strong consistency. A single response has a size limit of 1 MB. + + Scan - Reads every item in a table; the result set is eventually + consistent. You can limit the number of items returned by + filtering the data attributes, using conditional expressions. Scan + can be used to enable ad-hoc querying of a table against non-key + attributes; however, since this is a full table scan without using + an index, Scan should not be used for any application query use + case that requires predictable performance. + + + For conceptual information about reading data, go to `Working with + Items`_ and `Query and Scan Operations`_ in the Amazon DynamoDB + Developer Guide . + + **Modifying Data** + + + + PutItem - Creates a new item, or replaces an existing item with + a new item (including all the attributes). By default, if an item + in the table already exists with the same primary key, the new + item completely replaces the existing item. You can use + conditional operators to replace an item only if its attribute + values match certain conditions, or to insert a new item only if + that item doesn't already exist. + + UpdateItem - Modifies the attributes of an existing item. You + can also use conditional operators to perform an update only if + the item's attribute values match certain conditions. + + DeleteItem - Deletes an item in a table by primary key. You can + use conditional operators to perform a delete an item only if the + item's attribute values match certain conditions. + + BatchWriteItem - Performs multiple PutItem and DeleteItem + requests across multiple tables in a single request. A failure of + any request(s) in the batch will not cause the entire + BatchWriteItem operation to fail. Supports batches of up to 25 + items to put or delete, with a maximum total request size of 16 + MB. + + + For conceptual information about modifying data, go to `Working + with Items`_ and `Query and Scan Operations`_ in the Amazon + DynamoDB Developer Guide . + """ + APIVersion = "2012-08-10" + DefaultRegionName = "us-east-1" + DefaultRegionEndpoint = "dynamodb.us-east-1.amazonaws.com" + ServiceName = "DynamoDB" + TargetPrefix = "DynamoDB_20120810" + ResponseError = JSONResponseError + + _faults = { + "ProvisionedThroughputExceededException": exceptions.ProvisionedThroughputExceededException, + "LimitExceededException": exceptions.LimitExceededException, + "ConditionalCheckFailedException": exceptions.ConditionalCheckFailedException, + "ResourceInUseException": exceptions.ResourceInUseException, + "ResourceNotFoundException": exceptions.ResourceNotFoundException, + "InternalServerError": exceptions.InternalServerError, + "ItemCollectionSizeLimitExceededException": exceptions.ItemCollectionSizeLimitExceededException, + } + + NumberRetries = 10 + + + def __init__(self, **kwargs): + region = kwargs.pop('region', None) + validate_checksums = kwargs.pop('validate_checksums', True) + if not region: + region_name = boto.config.get('DynamoDB', 'region', + self.DefaultRegionName) + for reg in boto.dynamodb2.regions(): + if reg.name == region_name: + region = reg + break + + # Only set host if it isn't manually overwritten + if 'host' not in kwargs: + kwargs['host'] = region.endpoint + + super(DynamoDBConnection, self).__init__(**kwargs) + self.region = region + self._validate_checksums = boto.config.getbool( + 'DynamoDB', 'validate_checksums', validate_checksums) + self.throughput_exceeded_events = 0 + + def _required_auth_capability(self): + return ['hmac-v4'] + + def batch_get_item(self, request_items, return_consumed_capacity=None): + """ + The BatchGetItem operation returns the attributes of one or + more items from one or more tables. You identify requested + items by primary key. + + A single operation can retrieve up to 16 MB of data, which can + contain as many as 100 items. BatchGetItem will return a + partial result if the response size limit is exceeded, the + table's provisioned throughput is exceeded, or an internal + processing failure occurs. If a partial result is returned, + the operation returns a value for UnprocessedKeys . You can + use this value to retry the operation starting with the next + item to get. + + For example, if you ask to retrieve 100 items, but each + individual item is 300 KB in size, the system returns 52 items + (so as not to exceed the 16 MB limit). It also returns an + appropriate UnprocessedKeys value so you can get the next page + of results. If desired, your application can include its own + logic to assemble the pages of results into one data set. + + If none of the items can be processed due to insufficient + provisioned throughput on all of the tables in the request, + then BatchGetItem will return a + ProvisionedThroughputExceededException . If at least one of + the items is successfully processed, then BatchGetItem + completes successfully, while returning the keys of the unread + items in UnprocessedKeys . + + If DynamoDB returns any unprocessed items, you should retry + the batch operation on those items. However, we strongly + recommend that you use an exponential backoff algorithm . If + you retry the batch operation immediately, the underlying read + or write requests can still fail due to throttling on the + individual tables. If you delay the batch operation using + exponential backoff, the individual requests in the batch are + much more likely to succeed. + + For more information, go to `Batch Operations and Error + Handling`_ in the Amazon DynamoDB Developer Guide . + + By default, BatchGetItem performs eventually consistent reads + on every table in the request. If you want strongly consistent + reads instead, you can set ConsistentRead to `True` for any or + all tables. + + In order to minimize response latency, BatchGetItem retrieves + items in parallel. + + When designing your application, keep in mind that DynamoDB + does not return attributes in any particular order. To help + parse the response by item, include the primary key values for + the items in your request in the AttributesToGet parameter. + + If a requested item does not exist, it is not returned in the + result. Requests for nonexistent items consume the minimum + read capacity units according to the type of read. For more + information, see `Capacity Units Calculations`_ in the Amazon + DynamoDB Developer Guide . + + :type request_items: map + :param request_items: + A map of one or more table names and, for each table, the corresponding + primary keys for the items to retrieve. Each table name can be + invoked only once. + + Each element in the map consists of the following: + + + + Keys - An array of primary key attribute values that define specific + items in the table. For each primary key, you must provide all of + the key attributes. For example, with a hash type primary key, you + only need to specify the hash attribute. For a hash-and-range type + primary key, you must specify both the hash attribute and the range + attribute. + + AttributesToGet - One or more attributes to be retrieved from the + table. By default, all attributes are returned. If a specified + attribute is not found, it does not appear in the result. Note that + AttributesToGet has no effect on provisioned throughput + consumption. DynamoDB determines capacity units consumed based on + item size, not on the amount of data that is returned to an + application. + + ConsistentRead - If `True`, a strongly consistent read is used; if + `False` (the default), an eventually consistent read is used. + + :type return_consumed_capacity: string + :param return_consumed_capacity: A value that if set to `TOTAL`, the + response includes ConsumedCapacity data for tables and indexes. If + set to `INDEXES`, the response includes ConsumedCapacity for + indexes. If set to `NONE` (the default), ConsumedCapacity is not + included in the response. + + """ + params = {'RequestItems': request_items, } + if return_consumed_capacity is not None: + params['ReturnConsumedCapacity'] = return_consumed_capacity + return self.make_request(action='BatchGetItem', + body=json.dumps(params)) + + def batch_write_item(self, request_items, return_consumed_capacity=None, + return_item_collection_metrics=None): + """ + The BatchWriteItem operation puts or deletes multiple items in + one or more tables. A single call to BatchWriteItem can write + up to 16 MB of data, which can comprise as many as 25 put or + delete requests. Individual items to be written can be as + large as 400 KB. + + + BatchWriteItem cannot update items. To update items, use the + UpdateItem API. + + + The individual PutItem and DeleteItem operations specified in + BatchWriteItem are atomic; however BatchWriteItem as a whole + is not. If any requested operations fail because the table's + provisioned throughput is exceeded or an internal processing + failure occurs, the failed operations are returned in the + UnprocessedItems response parameter. You can investigate and + optionally resend the requests. Typically, you would call + BatchWriteItem in a loop. Each iteration would check for + unprocessed items and submit a new BatchWriteItem request with + those unprocessed items until all items have been processed. + + Note that if none of the items can be processed due to + insufficient provisioned throughput on all of the tables in + the request, then BatchWriteItem will return a + ProvisionedThroughputExceededException . + + If DynamoDB returns any unprocessed items, you should retry + the batch operation on those items. However, we strongly + recommend that you use an exponential backoff algorithm . If + you retry the batch operation immediately, the underlying read + or write requests can still fail due to throttling on the + individual tables. If you delay the batch operation using + exponential backoff, the individual requests in the batch are + much more likely to succeed. + + For more information, go to `Batch Operations and Error + Handling`_ in the Amazon DynamoDB Developer Guide . + + With BatchWriteItem , you can efficiently write or delete + large amounts of data, such as from Amazon Elastic MapReduce + (EMR), or copy data from another database into DynamoDB. In + order to improve performance with these large-scale + operations, BatchWriteItem does not behave in the same way as + individual PutItem and DeleteItem calls would For example, you + cannot specify conditions on individual put and delete + requests, and BatchWriteItem does not return deleted items in + the response. + + If you use a programming language that supports concurrency, + such as Java, you can use threads to write items in parallel. + Your application must include the necessary logic to manage + the threads. With languages that don't support threading, such + as PHP, you must update or delete the specified items one at a + time. In both situations, BatchWriteItem provides an + alternative where the API performs the specified put and + delete operations in parallel, giving you the power of the + thread pool approach without having to introduce complexity + into your application. + + Parallel processing reduces latency, but each specified put + and delete request consumes the same number of write capacity + units whether it is processed in parallel or not. Delete + operations on nonexistent items consume one write capacity + unit. + + If one or more of the following is true, DynamoDB rejects the + entire batch write operation: + + + + One or more tables specified in the BatchWriteItem request + does not exist. + + Primary key attributes specified on an item in the request + do not match those in the corresponding table's primary key + schema. + + You try to perform multiple operations on the same item in + the same BatchWriteItem request. For example, you cannot put + and delete the same item in the same BatchWriteItem request. + + There are more than 25 requests in the batch. + + Any individual item in a batch exceeds 400 KB. + + The total request size exceeds 16 MB. + + :type request_items: map + :param request_items: + A map of one or more table names and, for each table, a list of + operations to be performed ( DeleteRequest or PutRequest ). Each + element in the map consists of the following: + + + + DeleteRequest - Perform a DeleteItem operation on the specified item. + The item to be deleted is identified by a Key subelement: + + + Key - A map of primary key attribute values that uniquely identify + the ! item. Each entry in this map consists of an attribute name + and an attribute value. For each primary key, you must provide all + of the key attributes. For example, with a hash type primary key, + you only need to specify the hash attribute. For a hash-and-range + type primary key, you must specify both the hash attribute and the + range attribute. + + + PutRequest - Perform a PutItem operation on the specified item. The + item to be put is identified by an Item subelement: + + + Item - A map of attributes and their values. Each entry in this map + consists of an attribute name and an attribute value. Attribute + values must not be null; string and binary type attributes must + have lengths greater than zero; and set type attributes must not be + empty. Requests that contain empty values will be rejected with a + ValidationException exception. If you specify any attributes that + are part of an index key, then the data types for those attributes + must match those of the schema in the table's attribute definition. + + :type return_consumed_capacity: string + :param return_consumed_capacity: A value that if set to `TOTAL`, the + response includes ConsumedCapacity data for tables and indexes. If + set to `INDEXES`, the response includes ConsumedCapacity for + indexes. If set to `NONE` (the default), ConsumedCapacity is not + included in the response. + + :type return_item_collection_metrics: string + :param return_item_collection_metrics: A value that if set to `SIZE`, + the response includes statistics about item collections, if any, + that were modified during the operation are returned in the + response. If set to `NONE` (the default), no statistics are + returned. + + """ + params = {'RequestItems': request_items, } + if return_consumed_capacity is not None: + params['ReturnConsumedCapacity'] = return_consumed_capacity + if return_item_collection_metrics is not None: + params['ReturnItemCollectionMetrics'] = return_item_collection_metrics + return self.make_request(action='BatchWriteItem', + body=json.dumps(params)) + + def create_table(self, attribute_definitions, table_name, key_schema, + provisioned_throughput, local_secondary_indexes=None, + global_secondary_indexes=None): + """ + The CreateTable operation adds a new table to your account. In + an AWS account, table names must be unique within each region. + That is, you can have two tables with same name if you create + the tables in different regions. + + CreateTable is an asynchronous operation. Upon receiving a + CreateTable request, DynamoDB immediately returns a response + with a TableStatus of `CREATING`. After the table is created, + DynamoDB sets the TableStatus to `ACTIVE`. You can perform + read and write operations only on an `ACTIVE` table. + + You can optionally define secondary indexes on the new table, + as part of the CreateTable operation. If you want to create + multiple tables with secondary indexes on them, you must + create the tables sequentially. Only one table with secondary + indexes can be in the `CREATING` state at any given time. + + You can use the DescribeTable API to check the table status. + + :type attribute_definitions: list + :param attribute_definitions: An array of attributes that describe the + key schema for the table and indexes. + + :type table_name: string + :param table_name: The name of the table to create. + + :type key_schema: list + :param key_schema: Specifies the attributes that make up the primary + key for a table or an index. The attributes in KeySchema must also + be defined in the AttributeDefinitions array. For more information, + see `Data Model`_ in the Amazon DynamoDB Developer Guide . + Each KeySchemaElement in the array is composed of: + + + + AttributeName - The name of this key attribute. + + KeyType - Determines whether the key attribute is `HASH` or `RANGE`. + + + For a primary key that consists of a hash attribute, you must specify + exactly one element with a KeyType of `HASH`. + + For a primary key that consists of hash and range attributes, you must + specify exactly two elements, in this order: The first element must + have a KeyType of `HASH`, and the second element must have a + KeyType of `RANGE`. + + For more information, see `Specifying the Primary Key`_ in the Amazon + DynamoDB Developer Guide . + + :type local_secondary_indexes: list + :param local_secondary_indexes: + One or more local secondary indexes (the maximum is five) to be created + on the table. Each index is scoped to a given hash key value. There + is a 10 GB size limit per hash key; otherwise, the size of a local + secondary index is unconstrained. + + Each local secondary index in the array includes the following: + + + + IndexName - The name of the local secondary index. Must be unique + only for this table. + + KeySchema - Specifies the key schema for the local secondary index. + The key schema must begin with the same hash key attribute as the + table. + + Projection - Specifies attributes that are copied (projected) from + the table into the index. These are in addition to the primary key + attributes and index key attributes, which are automatically + projected. Each attribute specification is composed of: + + + ProjectionType - One of the following: + + + `KEYS_ONLY` - Only the index and primary keys are projected into the + index. + + `INCLUDE` - Only the specified table attributes are projected into + the index. The list of projected attributes are in NonKeyAttributes + . + + `ALL` - All of the table attributes are projected into the index. + + + NonKeyAttributes - A list of one or more non-key attribute names that + are projected into the secondary index. The total count of + attributes specified in NonKeyAttributes , summed across all of the + secondary indexes, must not exceed 20. If you project the same + attribute into two different indexes, this counts as two distinct + attributes when determining the total. + + :type global_secondary_indexes: list + :param global_secondary_indexes: + One or more global secondary indexes (the maximum is five) to be + created on the table. Each global secondary index in the array + includes the following: + + + + IndexName - The name of the global secondary index. Must be unique + only for this table. + + KeySchema - Specifies the key schema for the global secondary index. + + Projection - Specifies attributes that are copied (projected) from + the table into the index. These are in addition to the primary key + attributes and index key attributes, which are automatically + projected. Each attribute specification is composed of: + + + ProjectionType - One of the following: + + + `KEYS_ONLY` - Only the index and primary keys are projected into the + index. + + `INCLUDE` - Only the specified table attributes are projected into + the index. The list of projected attributes are in NonKeyAttributes + . + + `ALL` - All of the table attributes are projected into the index. + + + NonKeyAttributes - A list of one or more non-key attribute names that + are projected into the secondary index. The total count of + attributes specified in NonKeyAttributes , summed across all of the + secondary indexes, must not exceed 20. If you project the same + attribute into two different indexes, this counts as two distinct + attributes when determining the total. + + + ProvisionedThroughput - The provisioned throughput settings for the + global secondary index, consisting of read and write capacity + units. + + :type provisioned_throughput: dict + :param provisioned_throughput: Represents the provisioned throughput + settings for a specified table or index. The settings can be + modified using the UpdateTable operation. + For current minimum and maximum provisioned throughput values, see + `Limits`_ in the Amazon DynamoDB Developer Guide . + + """ + params = { + 'AttributeDefinitions': attribute_definitions, + 'TableName': table_name, + 'KeySchema': key_schema, + 'ProvisionedThroughput': provisioned_throughput, + } + if local_secondary_indexes is not None: + params['LocalSecondaryIndexes'] = local_secondary_indexes + if global_secondary_indexes is not None: + params['GlobalSecondaryIndexes'] = global_secondary_indexes + return self.make_request(action='CreateTable', + body=json.dumps(params)) + + def delete_item(self, table_name, key, expected=None, + conditional_operator=None, return_values=None, + return_consumed_capacity=None, + return_item_collection_metrics=None, + condition_expression=None, + expression_attribute_names=None, + expression_attribute_values=None): + """ + Deletes a single item in a table by primary key. You can + perform a conditional delete operation that deletes the item + if it exists, or if it has an expected attribute value. + + In addition to deleting an item, you can also return the + item's attribute values in the same operation, using the + ReturnValues parameter. + + Unless you specify conditions, the DeleteItem is an idempotent + operation; running it multiple times on the same item or + attribute does not result in an error response. + + Conditional deletes are useful for deleting items only if + specific conditions are met. If those conditions are met, + DynamoDB performs the delete. Otherwise, the item is not + deleted. + + :type table_name: string + :param table_name: The name of the table from which to delete the item. + + :type key: map + :param key: A map of attribute names to AttributeValue objects, + representing the primary key of the item to delete. + For the primary key, you must provide all of the attributes. For + example, with a hash type primary key, you only need to specify the + hash attribute. For a hash-and-range type primary key, you must + specify both the hash attribute and the range attribute. + + :type expected: map + :param expected: + There is a newer parameter available. Use ConditionExpression instead. + Note that if you use Expected and ConditionExpression at the same + time, DynamoDB will return a ValidationException exception. + + This parameter does not support lists or maps. + + A map of attribute/condition pairs. Expected provides a conditional + block for the DeleteItem operation. + + Each element of Expected consists of an attribute name, a comparison + operator, and one or more values. DynamoDB compares the attribute + with the value(s) you supplied, using the comparison operator. For + each Expected element, the result of the evaluation is either true + or false. + + If you specify more than one element in the Expected map, then by + default all of the conditions must evaluate to true. In other + words, the conditions are ANDed together. (You can use the + ConditionalOperator parameter to OR the conditions instead. If you + do this, then at least one of the conditions must evaluate to true, + rather than all of them.) + + If the Expected map evaluates to true, then the conditional operation + succeeds; otherwise, it fails. + + Expected contains the following: + + + + AttributeValueList - One or more values to evaluate against the + supplied attribute. The number of values in the list depends on the + ComparisonOperator being used. For type Number, value comparisons + are numeric. String value comparisons for greater than, equals, or + less than are based on ASCII character code values. For example, + `a` is greater than `A`, and `a` is greater than `B`. For a list of + code values, see + `http://en.wikipedia.org/wiki/ASCII#ASCII_printable_characters`_. + For type Binary, DynamoDB treats each byte of the binary data as + unsigned when it compares binary values, for example when + evaluating query expressions. + + ComparisonOperator - A comparator for evaluating attributes in the + AttributeValueList . When performing the comparison, DynamoDB uses + strongly consistent reads. The following comparison operators are + available: `EQ | NE | LE | LT | GE | GT | NOT_NULL | NULL | + CONTAINS | NOT_CONTAINS | BEGINS_WITH | IN | BETWEEN` The following + are descriptions of each comparison operator. + + + `EQ` : Equal. `EQ` is supported for all datatypes, including lists + and maps. AttributeValueList can contain only one AttributeValue + element of type String, Number, Binary, String Set, Number Set, or + Binary Set. If an item contains an AttributeValue element of a + different type than the one specified in the request, the value + does not match. For example, `{"S":"6"}` does not equal + `{"N":"6"}`. Also, `{"N":"6"}` does not equal `{"NS":["6", "2", + "1"]}`. > <li> + + `NE` : Not equal. `NE` is supported for all datatypes, including + lists and maps. AttributeValueList can contain only one + AttributeValue of type String, Number, Binary, String Set, Number + Set, or Binary Set. If an item contains an AttributeValue of a + different type than the one specified in the request, the value + does not match. For example, `{"S":"6"}` does not equal + `{"N":"6"}`. Also, `{"N":"6"}` does not equal `{"NS":["6", "2", + "1"]}`. > <li> + + `LE` : Less than or equal. AttributeValueList can contain only one + AttributeValue element of type String, Number, or Binary (not a set + type). If an item contains an AttributeValue element of a different + type than the one specified in the request, the value does not + match. For example, `{"S":"6"}` does not equal `{"N":"6"}`. Also, + `{"N":"6"}` does not compare to `{"NS":["6", "2", "1"]}`. > <li> + + `LT` : Less than. AttributeValueList can contain only one + AttributeValue of type String, Number, or Binary (not a set type). + If an item contains an AttributeValue element of a different type + than the one specified in the request, the value does not match. + For example, `{"S":"6"}` does not equal `{"N":"6"}`. Also, + `{"N":"6"}` does not compare to `{"NS":["6", "2", "1"]}`. > <li> + + `GE` : Greater than or equal. AttributeValueList can contain only one + AttributeValue element of type String, Number, or Binary (not a set + type). If an item contains an AttributeValue element of a different + type than the one specified in the request, the value does not + match. For example, `{"S":"6"}` does not equal `{"N":"6"}`. Also, + `{"N":"6"}` does not compare to `{"NS":["6", "2", "1"]}`. > <li> + + `GT` : Greater than. AttributeValueList can contain only one + AttributeValue element of type String, Number, or Binary (not a set + type). If an item contains an AttributeValue element of a different + type than the one specified in the request, the value does not + match. For example, `{"S":"6"}` does not equal `{"N":"6"}`. Also, + `{"N":"6"}` does not compare to `{"NS":["6", "2", "1"]}`. > <li> + + `NOT_NULL` : The attribute exists. `NOT_NULL` is supported for all + datatypes, including lists and maps. This operator tests for the + existence of an attribute, not its data type. If the data type of + attribute " `a`" is null, and you evaluate it using `NOT_NULL`, the + result is a Boolean true . This result is because the attribute " + `a`" exists; its data type is not relevant to the `NOT_NULL` + comparison operator. + + `NULL` : The attribute does not exist. `NULL` is supported for all + datatypes, including lists and maps. This operator tests for the + nonexistence of an attribute, not its data type. If the data type + of attribute " `a`" is null, and you evaluate it using `NULL`, the + result is a Boolean false . This is because the attribute " `a`" + exists; its data type is not relevant to the `NULL` comparison + operator. + + `CONTAINS` : Checks for a subsequence, or value in a set. + AttributeValueList can contain only one AttributeValue element of + type String, Number, or Binary (not a set type). If the target + attribute of the comparison is of type String, then the operator + checks for a substring match. If the target attribute of the + comparison is of type Binary, then the operator looks for a + subsequence of the target that matches the input. If the target + attribute of the comparison is a set (" `SS`", " `NS`", or " + `BS`"), then the operator evaluates to true if it finds an exact + match with any member of the set. CONTAINS is supported for lists: + When evaluating " `a CONTAINS b`", " `a`" can be a list; however, " + `b`" cannot be a set, a map, or a list. + + `NOT_CONTAINS` : Checks for absence of a subsequence, or absence of a + value in a set. AttributeValueList can contain only one + AttributeValue element of type String, Number, or Binary (not a set + type). If the target attribute of the comparison is a String, then + the operator checks for the absence of a substring match. If the + target attribute of the comparison is Binary, then the operator + checks for the absence of a subsequence of the target that matches + the input. If the target attribute of the comparison is a set (" + `SS`", " `NS`", or " `BS`"), then the operator evaluates to true if + it does not find an exact match with any member of the set. + NOT_CONTAINS is supported for lists: When evaluating " `a NOT + CONTAINS b`", " `a`" can be a list; however, " `b`" cannot be a + set, a map, or a list. + + `BEGINS_WITH` : Checks for a prefix. AttributeValueList can contain + only one AttributeValue of type String or Binary (not a Number or a + set type). The target attribute of the comparison must be of type + String or Binary (not a Number or a set type). > <li> + + `IN` : Checks for matching elements within two sets. + AttributeValueList can contain one or more AttributeValue elements + of type String, Number, or Binary (not a set type). These + attributes are compared against an existing set type attribute of + an item. If any elements of the input set are present in the item + attribute, the expression evaluates to true. + + `BETWEEN` : Greater than or equal to the first value, and less than + or equal to the second value. AttributeValueList must contain two + AttributeValue elements of the same type, either String, Number, or + Binary (not a set type). A target attribute matches if the target + value is greater than, or equal to, the first element and less + than, or equal to, the second element. If an item contains an + AttributeValue element of a different type than the one specified + in the request, the value does not match. For example, `{"S":"6"}` + does not compare to `{"N":"6"}`. Also, `{"N":"6"}` does not compare + to `{"NS":["6", "2", "1"]}` + + + + For usage examples of AttributeValueList and ComparisonOperator , see + `Legacy Conditional Parameters`_ in the Amazon DynamoDB Developer + Guide . + + For backward compatibility with previous DynamoDB releases, the + following parameters can be used instead of AttributeValueList and + ComparisonOperator : + + + + Value - A value for DynamoDB to compare with an attribute. + + Exists - A Boolean value that causes DynamoDB to evaluate the value + before attempting the conditional operation: + + + If Exists is `True`, DynamoDB will check to see if that attribute + value already exists in the table. If it is found, then the + condition evaluates to true; otherwise the condition evaluate to + false. + + If Exists is `False`, DynamoDB assumes that the attribute value does + not exist in the table. If in fact the value does not exist, then + the assumption is valid and the condition evaluates to true. If the + value is found, despite the assumption that it does not exist, the + condition evaluates to false. + Note that the default value for Exists is `True`. + + + The Value and Exists parameters are incompatible with + AttributeValueList and ComparisonOperator . Note that if you use + both sets of parameters at once, DynamoDB will return a + ValidationException exception. + + :type conditional_operator: string + :param conditional_operator: + There is a newer parameter available. Use ConditionExpression instead. + Note that if you use ConditionalOperator and ConditionExpression at + the same time, DynamoDB will return a ValidationException + exception. + + This parameter does not support lists or maps. + + A logical operator to apply to the conditions in the Expected map: + + + + `AND` - If all of the conditions evaluate to true, then the entire + map evaluates to true. + + `OR` - If at least one of the conditions evaluate to true, then the + entire map evaluates to true. + + + If you omit ConditionalOperator , then `AND` is the default. + + The operation will succeed only if the entire map evaluates to true. + + :type return_values: string + :param return_values: + Use ReturnValues if you want to get the item attributes as they + appeared before they were deleted. For DeleteItem , the valid + values are: + + + + `NONE` - If ReturnValues is not specified, or if its value is `NONE`, + then nothing is returned. (This setting is the default for + ReturnValues .) + + `ALL_OLD` - The content of the old item is returned. + + :type return_consumed_capacity: string + :param return_consumed_capacity: A value that if set to `TOTAL`, the + response includes ConsumedCapacity data for tables and indexes. If + set to `INDEXES`, the response includes ConsumedCapacity for + indexes. If set to `NONE` (the default), ConsumedCapacity is not + included in the response. + + :type return_item_collection_metrics: string + :param return_item_collection_metrics: A value that if set to `SIZE`, + the response includes statistics about item collections, if any, + that were modified during the operation are returned in the + response. If set to `NONE` (the default), no statistics are + returned. + + :type condition_expression: string + :param condition_expression: A condition that must be satisfied in + order for a conditional DeleteItem to succeed. + An expression can contain any of the following: + + + + Boolean functions: `attribute_exists | attribute_not_exists | + contains | begins_with` These function names are case-sensitive. + + Comparison operators: ` = | <> | < | > | <= + | >= | BETWEEN | IN` + + Logical operators: `AND | OR | NOT` + + + For more information on condition expressions, go to `Specifying + Conditions`_ in the Amazon DynamoDB Developer Guide . + + :type expression_attribute_names: map + :param expression_attribute_names: One or more substitution tokens for + simplifying complex expressions. The following are some use cases + for using ExpressionAttributeNames : + + + To shorten an attribute name that is very long or unwieldy in an + expression. + + To create a placeholder for repeating occurrences of an attribute + name in an expression. + + To prevent special characters in an attribute name from being + misinterpreted in an expression. + + + Use the **#** character in an expression to dereference an attribute + name. For example, consider the following expression: + + + + `order.customerInfo.LastName = "Smith" OR order.customerInfo.LastName + = "Jones"` + + + Now suppose that you specified the following for + ExpressionAttributeNames : + + + + `{"#name":"order.customerInfo.LastName"}` + + + The expression can now be simplified as follows: + + + + `#name = "Smith" OR #name = "Jones"` + + + For more information on expression attribute names, go to `Accessing + Item Attributes`_ in the Amazon DynamoDB Developer Guide . + + :type expression_attribute_values: map + :param expression_attribute_values: One or more values that can be + substituted in an expression. + Use the **:** (colon) character in an expression to dereference an + attribute value. For example, suppose that you wanted to check + whether the value of the ProductStatus attribute was one of the + following: + + `Available | Backordered | Discontinued` + + You would first need to specify ExpressionAttributeValues as follows: + + `{ ":avail":{"S":"Available"}, ":back":{"S":"Backordered"}, + ":disc":{"S":"Discontinued"} }` + + You could then use these values in an expression, such as this: + + `ProductStatus IN (:avail, :back, :disc)` + + For more information on expression attribute values, go to `Specifying + Conditions`_ in the Amazon DynamoDB Developer Guide . + + """ + params = {'TableName': table_name, 'Key': key, } + if expected is not None: + params['Expected'] = expected + if conditional_operator is not None: + params['ConditionalOperator'] = conditional_operator + if return_values is not None: + params['ReturnValues'] = return_values + if return_consumed_capacity is not None: + params['ReturnConsumedCapacity'] = return_consumed_capacity + if return_item_collection_metrics is not None: + params['ReturnItemCollectionMetrics'] = return_item_collection_metrics + if condition_expression is not None: + params['ConditionExpression'] = condition_expression + if expression_attribute_names is not None: + params['ExpressionAttributeNames'] = expression_attribute_names + if expression_attribute_values is not None: + params['ExpressionAttributeValues'] = expression_attribute_values + return self.make_request(action='DeleteItem', + body=json.dumps(params)) + + def delete_table(self, table_name): + """ + The DeleteTable operation deletes a table and all of its + items. After a DeleteTable request, the specified table is in + the `DELETING` state until DynamoDB completes the deletion. If + the table is in the `ACTIVE` state, you can delete it. If a + table is in `CREATING` or `UPDATING` states, then DynamoDB + returns a ResourceInUseException . If the specified table does + not exist, DynamoDB returns a ResourceNotFoundException . If + table is already in the `DELETING` state, no error is + returned. + + + DynamoDB might continue to accept data read and write + operations, such as GetItem and PutItem , on a table in the + `DELETING` state until the table deletion is complete. + + + When you delete a table, any indexes on that table are also + deleted. + + Use the DescribeTable API to check the status of the table. + + :type table_name: string + :param table_name: The name of the table to delete. + + """ + params = {'TableName': table_name, } + return self.make_request(action='DeleteTable', + body=json.dumps(params)) + + def describe_table(self, table_name): + """ + Returns information about the table, including the current + status of the table, when it was created, the primary key + schema, and any indexes on the table. + + + If you issue a DescribeTable request immediately after a + CreateTable request, DynamoDB might return a + ResourceNotFoundException. This is because DescribeTable uses + an eventually consistent query, and the metadata for your + table might not be available at that moment. Wait for a few + seconds, and then try the DescribeTable request again. + + :type table_name: string + :param table_name: The name of the table to describe. + + """ + params = {'TableName': table_name, } + return self.make_request(action='DescribeTable', + body=json.dumps(params)) + + def get_item(self, table_name, key, attributes_to_get=None, + consistent_read=None, return_consumed_capacity=None, + projection_expression=None, expression_attribute_names=None): + """ + The GetItem operation returns a set of attributes for the item + with the given primary key. If there is no matching item, + GetItem does not return any data. + + GetItem provides an eventually consistent read by default. If + your application requires a strongly consistent read, set + ConsistentRead to `True`. Although a strongly consistent read + might take more time than an eventually consistent read, it + always returns the last updated value. + + :type table_name: string + :param table_name: The name of the table containing the requested item. + + :type key: map + :param key: A map of attribute names to AttributeValue objects, + representing the primary key of the item to retrieve. + For the primary key, you must provide all of the attributes. For + example, with a hash type primary key, you only need to specify the + hash attribute. For a hash-and-range type primary key, you must + specify both the hash attribute and the range attribute. + + :type attributes_to_get: list + :param attributes_to_get: + There is a newer parameter available. Use ProjectionExpression instead. + Note that if you use AttributesToGet and ProjectionExpression at + the same time, DynamoDB will return a ValidationException + exception. + + This parameter allows you to retrieve lists or maps; however, it cannot + retrieve individual list or map elements. + + The names of one or more attributes to retrieve. If no attribute names + are specified, then all attributes will be returned. If any of the + requested attributes are not found, they will not appear in the + result. + + Note that AttributesToGet has no effect on provisioned throughput + consumption. DynamoDB determines capacity units consumed based on + item size, not on the amount of data that is returned to an + application. + + :type consistent_read: boolean + :param consistent_read: A value that if set to `True`, then the + operation uses strongly consistent reads; otherwise, eventually + consistent reads are used. + + :type return_consumed_capacity: string + :param return_consumed_capacity: A value that if set to `TOTAL`, the + response includes ConsumedCapacity data for tables and indexes. If + set to `INDEXES`, the response includes ConsumedCapacity for + indexes. If set to `NONE` (the default), ConsumedCapacity is not + included in the response. + + :type projection_expression: string + :param projection_expression: A string that identifies one or more + attributes to retrieve from the table. These attributes can include + scalars, sets, or elements of a JSON document. The attributes in + the expression must be separated by commas. + If no attribute names are specified, then all attributes will be + returned. If any of the requested attributes are not found, they + will not appear in the result. + + For more information on projection expressions, go to `Accessing Item + Attributes`_ in the Amazon DynamoDB Developer Guide . + + :type expression_attribute_names: map + :param expression_attribute_names: One or more substitution tokens for + simplifying complex expressions. The following are some use cases + for using ExpressionAttributeNames : + + + To shorten an attribute name that is very long or unwieldy in an + expression. + + To create a placeholder for repeating occurrences of an attribute + name in an expression. + + To prevent special characters in an attribute name from being + misinterpreted in an expression. + + + Use the **#** character in an expression to dereference an attribute + name. For example, consider the following expression: + + + + `order.customerInfo.LastName = "Smith" OR order.customerInfo.LastName + = "Jones"` + + + Now suppose that you specified the following for + ExpressionAttributeNames : + + + + `{"#name":"order.customerInfo.LastName"}` + + + The expression can now be simplified as follows: + + + + `#name = "Smith" OR #name = "Jones"` + + + For more information on expression attribute names, go to `Accessing + Item Attributes`_ in the Amazon DynamoDB Developer Guide . + + """ + params = {'TableName': table_name, 'Key': key, } + if attributes_to_get is not None: + params['AttributesToGet'] = attributes_to_get + if consistent_read is not None: + params['ConsistentRead'] = consistent_read + if return_consumed_capacity is not None: + params['ReturnConsumedCapacity'] = return_consumed_capacity + if projection_expression is not None: + params['ProjectionExpression'] = projection_expression + if expression_attribute_names is not None: + params['ExpressionAttributeNames'] = expression_attribute_names + return self.make_request(action='GetItem', + body=json.dumps(params)) + + def list_tables(self, exclusive_start_table_name=None, limit=None): + """ + Returns an array of table names associated with the current + account and endpoint. The output from ListTables is paginated, + with each page returning a maximum of 100 table names. + + :type exclusive_start_table_name: string + :param exclusive_start_table_name: The first table name that this + operation will evaluate. Use the value that was returned for + LastEvaluatedTableName in a previous operation, so that you can + obtain the next page of results. + + :type limit: integer + :param limit: A maximum number of table names to return. If this + parameter is not specified, the limit is 100. + + """ + params = {} + if exclusive_start_table_name is not None: + params['ExclusiveStartTableName'] = exclusive_start_table_name + if limit is not None: + params['Limit'] = limit + return self.make_request(action='ListTables', + body=json.dumps(params)) + + def put_item(self, table_name, item, expected=None, return_values=None, + return_consumed_capacity=None, + return_item_collection_metrics=None, + conditional_operator=None, condition_expression=None, + expression_attribute_names=None, + expression_attribute_values=None): + """ + Creates a new item, or replaces an old item with a new item. + If an item that has the same primary key as the new item + already exists in the specified table, the new item completely + replaces the existing item. You can perform a conditional put + operation (add a new item if one with the specified primary + key doesn't exist), or replace an existing item if it has + certain attribute values. + + In addition to putting an item, you can also return the item's + attribute values in the same operation, using the ReturnValues + parameter. + + When you add an item, the primary key attribute(s) are the + only required attributes. Attribute values cannot be null. + String and Binary type attributes must have lengths greater + than zero. Set type attributes cannot be empty. Requests with + empty values will be rejected with a ValidationException + exception. + + You can request that PutItem return either a copy of the + original item (before the update) or a copy of the updated + item (after the update). For more information, see the + ReturnValues description below. + + + To prevent a new item from replacing an existing item, use a + conditional put operation with ComparisonOperator set to + `NULL` for the primary key attribute, or attributes. + + + For more information about using this API, see `Working with + Items`_ in the Amazon DynamoDB Developer Guide . + + :type table_name: string + :param table_name: The name of the table to contain the item. + + :type item: map + :param item: A map of attribute name/value pairs, one for each + attribute. Only the primary key attributes are required; you can + optionally provide other attribute name-value pairs for the item. + You must provide all of the attributes for the primary key. For + example, with a hash type primary key, you only need to specify the + hash attribute. For a hash-and-range type primary key, you must + specify both the hash attribute and the range attribute. + + If you specify any attributes that are part of an index key, then the + data types for those attributes must match those of the schema in + the table's attribute definition. + + For more information about primary keys, see `Primary Key`_ in the + Amazon DynamoDB Developer Guide . + + Each element in the Item map is an AttributeValue object. + + :type expected: map + :param expected: + There is a newer parameter available. Use ConditionExpression instead. + Note that if you use Expected and ConditionExpression at the same + time, DynamoDB will return a ValidationException exception. + + This parameter does not support lists or maps. + + A map of attribute/condition pairs. Expected provides a conditional + block for the PutItem operation. + + Each element of Expected consists of an attribute name, a comparison + operator, and one or more values. DynamoDB compares the attribute + with the value(s) you supplied, using the comparison operator. For + each Expected element, the result of the evaluation is either true + or false. + + If you specify more than one element in the Expected map, then by + default all of the conditions must evaluate to true. In other + words, the conditions are ANDed together. (You can use the + ConditionalOperator parameter to OR the conditions instead. If you + do this, then at least one of the conditions must evaluate to true, + rather than all of them.) + + If the Expected map evaluates to true, then the conditional operation + succeeds; otherwise, it fails. + + Expected contains the following: + + + + AttributeValueList - One or more values to evaluate against the + supplied attribute. The number of values in the list depends on the + ComparisonOperator being used. For type Number, value comparisons + are numeric. String value comparisons for greater than, equals, or + less than are based on ASCII character code values. For example, + `a` is greater than `A`, and `a` is greater than `B`. For a list of + code values, see + `http://en.wikipedia.org/wiki/ASCII#ASCII_printable_characters`_. + For type Binary, DynamoDB treats each byte of the binary data as + unsigned when it compares binary values, for example when + evaluating query expressions. + + ComparisonOperator - A comparator for evaluating attributes in the + AttributeValueList . When performing the comparison, DynamoDB uses + strongly consistent reads. The following comparison operators are + available: `EQ | NE | LE | LT | GE | GT | NOT_NULL | NULL | + CONTAINS | NOT_CONTAINS | BEGINS_WITH | IN | BETWEEN` The following + are descriptions of each comparison operator. + + + `EQ` : Equal. `EQ` is supported for all datatypes, including lists + and maps. AttributeValueList can contain only one AttributeValue + element of type String, Number, Binary, String Set, Number Set, or + Binary Set. If an item contains an AttributeValue element of a + different type than the one specified in the request, the value + does not match. For example, `{"S":"6"}` does not equal + `{"N":"6"}`. Also, `{"N":"6"}` does not equal `{"NS":["6", "2", + "1"]}`. > <li> + + `NE` : Not equal. `NE` is supported for all datatypes, including + lists and maps. AttributeValueList can contain only one + AttributeValue of type String, Number, Binary, String Set, Number + Set, or Binary Set. If an item contains an AttributeValue of a + different type than the one specified in the request, the value + does not match. For example, `{"S":"6"}` does not equal + `{"N":"6"}`. Also, `{"N":"6"}` does not equal `{"NS":["6", "2", + "1"]}`. > <li> + + `LE` : Less than or equal. AttributeValueList can contain only one + AttributeValue element of type String, Number, or Binary (not a set + type). If an item contains an AttributeValue element of a different + type than the one specified in the request, the value does not + match. For example, `{"S":"6"}` does not equal `{"N":"6"}`. Also, + `{"N":"6"}` does not compare to `{"NS":["6", "2", "1"]}`. > <li> + + `LT` : Less than. AttributeValueList can contain only one + AttributeValue of type String, Number, or Binary (not a set type). + If an item contains an AttributeValue element of a different type + than the one specified in the request, the value does not match. + For example, `{"S":"6"}` does not equal `{"N":"6"}`. Also, + `{"N":"6"}` does not compare to `{"NS":["6", "2", "1"]}`. > <li> + + `GE` : Greater than or equal. AttributeValueList can contain only one + AttributeValue element of type String, Number, or Binary (not a set + type). If an item contains an AttributeValue element of a different + type than the one specified in the request, the value does not + match. For example, `{"S":"6"}` does not equal `{"N":"6"}`. Also, + `{"N":"6"}` does not compare to `{"NS":["6", "2", "1"]}`. > <li> + + `GT` : Greater than. AttributeValueList can contain only one + AttributeValue element of type String, Number, or Binary (not a set + type). If an item contains an AttributeValue element of a different + type than the one specified in the request, the value does not + match. For example, `{"S":"6"}` does not equal `{"N":"6"}`. Also, + `{"N":"6"}` does not compare to `{"NS":["6", "2", "1"]}`. > <li> + + `NOT_NULL` : The attribute exists. `NOT_NULL` is supported for all + datatypes, including lists and maps. This operator tests for the + existence of an attribute, not its data type. If the data type of + attribute " `a`" is null, and you evaluate it using `NOT_NULL`, the + result is a Boolean true . This result is because the attribute " + `a`" exists; its data type is not relevant to the `NOT_NULL` + comparison operator. + + `NULL` : The attribute does not exist. `NULL` is supported for all + datatypes, including lists and maps. This operator tests for the + nonexistence of an attribute, not its data type. If the data type + of attribute " `a`" is null, and you evaluate it using `NULL`, the + result is a Boolean false . This is because the attribute " `a`" + exists; its data type is not relevant to the `NULL` comparison + operator. + + `CONTAINS` : Checks for a subsequence, or value in a set. + AttributeValueList can contain only one AttributeValue element of + type String, Number, or Binary (not a set type). If the target + attribute of the comparison is of type String, then the operator + checks for a substring match. If the target attribute of the + comparison is of type Binary, then the operator looks for a + subsequence of the target that matches the input. If the target + attribute of the comparison is a set (" `SS`", " `NS`", or " + `BS`"), then the operator evaluates to true if it finds an exact + match with any member of the set. CONTAINS is supported for lists: + When evaluating " `a CONTAINS b`", " `a`" can be a list; however, " + `b`" cannot be a set, a map, or a list. + + `NOT_CONTAINS` : Checks for absence of a subsequence, or absence of a + value in a set. AttributeValueList can contain only one + AttributeValue element of type String, Number, or Binary (not a set + type). If the target attribute of the comparison is a String, then + the operator checks for the absence of a substring match. If the + target attribute of the comparison is Binary, then the operator + checks for the absence of a subsequence of the target that matches + the input. If the target attribute of the comparison is a set (" + `SS`", " `NS`", or " `BS`"), then the operator evaluates to true if + it does not find an exact match with any member of the set. + NOT_CONTAINS is supported for lists: When evaluating " `a NOT + CONTAINS b`", " `a`" can be a list; however, " `b`" cannot be a + set, a map, or a list. + + `BEGINS_WITH` : Checks for a prefix. AttributeValueList can contain + only one AttributeValue of type String or Binary (not a Number or a + set type). The target attribute of the comparison must be of type + String or Binary (not a Number or a set type). > <li> + + `IN` : Checks for matching elements within two sets. + AttributeValueList can contain one or more AttributeValue elements + of type String, Number, or Binary (not a set type). These + attributes are compared against an existing set type attribute of + an item. If any elements of the input set are present in the item + attribute, the expression evaluates to true. + + `BETWEEN` : Greater than or equal to the first value, and less than + or equal to the second value. AttributeValueList must contain two + AttributeValue elements of the same type, either String, Number, or + Binary (not a set type). A target attribute matches if the target + value is greater than, or equal to, the first element and less + than, or equal to, the second element. If an item contains an + AttributeValue element of a different type than the one specified + in the request, the value does not match. For example, `{"S":"6"}` + does not compare to `{"N":"6"}`. Also, `{"N":"6"}` does not compare + to `{"NS":["6", "2", "1"]}` + + + + For usage examples of AttributeValueList and ComparisonOperator , see + `Legacy Conditional Parameters`_ in the Amazon DynamoDB Developer + Guide . + + For backward compatibility with previous DynamoDB releases, the + following parameters can be used instead of AttributeValueList and + ComparisonOperator : + + + + Value - A value for DynamoDB to compare with an attribute. + + Exists - A Boolean value that causes DynamoDB to evaluate the value + before attempting the conditional operation: + + + If Exists is `True`, DynamoDB will check to see if that attribute + value already exists in the table. If it is found, then the + condition evaluates to true; otherwise the condition evaluate to + false. + + If Exists is `False`, DynamoDB assumes that the attribute value does + not exist in the table. If in fact the value does not exist, then + the assumption is valid and the condition evaluates to true. If the + value is found, despite the assumption that it does not exist, the + condition evaluates to false. + Note that the default value for Exists is `True`. + + + The Value and Exists parameters are incompatible with + AttributeValueList and ComparisonOperator . Note that if you use + both sets of parameters at once, DynamoDB will return a + ValidationException exception. + + :type return_values: string + :param return_values: + Use ReturnValues if you want to get the item attributes as they + appeared before they were updated with the PutItem request. For + PutItem , the valid values are: + + + + `NONE` - If ReturnValues is not specified, or if its value is `NONE`, + then nothing is returned. (This setting is the default for + ReturnValues .) + + `ALL_OLD` - If PutItem overwrote an attribute name-value pair, then + the content of the old item is returned. + + :type return_consumed_capacity: string + :param return_consumed_capacity: A value that if set to `TOTAL`, the + response includes ConsumedCapacity data for tables and indexes. If + set to `INDEXES`, the response includes ConsumedCapacity for + indexes. If set to `NONE` (the default), ConsumedCapacity is not + included in the response. + + :type return_item_collection_metrics: string + :param return_item_collection_metrics: A value that if set to `SIZE`, + the response includes statistics about item collections, if any, + that were modified during the operation are returned in the + response. If set to `NONE` (the default), no statistics are + returned. + + :type conditional_operator: string + :param conditional_operator: + There is a newer parameter available. Use ConditionExpression instead. + Note that if you use ConditionalOperator and ConditionExpression at + the same time, DynamoDB will return a ValidationException + exception. + + This parameter does not support lists or maps. + + A logical operator to apply to the conditions in the Expected map: + + + + `AND` - If all of the conditions evaluate to true, then the entire + map evaluates to true. + + `OR` - If at least one of the conditions evaluate to true, then the + entire map evaluates to true. + + + If you omit ConditionalOperator , then `AND` is the default. + + The operation will succeed only if the entire map evaluates to true. + + :type condition_expression: string + :param condition_expression: A condition that must be satisfied in + order for a conditional PutItem operation to succeed. + An expression can contain any of the following: + + + + Boolean functions: `attribute_exists | attribute_not_exists | + contains | begins_with` These function names are case-sensitive. + + Comparison operators: ` = | <> | < | > | <= + | >= | BETWEEN | IN` + + Logical operators: `AND | OR | NOT` + + + For more information on condition expressions, go to `Specifying + Conditions`_ in the Amazon DynamoDB Developer Guide . + + :type expression_attribute_names: map + :param expression_attribute_names: One or more substitution tokens for + simplifying complex expressions. The following are some use cases + for using ExpressionAttributeNames : + + + To shorten an attribute name that is very long or unwieldy in an + expression. + + To create a placeholder for repeating occurrences of an attribute + name in an expression. + + To prevent special characters in an attribute name from being + misinterpreted in an expression. + + + Use the **#** character in an expression to dereference an attribute + name. For example, consider the following expression: + + + + `order.customerInfo.LastName = "Smith" OR order.customerInfo.LastName + = "Jones"` + + + Now suppose that you specified the following for + ExpressionAttributeNames : + + + + `{"#name":"order.customerInfo.LastName"}` + + + The expression can now be simplified as follows: + + + + `#name = "Smith" OR #name = "Jones"` + + + For more information on expression attribute names, go to `Accessing + Item Attributes`_ in the Amazon DynamoDB Developer Guide . + + :type expression_attribute_values: map + :param expression_attribute_values: One or more values that can be + substituted in an expression. + Use the **:** (colon) character in an expression to dereference an + attribute value. For example, suppose that you wanted to check + whether the value of the ProductStatus attribute was one of the + following: + + `Available | Backordered | Discontinued` + + You would first need to specify ExpressionAttributeValues as follows: + + `{ ":avail":{"S":"Available"}, ":back":{"S":"Backordered"}, + ":disc":{"S":"Discontinued"} }` + + You could then use these values in an expression, such as this: + + `ProductStatus IN (:avail, :back, :disc)` + + For more information on expression attribute values, go to `Specifying + Conditions`_ in the Amazon DynamoDB Developer Guide . + + """ + params = {'TableName': table_name, 'Item': item, } + if expected is not None: + params['Expected'] = expected + if return_values is not None: + params['ReturnValues'] = return_values + if return_consumed_capacity is not None: + params['ReturnConsumedCapacity'] = return_consumed_capacity + if return_item_collection_metrics is not None: + params['ReturnItemCollectionMetrics'] = return_item_collection_metrics + if conditional_operator is not None: + params['ConditionalOperator'] = conditional_operator + if condition_expression is not None: + params['ConditionExpression'] = condition_expression + if expression_attribute_names is not None: + params['ExpressionAttributeNames'] = expression_attribute_names + if expression_attribute_values is not None: + params['ExpressionAttributeValues'] = expression_attribute_values + return self.make_request(action='PutItem', + body=json.dumps(params)) + + def query(self, table_name, key_conditions, index_name=None, select=None, + attributes_to_get=None, limit=None, consistent_read=None, + query_filter=None, conditional_operator=None, + scan_index_forward=None, exclusive_start_key=None, + return_consumed_capacity=None, projection_expression=None, + filter_expression=None, expression_attribute_names=None, + expression_attribute_values=None): + """ + A Query operation directly accesses items from a table using + the table primary key, or from an index using the index key. + You must provide a specific hash key value. You can narrow the + scope of the query by using comparison operators on the range + key value, or on the index key. You can use the + ScanIndexForward parameter to get results in forward or + reverse order, by range key or by index key. + + Queries that do not return results consume the minimum number + of read capacity units for that type of read operation. + + If the total number of items meeting the query criteria + exceeds the result set size limit of 1 MB, the query stops and + results are returned to the user with LastEvaluatedKey to + continue the query in a subsequent operation. Unlike a Scan + operation, a Query operation never returns both an empty + result set and a LastEvaluatedKey . The LastEvaluatedKey is + only provided if the results exceed 1 MB, or if you have used + Limit . + + You can query a table, a local secondary index, or a global + secondary index. For a query on a table or on a local + secondary index, you can set ConsistentRead to true and obtain + a strongly consistent result. Global secondary indexes support + eventually consistent reads only, so do not specify + ConsistentRead when querying a global secondary index. + + :type table_name: string + :param table_name: The name of the table containing the requested + items. + + :type index_name: string + :param index_name: The name of an index to query. This index can be any + local secondary index or global secondary index on the table. + + :type select: string + :param select: The attributes to be returned in the result. You can + retrieve all item attributes, specific item attributes, the count + of matching items, or in the case of an index, some or all of the + attributes projected into the index. + + + `ALL_ATTRIBUTES` - Returns all of the item attributes from the + specified table or index. If you query a local secondary index, + then for each matching item in the index DynamoDB will fetch the + entire item from the parent table. If the index is configured to + project all item attributes, then all of the data can be obtained + from the local secondary index, and no fetching is required. + + `ALL_PROJECTED_ATTRIBUTES` - Allowed only when querying an index. + Retrieves all attributes that have been projected into the index. + If the index is configured to project all attributes, this return + value is equivalent to specifying `ALL_ATTRIBUTES`. + + `COUNT` - Returns the number of matching items, rather than the + matching items themselves. + + `SPECIFIC_ATTRIBUTES` - Returns only the attributes listed in + AttributesToGet . This return value is equivalent to specifying + AttributesToGet without specifying any value for Select . If you + query a local secondary index and request only attributes that are + projected into that index, the operation will read only the index + and not the table. If any of the requested attributes are not + projected into the local secondary index, DynamoDB will fetch each + of these attributes from the parent table. This extra fetching + incurs additional throughput cost and latency. If you query a + global secondary index, you can only request attributes that are + projected into the index. Global secondary index queries cannot + fetch attributes from the parent table. + + + If neither Select nor AttributesToGet are specified, DynamoDB defaults + to `ALL_ATTRIBUTES` when accessing a table, and + `ALL_PROJECTED_ATTRIBUTES` when accessing an index. You cannot use + both Select and AttributesToGet together in a single request, + unless the value for Select is `SPECIFIC_ATTRIBUTES`. (This usage + is equivalent to specifying AttributesToGet without any value for + Select .) + + :type attributes_to_get: list + :param attributes_to_get: + There is a newer parameter available. Use ProjectionExpression instead. + Note that if you use AttributesToGet and ProjectionExpression at + the same time, DynamoDB will return a ValidationException + exception. + + This parameter allows you to retrieve lists or maps; however, it cannot + retrieve individual list or map elements. + + The names of one or more attributes to retrieve. If no attribute names + are specified, then all attributes will be returned. If any of the + requested attributes are not found, they will not appear in the + result. + + Note that AttributesToGet has no effect on provisioned throughput + consumption. DynamoDB determines capacity units consumed based on + item size, not on the amount of data that is returned to an + application. + + You cannot use both AttributesToGet and Select together in a Query + request, unless the value for Select is `SPECIFIC_ATTRIBUTES`. + (This usage is equivalent to specifying AttributesToGet without any + value for Select .) + + If you query a local secondary index and request only attributes that + are projected into that index, the operation will read only the + index and not the table. If any of the requested attributes are not + projected into the local secondary index, DynamoDB will fetch each + of these attributes from the parent table. This extra fetching + incurs additional throughput cost and latency. + + If you query a global secondary index, you can only request attributes + that are projected into the index. Global secondary index queries + cannot fetch attributes from the parent table. + + :type limit: integer + :param limit: The maximum number of items to evaluate (not necessarily + the number of matching items). If DynamoDB processes the number of + items up to the limit while processing the results, it stops the + operation and returns the matching values up to that point, and a + key in LastEvaluatedKey to apply in a subsequent operation, so that + you can pick up where you left off. Also, if the processed data set + size exceeds 1 MB before DynamoDB reaches this limit, it stops the + operation and returns the matching values up to the limit, and a + key in LastEvaluatedKey to apply in a subsequent operation to + continue the operation. For more information, see `Query and Scan`_ + in the Amazon DynamoDB Developer Guide . + + :type consistent_read: boolean + :param consistent_read: A value that if set to `True`, then the + operation uses strongly consistent reads; otherwise, eventually + consistent reads are used. + Strongly consistent reads are not supported on global secondary + indexes. If you query a global secondary index with ConsistentRead + set to `True`, you will receive an error message. + + :type key_conditions: map + :param key_conditions: The selection criteria for the query. For a + query on a table, you can have conditions only on the table primary + key attributes. You must specify the hash key attribute name and + value as an `EQ` condition. You can optionally specify a second + condition, referring to the range key attribute. If you do not + specify a range key condition, all items under the hash key will be + fetched and processed. Any filters will applied after this. + For a query on an index, you can have conditions only on the index key + attributes. You must specify the index hash attribute name and + value as an EQ condition. You can optionally specify a second + condition, referring to the index key range attribute. + + Each KeyConditions element consists of an attribute name to compare, + along with the following: + + + + AttributeValueList - One or more values to evaluate against the + supplied attribute. The number of values in the list depends on the + ComparisonOperator being used. For type Number, value comparisons + are numeric. String value comparisons for greater than, equals, or + less than are based on ASCII character code values. For example, + `a` is greater than `A`, and `a` is greater than `B`. For a list of + code values, see + `http://en.wikipedia.org/wiki/ASCII#ASCII_printable_characters`_. + For Binary, DynamoDB treats each byte of the binary data as + unsigned when it compares binary values, for example when + evaluating query expressions. + + ComparisonOperator - A comparator for evaluating attributes, for + example, equals, greater than, less than, and so on. For + KeyConditions , only the following comparison operators are + supported: `EQ | LE | LT | GE | GT | BEGINS_WITH | BETWEEN` The + following are descriptions of these comparison operators. + + + `EQ` : Equal. AttributeValueList can contain only one AttributeValue + of type String, Number, or Binary (not a set type). If an item + contains an AttributeValue element of a different type than the one + specified in the request, the value does not match. For example, + `{"S":"6"}` does not equal `{"N":"6"}`. Also, `{"N":"6"}` does not + equal `{"NS":["6", "2", "1"]}`. + + `LE` : Less than or equal. AttributeValueList can contain only one + AttributeValue element of type String, Number, or Binary (not a set + type). If an item contains an AttributeValue element of a different + type than the one specified in the request, the value does not + match. For example, `{"S":"6"}` does not equal `{"N":"6"}`. Also, + `{"N":"6"}` does not compare to `{"NS":["6", "2", "1"]}`. > <li> + + `LT` : Less than. AttributeValueList can contain only one + AttributeValue of type String, Number, or Binary (not a set type). + If an item contains an AttributeValue element of a different type + than the one specified in the request, the value does not match. + For example, `{"S":"6"}` does not equal `{"N":"6"}`. Also, + `{"N":"6"}` does not compare to `{"NS":["6", "2", "1"]}`. > <li> + + `GE` : Greater than or equal. AttributeValueList can contain only one + AttributeValue element of type String, Number, or Binary (not a set + type). If an item contains an AttributeValue element of a different + type than the one specified in the request, the value does not + match. For example, `{"S":"6"}` does not equal `{"N":"6"}`. Also, + `{"N":"6"}` does not compare to `{"NS":["6", "2", "1"]}`. > <li> + + `GT` : Greater than. AttributeValueList can contain only one + AttributeValue element of type String, Number, or Binary (not a set + type). If an item contains an AttributeValue element of a different + type than the one specified in the request, the value does not + match. For example, `{"S":"6"}` does not equal `{"N":"6"}`. Also, + `{"N":"6"}` does not compare to `{"NS":["6", "2", "1"]}`. > <li> + + `BEGINS_WITH` : Checks for a prefix. AttributeValueList can contain + only one AttributeValue of type String or Binary (not a Number or a + set type). The target attribute of the comparison must be of type + String or Binary (not a Number or a set type). > <li> + + `BETWEEN` : Greater than or equal to the first value, and less than + or equal to the second value. AttributeValueList must contain two + AttributeValue elements of the same type, either String, Number, or + Binary (not a set type). A target attribute matches if the target + value is greater than, or equal to, the first element and less + than, or equal to, the second element. If an item contains an + AttributeValue element of a different type than the one specified + in the request, the value does not match. For example, `{"S":"6"}` + does not compare to `{"N":"6"}`. Also, `{"N":"6"}` does not compare + to `{"NS":["6", "2", "1"]}` + + + + For usage examples of AttributeValueList and ComparisonOperator , see + `Legacy Conditional Parameters`_ in the Amazon DynamoDB Developer + Guide . + + :type query_filter: map + :param query_filter: + There is a newer parameter available. Use FilterExpression instead. + Note that if you use QueryFilter and FilterExpression at the same + time, DynamoDB will return a ValidationException exception. + + This parameter does not support lists or maps. + + A condition that evaluates the query results after the items are read + and returns only the desired values. + Query filters are applied after the items are read, so they do not + limit the capacity used. + If you specify more than one condition in the QueryFilter map, then by + default all of the conditions must evaluate to true. In other + words, the conditions are ANDed together. (You can use the + ConditionalOperator parameter to OR the conditions instead. If you + do this, then at least one of the conditions must evaluate to true, + rather than all of them.) + + + QueryFilter does not allow key attributes. You cannot define a filter + condition on a hash key or range key. + + + Each QueryFilter element consists of an attribute name to compare, + along with the following: + + + + AttributeValueList - One or more values to evaluate against the + supplied attribute. The number of values in the list depends on the + operator specified in ComparisonOperator . For type Number, value + comparisons are numeric. String value comparisons for greater than, + equals, or less than are based on ASCII character code values. For + example, `a` is greater than `A`, and `a` is greater than `B`. For + a list of code values, see + `http://en.wikipedia.org/wiki/ASCII#ASCII_printable_characters`_. + For type Binary, DynamoDB treats each byte of the binary data as + unsigned when it compares binary values, for example when + evaluating query expressions. For information on specifying data + types in JSON, see `JSON Data Format`_ in the Amazon DynamoDB + Developer Guide . + + ComparisonOperator - A comparator for evaluating attributes. For + example, equals, greater than, less than, etc. The following + comparison operators are available: `EQ | NE | LE | LT | GE | GT | + NOT_NULL | NULL | CONTAINS | NOT_CONTAINS | BEGINS_WITH | IN | + BETWEEN` For complete descriptions of all comparison operators, see + `API_Condition.html`_. + + :type conditional_operator: string + :param conditional_operator: + This parameter does not support lists or maps. + + A logical operator to apply to the conditions in the QueryFilter map: + + + + `AND` - If all of the conditions evaluate to true, then the entire + map evaluates to true. + + `OR` - If at least one of the conditions evaluate to true, then the + entire map evaluates to true. + + + If you omit ConditionalOperator , then `AND` is the default. + + The operation will succeed only if the entire map evaluates to true. + + :type scan_index_forward: boolean + :param scan_index_forward: A value that specifies ascending (true) or + descending (false) traversal of the index. DynamoDB returns results + reflecting the requested order determined by the range key. If the + data type is Number, the results are returned in numeric order. For + type String, the results are returned in order of ASCII character + code values. For type Binary, DynamoDB treats each byte of the + binary data as unsigned when it compares binary values. + If ScanIndexForward is not specified, the results are returned in + ascending order. + + :type exclusive_start_key: map + :param exclusive_start_key: The primary key of the first item that this + operation will evaluate. Use the value that was returned for + LastEvaluatedKey in the previous operation. + The data type for ExclusiveStartKey must be String, Number or Binary. + No set data types are allowed. + + :type return_consumed_capacity: string + :param return_consumed_capacity: A value that if set to `TOTAL`, the + response includes ConsumedCapacity data for tables and indexes. If + set to `INDEXES`, the response includes ConsumedCapacity for + indexes. If set to `NONE` (the default), ConsumedCapacity is not + included in the response. + + :type projection_expression: string + :param projection_expression: A string that identifies one or more + attributes to retrieve from the table. These attributes can include + scalars, sets, or elements of a JSON document. The attributes in + the expression must be separated by commas. + If no attribute names are specified, then all attributes will be + returned. If any of the requested attributes are not found, they + will not appear in the result. + + For more information on projection expressions, go to `Accessing Item + Attributes`_ in the Amazon DynamoDB Developer Guide . + + :type filter_expression: string + :param filter_expression: A condition that evaluates the query results + after the items are read and returns only the desired values. + The condition you specify is applied to the items queried; any items + that do not match the expression are not returned. + Filter expressions are applied after the items are read, so they do not + limit the capacity used. + A FilterExpression has the same syntax as a ConditionExpression . For + more information on expression syntax, go to `Specifying + Conditions`_ in the Amazon DynamoDB Developer Guide . + + :type expression_attribute_names: map + :param expression_attribute_names: One or more substitution tokens for + simplifying complex expressions. The following are some use cases + for using ExpressionAttributeNames : + + + To shorten an attribute name that is very long or unwieldy in an + expression. + + To create a placeholder for repeating occurrences of an attribute + name in an expression. + + To prevent special characters in an attribute name from being + misinterpreted in an expression. + + + Use the **#** character in an expression to dereference an attribute + name. For example, consider the following expression: + + + + `order.customerInfo.LastName = "Smith" OR order.customerInfo.LastName + = "Jones"` + + + Now suppose that you specified the following for + ExpressionAttributeNames : + + + + `{"#name":"order.customerInfo.LastName"}` + + + The expression can now be simplified as follows: + + + + `#name = "Smith" OR #name = "Jones"` + + + For more information on expression attribute names, go to `Accessing + Item Attributes`_ in the Amazon DynamoDB Developer Guide . + + :type expression_attribute_values: map + :param expression_attribute_values: One or more values that can be + substituted in an expression. + Use the **:** (colon) character in an expression to dereference an + attribute value. For example, suppose that you wanted to check + whether the value of the ProductStatus attribute was one of the + following: + + `Available | Backordered | Discontinued` + + You would first need to specify ExpressionAttributeValues as follows: + + `{ ":avail":{"S":"Available"}, ":back":{"S":"Backordered"}, + ":disc":{"S":"Discontinued"} }` + + You could then use these values in an expression, such as this: + + `ProductStatus IN (:avail, :back, :disc)` + + For more information on expression attribute values, go to `Specifying + Conditions`_ in the Amazon DynamoDB Developer Guide . + + """ + params = { + 'TableName': table_name, + 'KeyConditions': key_conditions, + } + if index_name is not None: + params['IndexName'] = index_name + if select is not None: + params['Select'] = select + if attributes_to_get is not None: + params['AttributesToGet'] = attributes_to_get + if limit is not None: + params['Limit'] = limit + if consistent_read is not None: + params['ConsistentRead'] = consistent_read + if query_filter is not None: + params['QueryFilter'] = query_filter + if conditional_operator is not None: + params['ConditionalOperator'] = conditional_operator + if scan_index_forward is not None: + params['ScanIndexForward'] = scan_index_forward + if exclusive_start_key is not None: + params['ExclusiveStartKey'] = exclusive_start_key + if return_consumed_capacity is not None: + params['ReturnConsumedCapacity'] = return_consumed_capacity + if projection_expression is not None: + params['ProjectionExpression'] = projection_expression + if filter_expression is not None: + params['FilterExpression'] = filter_expression + if expression_attribute_names is not None: + params['ExpressionAttributeNames'] = expression_attribute_names + if expression_attribute_values is not None: + params['ExpressionAttributeValues'] = expression_attribute_values + return self.make_request(action='Query', + body=json.dumps(params)) + + def scan(self, table_name, attributes_to_get=None, limit=None, + select=None, scan_filter=None, conditional_operator=None, + exclusive_start_key=None, return_consumed_capacity=None, + total_segments=None, segment=None, projection_expression=None, + filter_expression=None, expression_attribute_names=None, + expression_attribute_values=None): + """ + The Scan operation returns one or more items and item + attributes by accessing every item in the table. To have + DynamoDB return fewer items, you can provide a ScanFilter + operation. + + If the total number of scanned items exceeds the maximum data + set size limit of 1 MB, the scan stops and results are + returned to the user as a LastEvaluatedKey value to continue + the scan in a subsequent operation. The results also include + the number of items exceeding the limit. A scan can result in + no table data meeting the filter criteria. + + The result set is eventually consistent. + + By default, Scan operations proceed sequentially; however, for + faster performance on large tables, applications can request a + parallel Scan operation by specifying the Segment and + TotalSegments parameters. For more information, see `Parallel + Scan`_ in the Amazon DynamoDB Developer Guide . + + :type table_name: string + :param table_name: The name of the table containing the requested + items. + + :type attributes_to_get: list + :param attributes_to_get: + There is a newer parameter available. Use ProjectionExpression instead. + Note that if you use AttributesToGet and ProjectionExpression at + the same time, DynamoDB will return a ValidationException + exception. + + This parameter allows you to retrieve lists or maps; however, it cannot + retrieve individual list or map elements. + + The names of one or more attributes to retrieve. If no attribute names + are specified, then all attributes will be returned. If any of the + requested attributes are not found, they will not appear in the + result. + + Note that AttributesToGet has no effect on provisioned throughput + consumption. DynamoDB determines capacity units consumed based on + item size, not on the amount of data that is returned to an + application. + + :type limit: integer + :param limit: The maximum number of items to evaluate (not necessarily + the number of matching items). If DynamoDB processes the number of + items up to the limit while processing the results, it stops the + operation and returns the matching values up to that point, and a + key in LastEvaluatedKey to apply in a subsequent operation, so that + you can pick up where you left off. Also, if the processed data set + size exceeds 1 MB before DynamoDB reaches this limit, it stops the + operation and returns the matching values up to the limit, and a + key in LastEvaluatedKey to apply in a subsequent operation to + continue the operation. For more information, see `Query and Scan`_ + in the Amazon DynamoDB Developer Guide . + + :type select: string + :param select: The attributes to be returned in the result. You can + retrieve all item attributes, specific item attributes, or the + count of matching items. + + + `ALL_ATTRIBUTES` - Returns all of the item attributes. + + `COUNT` - Returns the number of matching items, rather than the + matching items themselves. + + `SPECIFIC_ATTRIBUTES` - Returns only the attributes listed in + AttributesToGet . This return value is equivalent to specifying + AttributesToGet without specifying any value for Select . + + + If neither Select nor AttributesToGet are specified, DynamoDB defaults + to `ALL_ATTRIBUTES`. You cannot use both AttributesToGet and Select + together in a single request, unless the value for Select is + `SPECIFIC_ATTRIBUTES`. (This usage is equivalent to specifying + AttributesToGet without any value for Select .) + + :type scan_filter: map + :param scan_filter: + There is a newer parameter available. Use FilterExpression instead. + Note that if you use ScanFilter and FilterExpression at the same + time, DynamoDB will return a ValidationException exception. + + This parameter does not support lists or maps. + + A condition that evaluates the scan results and returns only the + desired values. + + If you specify more than one condition in the ScanFilter map, then by + default all of the conditions must evaluate to true. In other + words, the conditions are ANDed together. (You can use the + ConditionalOperator parameter to OR the conditions instead. If you + do this, then at least one of the conditions must evaluate to true, + rather than all of them.) + + Each ScanFilter element consists of an attribute name to compare, along + with the following: + + + + AttributeValueList - One or more values to evaluate against the + supplied attribute. The number of values in the list depends on the + operator specified in ComparisonOperator . For type Number, value + comparisons are numeric. String value comparisons for greater than, + equals, or less than are based on ASCII character code values. For + example, `a` is greater than `A`, and `a` is greater than `B`. For + a list of code values, see + `http://en.wikipedia.org/wiki/ASCII#ASCII_printable_characters`_. + For Binary, DynamoDB treats each byte of the binary data as + unsigned when it compares binary values, for example when + evaluating query expressions. For information on specifying data + types in JSON, see `JSON Data Format`_ in the Amazon DynamoDB + Developer Guide . + + ComparisonOperator - A comparator for evaluating attributes. For + example, equals, greater than, less than, etc. The following + comparison operators are available: `EQ | NE | LE | LT | GE | GT | + NOT_NULL | NULL | CONTAINS | NOT_CONTAINS | BEGINS_WITH | IN | + BETWEEN` For complete descriptions of all comparison operators, see + `Condition`_. + + :type conditional_operator: string + :param conditional_operator: + There is a newer parameter available. Use ConditionExpression instead. + Note that if you use ConditionalOperator and ConditionExpression at + the same time, DynamoDB will return a ValidationException + exception. + + This parameter does not support lists or maps. + + A logical operator to apply to the conditions in the ScanFilter map: + + + + `AND` - If all of the conditions evaluate to true, then the entire + map evaluates to true. + + `OR` - If at least one of the conditions evaluate to true, then the + entire map evaluates to true. + + + If you omit ConditionalOperator , then `AND` is the default. + + The operation will succeed only if the entire map evaluates to true. + + :type exclusive_start_key: map + :param exclusive_start_key: The primary key of the first item that this + operation will evaluate. Use the value that was returned for + LastEvaluatedKey in the previous operation. + The data type for ExclusiveStartKey must be String, Number or Binary. + No set data types are allowed. + + In a parallel scan, a Scan request that includes ExclusiveStartKey must + specify the same segment whose previous Scan returned the + corresponding value of LastEvaluatedKey . + + :type return_consumed_capacity: string + :param return_consumed_capacity: A value that if set to `TOTAL`, the + response includes ConsumedCapacity data for tables and indexes. If + set to `INDEXES`, the response includes ConsumedCapacity for + indexes. If set to `NONE` (the default), ConsumedCapacity is not + included in the response. + + :type total_segments: integer + :param total_segments: For a parallel Scan request, TotalSegments + represents the total number of segments into which the Scan + operation will be divided. The value of TotalSegments corresponds + to the number of application workers that will perform the parallel + scan. For example, if you want to scan a table using four + application threads, specify a TotalSegments value of 4. + The value for TotalSegments must be greater than or equal to 1, and + less than or equal to 1000000. If you specify a TotalSegments value + of 1, the Scan operation will be sequential rather than parallel. + + If you specify TotalSegments , you must also specify Segment . + + :type segment: integer + :param segment: For a parallel Scan request, Segment identifies an + individual segment to be scanned by an application worker. + Segment IDs are zero-based, so the first segment is always 0. For + example, if you want to scan a table using four application + threads, the first thread specifies a Segment value of 0, the + second thread specifies 1, and so on. + + The value of LastEvaluatedKey returned from a parallel Scan request + must be used as ExclusiveStartKey with the same segment ID in a + subsequent Scan operation. + + The value for Segment must be greater than or equal to 0, and less than + the value provided for TotalSegments . + + If you specify Segment , you must also specify TotalSegments . + + :type projection_expression: string + :param projection_expression: A string that identifies one or more + attributes to retrieve from the table. These attributes can include + scalars, sets, or elements of a JSON document. The attributes in + the expression must be separated by commas. + If no attribute names are specified, then all attributes will be + returned. If any of the requested attributes are not found, they + will not appear in the result. + + For more information on projection expressions, go to `Accessing Item + Attributes`_ in the Amazon DynamoDB Developer Guide . + + :type filter_expression: string + :param filter_expression: A condition that evaluates the scan results + and returns only the desired values. + The condition you specify is applied to the items scanned; any items + that do not match the expression are not returned. + + :type expression_attribute_names: map + :param expression_attribute_names: One or more substitution tokens for + simplifying complex expressions. The following are some use cases + for using ExpressionAttributeNames : + + + To shorten an attribute name that is very long or unwieldy in an + expression. + + To create a placeholder for repeating occurrences of an attribute + name in an expression. + + To prevent special characters in an attribute name from being + misinterpreted in an expression. + + + Use the **#** character in an expression to dereference an attribute + name. For example, consider the following expression: + + + + `order.customerInfo.LastName = "Smith" OR order.customerInfo.LastName + = "Jones"` + + + Now suppose that you specified the following for + ExpressionAttributeNames : + + + + `{"#name":"order.customerInfo.LastName"}` + + + The expression can now be simplified as follows: + + + + `#name = "Smith" OR #name = "Jones"` + + + For more information on expression attribute names, go to `Accessing + Item Attributes`_ in the Amazon DynamoDB Developer Guide . + + :type expression_attribute_values: map + :param expression_attribute_values: One or more values that can be + substituted in an expression. + Use the **:** (colon) character in an expression to dereference an + attribute value. For example, suppose that you wanted to check + whether the value of the ProductStatus attribute was one of the + following: + + `Available | Backordered | Discontinued` + + You would first need to specify ExpressionAttributeValues as follows: + + `{ ":avail":{"S":"Available"}, ":back":{"S":"Backordered"}, + ":disc":{"S":"Discontinued"} }` + + You could then use these values in an expression, such as this: + + `ProductStatus IN (:avail, :back, :disc)` + + For more information on expression attribute values, go to `Specifying + Conditions`_ in the Amazon DynamoDB Developer Guide . + + """ + params = {'TableName': table_name, } + if attributes_to_get is not None: + params['AttributesToGet'] = attributes_to_get + if limit is not None: + params['Limit'] = limit + if select is not None: + params['Select'] = select + if scan_filter is not None: + params['ScanFilter'] = scan_filter + if conditional_operator is not None: + params['ConditionalOperator'] = conditional_operator + if exclusive_start_key is not None: + params['ExclusiveStartKey'] = exclusive_start_key + if return_consumed_capacity is not None: + params['ReturnConsumedCapacity'] = return_consumed_capacity + if total_segments is not None: + params['TotalSegments'] = total_segments + if segment is not None: + params['Segment'] = segment + if projection_expression is not None: + params['ProjectionExpression'] = projection_expression + if filter_expression is not None: + params['FilterExpression'] = filter_expression + if expression_attribute_names is not None: + params['ExpressionAttributeNames'] = expression_attribute_names + if expression_attribute_values is not None: + params['ExpressionAttributeValues'] = expression_attribute_values + return self.make_request(action='Scan', + body=json.dumps(params)) + + def update_item(self, table_name, key, attribute_updates=None, + expected=None, conditional_operator=None, + return_values=None, return_consumed_capacity=None, + return_item_collection_metrics=None, + update_expression=None, condition_expression=None, + expression_attribute_names=None, + expression_attribute_values=None): + """ + Edits an existing item's attributes, or adds a new item to the + table if it does not already exist. You can put, delete, or + add attribute values. You can also 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). + + You can also return the item's attribute values in the same + UpdateItem operation using the ReturnValues parameter. + + :type table_name: string + :param table_name: The name of the table containing the item to update. + + :type key: map + :param key: The primary key of the item to be updated. Each element + consists of an attribute name and a value for that attribute. + For the primary key, you must provide all of the attributes. For + example, with a hash type primary key, you only need to specify the + hash attribute. For a hash-and-range type primary key, you must + specify both the hash attribute and the range attribute. + + :type attribute_updates: map + :param attribute_updates: + There is a newer parameter available. Use UpdateExpression instead. + Note that if you use AttributeUpdates and UpdateExpression at the + same time, DynamoDB will return a ValidationException exception. + + This parameter can be used for modifying top-level attributes; however, + it does not support individual list or map elements. + + The names of attributes to be modified, the action to perform on each, + and the new value for each. If you are updating an attribute that + is an index key attribute for any indexes on that table, the + attribute type must match the index key type defined in the + AttributesDefinition of the table description. You can use + UpdateItem to update any nonkey attributes. + + Attribute values cannot be null. String and Binary type attributes must + have lengths greater than zero. Set type attributes must not be + empty. Requests with empty values will be rejected with a + ValidationException exception. + + Each AttributeUpdates element consists of an attribute name to modify, + along with the following: + + + + Value - The new value, if applicable, for this attribute. + + Action - A value that specifies how to perform the update. This + action is only valid for an existing attribute whose data type is + Number or is a set; do not use `ADD` for other data types. If an + item with the specified primary key is found in the table, the + following values perform the following actions: + + + `PUT` - Adds the specified attribute to the item. If the attribute + already exists, it is replaced by the new value. + + `DELETE` - Removes the attribute and its value, if no value is + specified for `DELETE`. The data type of the specified value must + match the existing value's data type. If a set of values is + specified, then those values are subtracted from the old set. For + example, if the attribute value was the set `[a,b,c]` and the + `DELETE` action specifies `[a,c]`, then the final attribute value + is `[b]`. Specifying an empty set is an error. + + `ADD` - Adds the specified value to the item, if the attribute does + not already exist. If the attribute does exist, then the behavior + of `ADD` depends on the data type of the attribute: + + + If the existing attribute is a number, and if Value is also a number, + then Value is mathematically added to the existing attribute. If + Value is a negative number, then it is subtracted from the existing + attribute. If you use `ADD` to increment or decrement a number + value for an item that doesn't exist before the update, DynamoDB + uses 0 as the initial value. Similarly, if you use `ADD` for an + existing item to increment or decrement an attribute value that + doesn't exist before the update, DynamoDB uses `0` as the initial + value. For example, suppose that the item you want to update + doesn't have an attribute named itemcount , but you decide to `ADD` + the number `3` to this attribute anyway. DynamoDB will create the + itemcount attribute, set its initial value to `0`, and finally add + `3` to it. The result will be a new itemcount attribute, with a + value of `3`. + + If the existing data type is a set, and if Value is also a set, then + Value is appended to the existing set. For example, if the + attribute value is the set `[1,2]`, and the `ADD` action specified + `[3]`, then the final attribute value is `[1,2,3]`. An error occurs + if an `ADD` action is specified for a set attribute and the + attribute type specified does not match the existing set type. Both + sets must have the same primitive data type. For example, if the + existing data type is a set of strings, Value must also be a set of + strings. + + If no item with the specified key is found in the table, the following + values perform the following actions: + + + `PUT` - Causes DynamoDB to create a new item with the specified + primary key, and then adds the attribute. + + `DELETE` - Nothing happens, because attributes cannot be deleted from + a nonexistent item. The operation succeeds, but DynamoDB does not + create a new item. + + `ADD` - Causes DynamoDB to create an item with the supplied primary + key and number (or set of numbers) for the attribute value. The + only data types allowed are Number and Number Set. + + + + If you specify any attributes that are part of an index key, then the + data types for those attributes must match those of the schema in + the table's attribute definition. + + :type expected: map + :param expected: + There is a newer parameter available. Use ConditionExpression instead. + Note that if you use Expected and ConditionExpression at the same + time, DynamoDB will return a ValidationException exception. + + This parameter does not support lists or maps. + + A map of attribute/condition pairs. Expected provides a conditional + block for the UpdateItem operation. + + Each element of Expected consists of an attribute name, a comparison + operator, and one or more values. DynamoDB compares the attribute + with the value(s) you supplied, using the comparison operator. For + each Expected element, the result of the evaluation is either true + or false. + + If you specify more than one element in the Expected map, then by + default all of the conditions must evaluate to true. In other + words, the conditions are ANDed together. (You can use the + ConditionalOperator parameter to OR the conditions instead. If you + do this, then at least one of the conditions must evaluate to true, + rather than all of them.) + + If the Expected map evaluates to true, then the conditional operation + succeeds; otherwise, it fails. + + Expected contains the following: + + + + AttributeValueList - One or more values to evaluate against the + supplied attribute. The number of values in the list depends on the + ComparisonOperator being used. For type Number, value comparisons + are numeric. String value comparisons for greater than, equals, or + less than are based on ASCII character code values. For example, + `a` is greater than `A`, and `a` is greater than `B`. For a list of + code values, see + `http://en.wikipedia.org/wiki/ASCII#ASCII_printable_characters`_. + For type Binary, DynamoDB treats each byte of the binary data as + unsigned when it compares binary values, for example when + evaluating query expressions. + + ComparisonOperator - A comparator for evaluating attributes in the + AttributeValueList . When performing the comparison, DynamoDB uses + strongly consistent reads. The following comparison operators are + available: `EQ | NE | LE | LT | GE | GT | NOT_NULL | NULL | + CONTAINS | NOT_CONTAINS | BEGINS_WITH | IN | BETWEEN` The following + are descriptions of each comparison operator. + + + `EQ` : Equal. `EQ` is supported for all datatypes, including lists + and maps. AttributeValueList can contain only one AttributeValue + element of type String, Number, Binary, String Set, Number Set, or + Binary Set. If an item contains an AttributeValue element of a + different type than the one specified in the request, the value + does not match. For example, `{"S":"6"}` does not equal + `{"N":"6"}`. Also, `{"N":"6"}` does not equal `{"NS":["6", "2", + "1"]}`. > <li> + + `NE` : Not equal. `NE` is supported for all datatypes, including + lists and maps. AttributeValueList can contain only one + AttributeValue of type String, Number, Binary, String Set, Number + Set, or Binary Set. If an item contains an AttributeValue of a + different type than the one specified in the request, the value + does not match. For example, `{"S":"6"}` does not equal + `{"N":"6"}`. Also, `{"N":"6"}` does not equal `{"NS":["6", "2", + "1"]}`. > <li> + + `LE` : Less than or equal. AttributeValueList can contain only one + AttributeValue element of type String, Number, or Binary (not a set + type). If an item contains an AttributeValue element of a different + type than the one specified in the request, the value does not + match. For example, `{"S":"6"}` does not equal `{"N":"6"}`. Also, + `{"N":"6"}` does not compare to `{"NS":["6", "2", "1"]}`. > <li> + + `LT` : Less than. AttributeValueList can contain only one + AttributeValue of type String, Number, or Binary (not a set type). + If an item contains an AttributeValue element of a different type + than the one specified in the request, the value does not match. + For example, `{"S":"6"}` does not equal `{"N":"6"}`. Also, + `{"N":"6"}` does not compare to `{"NS":["6", "2", "1"]}`. > <li> + + `GE` : Greater than or equal. AttributeValueList can contain only one + AttributeValue element of type String, Number, or Binary (not a set + type). If an item contains an AttributeValue element of a different + type than the one specified in the request, the value does not + match. For example, `{"S":"6"}` does not equal `{"N":"6"}`. Also, + `{"N":"6"}` does not compare to `{"NS":["6", "2", "1"]}`. > <li> + + `GT` : Greater than. AttributeValueList can contain only one + AttributeValue element of type String, Number, or Binary (not a set + type). If an item contains an AttributeValue element of a different + type than the one specified in the request, the value does not + match. For example, `{"S":"6"}` does not equal `{"N":"6"}`. Also, + `{"N":"6"}` does not compare to `{"NS":["6", "2", "1"]}`. > <li> + + `NOT_NULL` : The attribute exists. `NOT_NULL` is supported for all + datatypes, including lists and maps. This operator tests for the + existence of an attribute, not its data type. If the data type of + attribute " `a`" is null, and you evaluate it using `NOT_NULL`, the + result is a Boolean true . This result is because the attribute " + `a`" exists; its data type is not relevant to the `NOT_NULL` + comparison operator. + + `NULL` : The attribute does not exist. `NULL` is supported for all + datatypes, including lists and maps. This operator tests for the + nonexistence of an attribute, not its data type. If the data type + of attribute " `a`" is null, and you evaluate it using `NULL`, the + result is a Boolean false . This is because the attribute " `a`" + exists; its data type is not relevant to the `NULL` comparison + operator. + + `CONTAINS` : Checks for a subsequence, or value in a set. + AttributeValueList can contain only one AttributeValue element of + type String, Number, or Binary (not a set type). If the target + attribute of the comparison is of type String, then the operator + checks for a substring match. If the target attribute of the + comparison is of type Binary, then the operator looks for a + subsequence of the target that matches the input. If the target + attribute of the comparison is a set (" `SS`", " `NS`", or " + `BS`"), then the operator evaluates to true if it finds an exact + match with any member of the set. CONTAINS is supported for lists: + When evaluating " `a CONTAINS b`", " `a`" can be a list; however, " + `b`" cannot be a set, a map, or a list. + + `NOT_CONTAINS` : Checks for absence of a subsequence, or absence of a + value in a set. AttributeValueList can contain only one + AttributeValue element of type String, Number, or Binary (not a set + type). If the target attribute of the comparison is a String, then + the operator checks for the absence of a substring match. If the + target attribute of the comparison is Binary, then the operator + checks for the absence of a subsequence of the target that matches + the input. If the target attribute of the comparison is a set (" + `SS`", " `NS`", or " `BS`"), then the operator evaluates to true if + it does not find an exact match with any member of the set. + NOT_CONTAINS is supported for lists: When evaluating " `a NOT + CONTAINS b`", " `a`" can be a list; however, " `b`" cannot be a + set, a map, or a list. + + `BEGINS_WITH` : Checks for a prefix. AttributeValueList can contain + only one AttributeValue of type String or Binary (not a Number or a + set type). The target attribute of the comparison must be of type + String or Binary (not a Number or a set type). > <li> + + `IN` : Checks for matching elements within two sets. + AttributeValueList can contain one or more AttributeValue elements + of type String, Number, or Binary (not a set type). These + attributes are compared against an existing set type attribute of + an item. If any elements of the input set are present in the item + attribute, the expression evaluates to true. + + `BETWEEN` : Greater than or equal to the first value, and less than + or equal to the second value. AttributeValueList must contain two + AttributeValue elements of the same type, either String, Number, or + Binary (not a set type). A target attribute matches if the target + value is greater than, or equal to, the first element and less + than, or equal to, the second element. If an item contains an + AttributeValue element of a different type than the one specified + in the request, the value does not match. For example, `{"S":"6"}` + does not compare to `{"N":"6"}`. Also, `{"N":"6"}` does not compare + to `{"NS":["6", "2", "1"]}` + + + + For usage examples of AttributeValueList and ComparisonOperator , see + `Legacy Conditional Parameters`_ in the Amazon DynamoDB Developer + Guide . + + For backward compatibility with previous DynamoDB releases, the + following parameters can be used instead of AttributeValueList and + ComparisonOperator : + + + + Value - A value for DynamoDB to compare with an attribute. + + Exists - A Boolean value that causes DynamoDB to evaluate the value + before attempting the conditional operation: + + + If Exists is `True`, DynamoDB will check to see if that attribute + value already exists in the table. If it is found, then the + condition evaluates to true; otherwise the condition evaluate to + false. + + If Exists is `False`, DynamoDB assumes that the attribute value does + not exist in the table. If in fact the value does not exist, then + the assumption is valid and the condition evaluates to true. If the + value is found, despite the assumption that it does not exist, the + condition evaluates to false. + Note that the default value for Exists is `True`. + + + The Value and Exists parameters are incompatible with + AttributeValueList and ComparisonOperator . Note that if you use + both sets of parameters at once, DynamoDB will return a + ValidationException exception. + + :type conditional_operator: string + :param conditional_operator: + There is a newer parameter available. Use ConditionExpression instead. + Note that if you use ConditionalOperator and ConditionExpression at + the same time, DynamoDB will return a ValidationException + exception. + + This parameter does not support lists or maps. + + A logical operator to apply to the conditions in the Expected map: + + + + `AND` - If all of the conditions evaluate to true, then the entire + map evaluates to true. + + `OR` - If at least one of the conditions evaluate to true, then the + entire map evaluates to true. + + + If you omit ConditionalOperator , then `AND` is the default. + + The operation will succeed only if the entire map evaluates to true. + + :type return_values: string + :param return_values: + Use ReturnValues if you want to get the item attributes as they + appeared either before or after they were updated. For UpdateItem , + the valid values are: + + + + `NONE` - If ReturnValues is not specified, or if its value is `NONE`, + then nothing is returned. (This setting is the default for + ReturnValues .) + + `ALL_OLD` - If UpdateItem overwrote an attribute name-value pair, + then the content of the old item is returned. + + `UPDATED_OLD` - The old versions of only the updated attributes are + returned. + + `ALL_NEW` - All of the attributes of the new version of the item are + returned. + + `UPDATED_NEW` - The new versions of only the updated attributes are + returned. + + :type return_consumed_capacity: string + :param return_consumed_capacity: A value that if set to `TOTAL`, the + response includes ConsumedCapacity data for tables and indexes. If + set to `INDEXES`, the response includes ConsumedCapacity for + indexes. If set to `NONE` (the default), ConsumedCapacity is not + included in the response. + + :type return_item_collection_metrics: string + :param return_item_collection_metrics: A value that if set to `SIZE`, + the response includes statistics about item collections, if any, + that were modified during the operation are returned in the + response. If set to `NONE` (the default), no statistics are + returned. + + :type update_expression: string + :param update_expression: An expression that defines one or more + attributes to be updated, the action to be performed on them, and + new value(s) for them. + The following action values are available for UpdateExpression . + + + + `SET` - Adds one or more attributes and values to an item. If any of + these attribute already exist, they are replaced by the new values. + You can also use `SET` to add or subtract from an attribute that is + of type Number. `SET` supports the following functions: + + + `if_not_exists (path, operand)` - if the item does not contain an + attribute at the specified path, then `if_not_exists` evaluates to + operand; otherwise, it evaluates to path. You can use this function + to avoid overwriting an attribute that may already be present in + the item. + + `list_append (operand, operand)` - evaluates to a list with a new + element added to it. You can append the new element to the start or + the end of the list by reversing the order of the operands. + These function names are case-sensitive. + + `REMOVE` - Removes one or more attributes from an item. + + `ADD` - Adds the specified value to the item, if the attribute does + not already exist. If the attribute does exist, then the behavior + of `ADD` depends on the data type of the attribute: + + + If the existing attribute is a number, and if Value is also a number, + then Value is mathematically added to the existing attribute. If + Value is a negative number, then it is subtracted from the existing + attribute. If you use `ADD` to increment or decrement a number + value for an item that doesn't exist before the update, DynamoDB + uses `0` as the initial value. Similarly, if you use `ADD` for an + existing item to increment or decrement an attribute value that + doesn't exist before the update, DynamoDB uses `0` as the initial + value. For example, suppose that the item you want to update + doesn't have an attribute named itemcount , but you decide to `ADD` + the number `3` to this attribute anyway. DynamoDB will create the + itemcount attribute, set its initial value to `0`, and finally add + `3` to it. The result will be a new itemcount attribute in the + item, with a value of `3`. + + If the existing data type is a set and if Value is also a set, then + Value is added to the existing set. For example, if the attribute + value is the set `[1,2]`, and the `ADD` action specified `[3]`, + then the final attribute value is `[1,2,3]`. An error occurs if an + `ADD` action is specified for a set attribute and the attribute + type specified does not match the existing set type. Both sets must + have the same primitive data type. For example, if the existing + data type is a set of strings, the Value must also be a set of + strings. + The `ADD` action only supports Number and set data types. In addition, + `ADD` can only be used on top-level attributes, not nested + attributes. + + `DELETE` - Deletes an element from a set. If a set of values is + specified, then those values are subtracted from the old set. For + example, if the attribute value was the set `[a,b,c]` and the + `DELETE` action specifies `[a,c]`, then the final attribute value + is `[b]`. Specifying an empty set is an error. The `DELETE` action + only supports Number and set data types. In addition, `DELETE` can + only be used on top-level attributes, not nested attributes. + + + You can have many actions in a single expression, such as the + following: `SET a=:value1, b=:value2 DELETE :value3, :value4, + :value5` + + For more information on update expressions, go to `Modifying Items and + Attributes`_ in the Amazon DynamoDB Developer Guide . + + :type condition_expression: string + :param condition_expression: A condition that must be satisfied in + order for a conditional update to succeed. + An expression can contain any of the following: + + + + Boolean functions: `attribute_exists | attribute_not_exists | + contains | begins_with` These function names are case-sensitive. + + Comparison operators: ` = | <> | < | > | <= + | >= | BETWEEN | IN` + + Logical operators: `AND | OR | NOT` + + + For more information on condition expressions, go to `Specifying + Conditions`_ in the Amazon DynamoDB Developer Guide . + + :type expression_attribute_names: map + :param expression_attribute_names: One or more substitution tokens for + simplifying complex expressions. The following are some use cases + for using ExpressionAttributeNames : + + + To shorten an attribute name that is very long or unwieldy in an + expression. + + To create a placeholder for repeating occurrences of an attribute + name in an expression. + + To prevent special characters in an attribute name from being + misinterpreted in an expression. + + + Use the **#** character in an expression to dereference an attribute + name. For example, consider the following expression: + + + + `order.customerInfo.LastName = "Smith" OR order.customerInfo.LastName + = "Jones"` + + + Now suppose that you specified the following for + ExpressionAttributeNames : + + + + `{"#name":"order.customerInfo.LastName"}` + + + The expression can now be simplified as follows: + + + + `#name = "Smith" OR #name = "Jones"` + + + For more information on expression attribute names, go to `Accessing + Item Attributes`_ in the Amazon DynamoDB Developer Guide . + + :type expression_attribute_values: map + :param expression_attribute_values: One or more values that can be + substituted in an expression. + Use the **:** (colon) character in an expression to dereference an + attribute value. For example, suppose that you wanted to check + whether the value of the ProductStatus attribute was one of the + following: + + `Available | Backordered | Discontinued` + + You would first need to specify ExpressionAttributeValues as follows: + + `{ ":avail":{"S":"Available"}, ":back":{"S":"Backordered"}, + ":disc":{"S":"Discontinued"} }` + + You could then use these values in an expression, such as this: + + `ProductStatus IN (:avail, :back, :disc)` + + For more information on expression attribute values, go to `Specifying + Conditions`_ in the Amazon DynamoDB Developer Guide . + + """ + params = {'TableName': table_name, 'Key': key, } + if attribute_updates is not None: + params['AttributeUpdates'] = attribute_updates + if expected is not None: + params['Expected'] = expected + if conditional_operator is not None: + params['ConditionalOperator'] = conditional_operator + if return_values is not None: + params['ReturnValues'] = return_values + if return_consumed_capacity is not None: + params['ReturnConsumedCapacity'] = return_consumed_capacity + if return_item_collection_metrics is not None: + params['ReturnItemCollectionMetrics'] = return_item_collection_metrics + if update_expression is not None: + params['UpdateExpression'] = update_expression + if condition_expression is not None: + params['ConditionExpression'] = condition_expression + if expression_attribute_names is not None: + params['ExpressionAttributeNames'] = expression_attribute_names + if expression_attribute_values is not None: + params['ExpressionAttributeValues'] = expression_attribute_values + return self.make_request(action='UpdateItem', + body=json.dumps(params)) + + def update_table(self, table_name, provisioned_throughput=None, + global_secondary_index_updates=None, + attribute_definitions=None): + """ + Updates the provisioned throughput for the given table, or + manages the global secondary indexes on the table. + + You can increase or decrease the table's provisioned + throughput values within the maximums and minimums listed in + the `Limits`_ section in the Amazon DynamoDB Developer Guide . + + In addition, you can use UpdateTable to add, modify or delete + global secondary indexes on the table. For more information, + see `Managing Global Secondary Indexes`_ in the Amazon + DynamoDB Developer Guide . + + The table must be in the `ACTIVE` state for UpdateTable to + succeed. UpdateTable is an asynchronous operation; while + executing the operation, the table is in the `UPDATING` state. + While the table is in the `UPDATING` state, the table still + has the provisioned throughput from before the call. The + table's new provisioned throughput settings go into effect + when the table returns to the `ACTIVE` state; at that point, + the UpdateTable operation is complete. + + :type attribute_definitions: list + :param attribute_definitions: An array of attributes that describe the + key schema for the table and indexes. If you are adding a new + global secondary index to the table, AttributeDefinitions must + include the key element(s) of the new index. + + :type table_name: string + :param table_name: The name of the table to be updated. + + :type provisioned_throughput: dict + :param provisioned_throughput: Represents the provisioned throughput + settings for a specified table or index. The settings can be + modified using the UpdateTable operation. + For current minimum and maximum provisioned throughput values, see + `Limits`_ in the Amazon DynamoDB Developer Guide . + + :type global_secondary_index_updates: list + :param global_secondary_index_updates: + An array of one or more global secondary indexes for the table. For + each index in the array, you can specify one action: + + + + Create - add a new global secondary index to the table. + + Update - modify the provisioned throughput settings of an existing + global secondary index. + + Delete - remove a global secondary index from the table. + + """ + params = {'TableName': table_name, } + if attribute_definitions is not None: + params['AttributeDefinitions'] = attribute_definitions + if provisioned_throughput is not None: + params['ProvisionedThroughput'] = provisioned_throughput + if global_secondary_index_updates is not None: + params['GlobalSecondaryIndexUpdates'] = global_secondary_index_updates + return self.make_request(action='UpdateTable', + body=json.dumps(params)) + + def make_request(self, action, body): + headers = { + 'X-Amz-Target': '%s.%s' % (self.TargetPrefix, action), + 'Host': self.host, + 'Content-Type': 'application/x-amz-json-1.0', + 'Content-Length': str(len(body)), + } + http_request = self.build_base_http_request( + method='POST', path='/', auth_path='/', params={}, + headers=headers, data=body, host=self.host) + response = self._mexe(http_request, sender=None, + override_num_retries=self.NumberRetries, + retry_handler=self._retry_handler) + response_body = response.read().decode('utf-8') + boto.log.debug(response_body) + if response.status == 200: + if response_body: + return json.loads(response_body) + else: + json_body = json.loads(response_body) + fault_name = json_body.get('__type', None) + exception_class = self._faults.get(fault_name, self.ResponseError) + raise exception_class(response.status, response.reason, + body=json_body) + + def _retry_handler(self, response, i, next_sleep): + status = None + boto.log.debug("Saw HTTP status: %s" % response.status) + if response.status == 400: + response_body = response.read().decode('utf-8') + boto.log.debug(response_body) + data = json.loads(response_body) + if 'ProvisionedThroughputExceededException' in data.get('__type'): + self.throughput_exceeded_events += 1 + msg = "%s, retry attempt %s" % ( + 'ProvisionedThroughputExceededException', + i + ) + next_sleep = self._truncated_exponential_time(i) + i += 1 + status = (msg, i, next_sleep) + if i == self.NumberRetries: + # If this was our last retry attempt, raise + # a specific error saying that the throughput + # was exceeded. + raise exceptions.ProvisionedThroughputExceededException( + response.status, response.reason, data) + elif 'ConditionalCheckFailedException' in data.get('__type'): + raise exceptions.ConditionalCheckFailedException( + response.status, response.reason, data) + elif 'ValidationException' in data.get('__type'): + raise exceptions.ValidationException( + response.status, response.reason, data) + else: + raise self.ResponseError(response.status, response.reason, + data) + expected_crc32 = response.getheader('x-amz-crc32') + if self._validate_checksums and expected_crc32 is not None: + boto.log.debug('Validating crc32 checksum for body: %s', + response.read()) + actual_crc32 = crc32(response.read()) & 0xffffffff + expected_crc32 = int(expected_crc32) + if actual_crc32 != expected_crc32: + msg = ("The calculated checksum %s did not match the expected " + "checksum %s" % (actual_crc32, expected_crc32)) + status = (msg, i + 1, self._truncated_exponential_time(i)) + return status + + def _truncated_exponential_time(self, i): + if i == 0: + next_sleep = 0 + else: + next_sleep = min(0.05 * (2 ** i), + boto.config.get('Boto', 'max_retry_delay', 60)) + return next_sleep