
DynamoDB
********


boto.dynamodb
=============

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

boto.dynamodb.regions()

   Get all available regions for the Amazon DynamoDB service.

   Return type:
      list

   Returns:
      A list of "boto.regioninfo.RegionInfo"


boto.dynamodb.layer1
====================

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

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

   Variables:
      **throughput_exceeded_events** -- An integer variable that keeps
      a running total of the number of ThroughputExceeded responses
      this connection has received from Amazon DynamoDB.

   ConditionalCheckFailedError = 'ConditionalCheckFailedException'

      The error response returned when a conditional check fails

   DefaultRegionName = 'us-east-1'

      The default region name for DynamoDB API.

   NumberRetries = 10

      The number of times an error is retried.

   ResponseError

      alias of "DynamoDBResponseError"

   ServiceName = 'DynamoDB'

      The name of the Service

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

      The error response returned when session token has expired

   ThruputError = 'ProvisionedThroughputExceededException'

      The error response returned when provisioned throughput is
      exceeded

   ValidationError = 'ValidationException'

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

   Version = '20111205'

      DynamoDB API version.

   batch_get_item(request_items, object_hook=None)

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

      Parameters:
         **request_items** (*dict*) -- A Python version of the
         RequestItems data structure defined by DynamoDB.

   batch_write_item(request_items, object_hook=None)

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

      Parameters:
         **request_items** (*dict*) -- A Python version of the
         RequestItems data structure defined by DynamoDB.

   create_table(table_name, schema, provisioned_throughput)

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

      Parameters:
         * **table_name** (*str*) -- The name of the table to create.

         * **schema** (*dict*) -- A Python version of the KeySchema
           data structure as defined by DynamoDB

         * **provisioned_throughput** (*dict*) -- A Python version of
           the ProvisionedThroughput data structure defined by
           DynamoDB.

   delete_item(table_name, key, expected=None, return_values=None, object_hook=None)

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

      Parameters:
         * **table_name** (*str*) -- The name of the table containing
           the item.

         * **key** (*dict*) -- A Python version of the Key data
           structure defined by DynamoDB.

         * **expected** (*dict*) -- A Python version of the Expected
           data structure defined by DynamoDB.

         * **return_values** (*str*) -- Controls the return of
           attribute name-value pairs before then were changed.
           Possible values are: None or 'ALL_OLD'. If 'ALL_OLD' is
           specified and the item is overwritten, the content of the
           old item is returned.

   delete_table(table_name)

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

      Parameters:
         **table_name** (*str*) -- The name of the table to delete.

   describe_table(table_name)

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

      Parameters:
         **table_name** (*str*) -- The name of the table to describe.

   get_item(table_name, key, attributes_to_get=None, consistent_read=False, object_hook=None)

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

      Parameters:
         * **table_name** (*str*) -- The name of the table containing
           the item.

         * **key** (*dict*) -- A Python version of the Key data
           structure defined by DynamoDB.

         * **attributes_to_get** (*list*) -- A list of attribute
           names. If supplied, only the specified attribute names will
           be returned.  Otherwise, all attributes will be returned.

         * **consistent_read** (*bool*) -- If True, a consistent read
           request is issued.  Otherwise, an eventually consistent
           request is issued.

   list_tables(limit=None, start_table=None)

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

      Parameters:
         * **limit** (*int*) -- The maximum number of tables to
           return.

         * **start_table** (*str*) -- The name of the table that
           starts the list.  If you ran a previous list_tables and not
           all results were returned, the response dict would include
           a LastEvaluatedTableName attribute.  Use that value here to
           continue the listing.

   make_request(action, body='', object_hook=None)

      Raises :
         "DynamoDBExpiredTokenError" if the security token expires.

   put_item(table_name, item, expected=None, return_values=None, object_hook=None)

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

      Parameters:
         * **table_name** (*str*) -- The name of the table in which to
           put the item.

         * **item** (*dict*) -- A Python version of the Item data
           structure defined by DynamoDB.

         * **expected** (*dict*) -- A Python version of the Expected
           data structure defined by DynamoDB.

         * **return_values** (*str*) -- Controls the return of
           attribute name-value pairs before then were changed.
           Possible values are: None or 'ALL_OLD'. If 'ALL_OLD' is
           specified and the item is overwritten, the content of the
           old item is returned.

   query(table_name, hash_key_value, range_key_conditions=None, attributes_to_get=None, limit=None, consistent_read=False, scan_index_forward=True, exclusive_start_key=None, object_hook=None, count=False)

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

      Parameters:
         * **table_name** (*str*) -- The name of the table to query.

         * **key** -- A DynamoDB-style HashKeyValue.

         * **range_key_conditions** (*dict*) -- A Python version of
           the RangeKeyConditions data structure.

         * **attributes_to_get** (*list*) -- A list of attribute
           names. If supplied, only the specified attribute names will
           be returned.  Otherwise, all attributes will be returned.

         * **limit** (*int*) -- The maximum number of items to return.

         * **count** (*bool*) -- If True, Amazon DynamoDB returns a
           total number of items for the Query operation, even if the
           operation has no matching items for the assigned filter.

         * **consistent_read** (*bool*) -- If True, a consistent read
           request is issued.  Otherwise, an eventually consistent
           request is issued.

         * **scan_index_forward** (*bool*) -- Specified forward or
           backward traversal of the index.  Default is forward
           (True).

         * **exclusive_start_key** (*list or tuple*) -- Primary key of
           the item from which to continue an earlier query.  This
           would be provided as the LastEvaluatedKey in that query.

   scan(table_name, scan_filter=None, attributes_to_get=None, limit=None, exclusive_start_key=None, object_hook=None, count=False)

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

      Parameters:
         * **table_name** (*str*) -- The name of the table to scan.

         * **scan_filter** (*dict*) -- A Python version of the
           ScanFilter data structure.

         * **attributes_to_get** (*list*) -- A list of attribute
           names. If supplied, only the specified attribute names will
           be returned.  Otherwise, all attributes will be returned.

         * **limit** (*int*) -- The maximum number of items to
           evaluate.

         * **count** (*bool*) -- If True, Amazon DynamoDB returns a
           total number of items for the Scan operation, even if the
           operation has no matching items for the assigned filter.

         * **exclusive_start_key** (*list or tuple*) -- Primary key of
           the item from which to continue an earlier query.  This
           would be provided as the LastEvaluatedKey in that query.

   update_item(table_name, key, attribute_updates, expected=None, return_values=None, object_hook=None)

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

      Parameters:
         * **table_name** (*str*) -- The name of the table.

         * **key** (*dict*) -- A Python version of the Key data
           structure defined by DynamoDB which identifies the item to
           be updated.

         * **attribute_updates** (*dict*) -- A Python version of the
           AttributeUpdates data structure defined by DynamoDB.

         * **expected** (*dict*) -- A Python version of the Expected
           data structure defined by DynamoDB.

         * **return_values** (*str*) -- Controls the return of
           attribute name-value pairs before then were changed.
           Possible values are: None or 'ALL_OLD'. If 'ALL_OLD' is
           specified and the item is overwritten, the content of the
           old item is returned.

   update_table(table_name, provisioned_throughput)

      Updates the provisioned throughput for a given table.

      Parameters:
         * **table_name** (*str*) -- The name of the table to update.

         * **provisioned_throughput** (*dict*) -- A Python version of
           the ProvisionedThroughput data structure defined by
           DynamoDB.


boto.dynamodb.layer2
====================

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

   batch_get_item(batch_list)

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

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

   batch_write_item(batch_list)

      Performs multiple Puts and Deletes in one batch.

      Parameters:
         **batch_list** ("boto.dynamodb.batch.BatchWriteList") -- A
         BatchWriteList object which consists of a list of
         "boto.dynamoddb.batch.BatchWrite" objects. Each Batch object
         contains the information about one batch of objects that you
         wish to put or delete.

   build_key_from_values(schema, hash_key, range_key=None)

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

      Parameters:
         * **hash_key** (*int|float|str|unicode|Binary*) -- The hash
           key of the item you are looking for. The type of the hash
           key should match the type defined in the schema.

         * **range_key** (*int|float|str|unicode|Binary*) -- The range
           key of the item your are looking for. This should be
           supplied only if the schema requires a range key.  The type
           of the range key should match the type defined in the
           schema.

   create_schema(hash_key_name, hash_key_proto_value, range_key_name=None, range_key_proto_value=None)

      Create a Schema object used when creating a Table.

      Parameters:
         * **hash_key_name** (*str*) -- The name of the HashKey for
           the schema.

         * **hash_key_proto_value**
           (*int|long|float|str|unicode|Binary*) -- A sample or
           prototype of the type of value you want to use for the
           HashKey.  Alternatively, you can also just pass in the
           Python type (e.g. int, float, etc.).

         * **range_key_name** (*str*) -- The name of the RangeKey for
           the schema. This parameter is optional.

         * **range_key_proto_value**
           (*int|long|float|str|unicode|Binary*) -- A sample or
           prototype of the type of value you want to use for the
           RangeKey.  Alternatively, you can also pass in the Python
           type (e.g. int, float, etc.) This parameter is optional.

   create_table(name, schema, read_units, write_units)

      Create a new Amazon DynamoDB table.

      Parameters:
         * **name** (*str*) -- The name of the desired table.

         * **schema** ("boto.dynamodb.schema.Schema") -- The Schema
           object that defines the schema used by this table.

         * **read_units** (*int*) -- The value for ReadCapacityUnits.

         * **write_units** (*int*) -- The value for
           WriteCapacityUnits.

      Return type:
         "boto.dynamodb.table.Table"

      Returns:
         A Table object representing the new Amazon DynamoDB table.

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

      Delete the item from Amazon DynamoDB.

      Parameters:
         * **item** ("boto.dynamodb.item.Item") -- The Item to delete
           from Amazon DynamoDB.

         * **expected_value** (*dict*) -- A dictionary of name/value
           pairs that you expect. This dictionary should have
           name/value pairs where the name is the name of the
           attribute and the value is either the value you are
           expecting or False if you expect the attribute not to
           exist.

         * **return_values** (*str*) -- Controls the return of
           attribute name-value pairs before then were changed.
           Possible values are: None or 'ALL_OLD'. If 'ALL_OLD' is
           specified and the item is overwritten, the content of the
           old item is returned.

   delete_table(table)

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

      Parameters:
         **table** ("boto.dynamodb.table.Table") -- The Table object
         that is being deleted.

   describe_table(name)

      Retrieve information about an existing table.

      Parameters:
         **name** (*str*) -- The name of the desired table.

   dynamize_attribute_updates(pending_updates)

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

   dynamize_expected_value(expected_value)

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

   dynamize_item(item)

   dynamize_last_evaluated_key(last_evaluated_key)

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

   dynamize_range_key_condition(range_key_condition)

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

   dynamize_scan_filter(scan_filter)

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

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

      Retrieve an existing item from the table.

      Parameters:
         * **table** ("boto.dynamodb.table.Table") -- The Table object
           from which the item is retrieved.

         * **hash_key** (*int|long|float|str|unicode|Binary*) -- The
           HashKey of the requested item.  The type of the value must
           match the type defined in the schema for the table.

         * **range_key** (*int|long|float|str|unicode|Binary*) -- The
           optional RangeKey of the requested item. The type of the
           value must match the type defined in the schema for the
           table.

         * **attributes_to_get** (*list*) -- A list of attribute
           names. If supplied, only the specified attribute names will
           be returned.  Otherwise, all attributes will be returned.

         * **consistent_read** (*bool*) -- If True, a consistent read
           request is issued.  Otherwise, an eventually consistent
           request is issued.

         * **item_class** (*Class*) -- Allows you to override the
           class used to generate the items. This should be a subclass
           of "boto.dynamodb.item.Item"

   get_table(name)

      Retrieve the Table object for an existing table.

      Parameters:
         **name** (*str*) -- The name of the desired table.

      Return type:
         "boto.dynamodb.table.Table"

      Returns:
         A Table object representing the table.

   list_tables(limit=None)

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

      Parameters:
         **limit** (*int*) -- The maximum number of tables to return.

   lookup(name)

      Retrieve the Table object for an existing table.

      Parameters:
         **name** (*str*) -- The name of the desired table.

      Return type:
         "boto.dynamodb.table.Table"

      Returns:
         A Table object representing the table.

   new_batch_list()

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

   new_batch_write_list()

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

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

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

      Parameters:
         * **item** ("boto.dynamodb.item.Item") -- The Item to write
           to Amazon DynamoDB.

         * **expected_value** (*dict*) -- A dictionary of name/value
           pairs that you expect. This dictionary should have
           name/value pairs where the name is the name of the
           attribute and the value is either the value you are
           expecting or False if you expect the attribute not to
           exist.

         * **return_values** (*str*) -- Controls the return of
           attribute name-value pairs before then were changed.
           Possible values are: None or 'ALL_OLD'. If 'ALL_OLD' is
           specified and the item is overwritten, the content of the
           old item is returned.

   query(table, hash_key, range_key_condition=None, attributes_to_get=None, request_limit=None, max_results=None, consistent_read=False, scan_index_forward=True, exclusive_start_key=None, item_class=<class 'boto.dynamodb.item.Item'>, count=False)

      Perform a query on the table.

      Parameters:
         * **table** ("boto.dynamodb.table.Table") -- The Table object
           that is being queried.

         * **hash_key** (*int|long|float|str|unicode|Binary*) -- The
           HashKey of the requested item.  The type of the value must
           match the type defined in the schema for the table.

         * **range_key_condition**
           ("boto.dynamodb.condition.Condition") --

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

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

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

         * **attributes_to_get** (*list*) -- A list of attribute
           names. If supplied, only the specified attribute names will
           be returned.  Otherwise, all attributes will be returned.

         * **request_limit** (*int*) -- The maximum number of items to
           retrieve from Amazon DynamoDB on each request.  You may
           want to set a specific request_limit based on the
           provisioned throughput of your table.  The default behavior
           is to retrieve as many results as possible per request.

         * **max_results** (*int*) -- The maximum number of results
           that will be retrieved from Amazon DynamoDB in total.  For
           example, if you only wanted to see the first 100 results
           from the query, regardless of how many were actually
           available, you could set max_results to 100 and the
           generator returned from the query method will only yeild
           100 results max.

         * **consistent_read** (*bool*) -- If True, a consistent read
           request is issued.  Otherwise, an eventually consistent
           request is issued.

         * **scan_index_forward** (*bool*) -- Specified forward or
           backward traversal of the index.  Default is forward
           (True).

         * **count** (*bool*) -- If True, Amazon DynamoDB returns a
           total number of items for the Query operation, even if the
           operation has no matching items for the assigned filter.

         * **exclusive_start_key** (*list or tuple*) -- Primary key of
           the item from which to continue an earlier query.  This
           would be provided as the LastEvaluatedKey in that query.

         * **item_class** (*Class*) -- Allows you to override the
           class used to generate the items. This should be a subclass
           of "boto.dynamodb.item.Item"

      Return type:
         "boto.dynamodb.layer2.TableGenerator"

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

      Perform a scan of DynamoDB.

      Parameters:
         * **table** ("boto.dynamodb.table.Table") -- The Table object
           that is being scanned.

         * **scan_filter** (*A dict*) --

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

              * EQ - equal (1)

              * NE - not equal (1)

              * LE - less than or equal (1)

              * LT - less than (1)

              * GE - greater than or equal (1)

              * GT - greater than (1)

              * NOT_NULL - attribute exists (0, use None)

              * NULL - attribute does not exist (0, use None)

              * CONTAINS - substring or value in list (1)

              * NOT_CONTAINS - absence of substring or value in list
                (1)

              * BEGINS_WITH - substring prefix (1)

              * IN - exact match in list (N)

              * BETWEEN - >= first value, <= second value (2)

         * **attributes_to_get** (*list*) -- A list of attribute
           names. If supplied, only the specified attribute names will
           be returned.  Otherwise, all attributes will be returned.

         * **request_limit** (*int*) -- The maximum number of items to
           retrieve from Amazon DynamoDB on each request.  You may
           want to set a specific request_limit based on the
           provisioned throughput of your table.  The default behavior
           is to retrieve as many results as possible per request.

         * **max_results** (*int*) -- The maximum number of results
           that will be retrieved from Amazon DynamoDB in total.  For
           example, if you only wanted to see the first 100 results
           from the query, regardless of how many were actually
           available, you could set max_results to 100 and the
           generator returned from the query method will only yeild
           100 results max.

         * **count** (*bool*) -- If True, Amazon DynamoDB returns a
           total number of items for the Scan operation, even if the
           operation has no matching items for the assigned filter.

         * **exclusive_start_key** (*list or tuple*) -- Primary key of
           the item from which to continue an earlier query.  This
           would be provided as the LastEvaluatedKey in that query.

         * **item_class** (*Class*) -- Allows you to override the
           class used to generate the items. This should be a subclass
           of "boto.dynamodb.item.Item"

      Return type:
         "boto.dynamodb.layer2.TableGenerator"

   table_from_schema(name, schema)

      Create a Table object from a schema.

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

      Example usage:

         table = layer2.table_from_schema(
             'tablename',
             Schema.create(hash_key=('foo', 'N')))

      Parameters:
         * **name** (*str*) -- The name of the table.

         * **schema** ("boto.dynamodb.schema.Schema") -- The schema
           associated with the table.

      Return type:
         "boto.dynamodb.table.Table"

      Returns:
         A Table object representing the table.

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

      Commit pending item updates to Amazon DynamoDB.

      Parameters:
         * **item** ("boto.dynamodb.item.Item") -- The Item to update
           in Amazon DynamoDB.  It is expected that you would have
           called the add_attribute, put_attribute and/or
           delete_attribute methods on this Item prior to calling this
           method.  Those queued changes are what will be updated.

         * **expected_value** (*dict*) -- A dictionary of name/value
           pairs that you expect.  This dictionary should have
           name/value pairs where the name is the name of the
           attribute and the value is either the value you are
           expecting or False if you expect the attribute not to
           exist.

         * **return_values** (*str*) -- Controls the return of
           attribute name/value pairs before they were updated.
           Possible values are: None, 'ALL_OLD', 'UPDATED_OLD',
           'ALL_NEW' or 'UPDATED_NEW'. If 'ALL_OLD' is specified and
           the item is overwritten, the content of the old item is
           returned. If 'ALL_NEW' is specified, then all the
           attributes of the new version of the item are returned. If
           'UPDATED_NEW' is specified, the new versions of only the
           updated attributes are returned.

   update_throughput(table, read_units, write_units)

      Update the ProvisionedThroughput for the Amazon DynamoDB Table.

      Parameters:
         * **table** ("boto.dynamodb.table.Table") -- The Table object
           whose throughput is being updated.

         * **read_units** (*int*) -- The new value for
           ReadCapacityUnits.

         * **write_units** (*int*) -- The new value for
           WriteCapacityUnits.

   use_decimals()

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

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

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

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

   Variables:
      * **last_evaluated_key** -- A sequence representing the key(s)
        of the item last evaluated, or None if no additional results
        are available.

      * **remaining** -- The remaining quantity of results requested.

      * **table** -- The table to which the call was made.

   consumed_units

      Returns a float representing the ConsumedCapacityUnits
      accumulated.

   count

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

   next_response()

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

   response

      The current response to the call from DynamoDB.

   scanned_count

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


boto.dynamodb.table
===================

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

   An Amazon DynamoDB table.

   Variables:
      * **name** -- The name of the table.

      * **create_time** -- The date and time that the table was
        created.

      * **status** -- The current status of the table.  One of:
        'ACTIVE', 'UPDATING', 'DELETING'.

      * **schema** -- A "boto.dynamodb.schema.Schema" object
        representing the schema defined for the table.

      * **item_count** -- The number of items in the table.  This
        value is set only when the Table object is created or
        refreshed and may not reflect the actual count.

      * **size_bytes** -- Total size of the specified table, in bytes.
        Amazon DynamoDB updates this value approximately every six
        hours. Recent changes might not be reflected in this value.

      * **read_units** -- The ReadCapacityUnits of the tables
        Provisioned Throughput.

      * **write_units** -- The WriteCapacityUnits of the tables
        Provisioned Throughput.

      * **schema** -- The Schema object associated with the table.

   Parameters:
      * **layer2** ("boto.dynamodb.layer2.Layer2") -- A *Layer2* api
        object.

      * **response** (*dict*) -- The output of
        *boto.dynamodb.layer1.Layer1.describe_table*.

   batch_get_item(keys, attributes_to_get=None)

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

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

         * **attributes_to_get** (*list*) -- A list of attribute
           names. If supplied, only the specified attribute names will
           be returned.  Otherwise, all attributes will be returned.

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

      Return type:
         "boto.dynamodb.table.TableBatchGenerator"

   classmethod create_from_schema(layer2, name, schema)

      Create a Table object.

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

      Example usage:

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

      Parameters:
         * **layer2** ("boto.dynamodb.layer2.Layer2") -- A "Layer2"
           api object.

         * **name** (*str*) -- The name of the table.

         * **schema** ("boto.dynamodb.schema.Schema") -- The schema
           associated with the table.

      Return type:
         "boto.dynamodb.table.Table"

      Returns:
         A Table object representing the table.

   create_time

   delete()

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

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

      Retrieve an existing item from the table.

      Parameters:
         * **hash_key** (*int|long|float|str|unicode|Binary*) -- The
           HashKey of the requested item.  The type of the value must
           match the type defined in the schema for the table.

         * **range_key** (*int|long|float|str|unicode|Binary*) -- The
           optional RangeKey of the requested item. The type of the
           value must match the type defined in the schema for the
           table.

         * **attributes_to_get** (*list*) -- A list of attribute
           names. If supplied, only the specified attribute names will
           be returned.  Otherwise, all attributes will be returned.

         * **consistent_read** (*bool*) -- If True, a consistent read
           request is issued.  Otherwise, an eventually consistent
           request is issued.

         * **item_class** (*Class*) -- Allows you to override the
           class used to generate the items. This should be a subclass
           of "boto.dynamodb.item.Item"

   has_item(hash_key, range_key=None, consistent_read=False)

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

      Parameters:
         * **hash_key** (*int|long|float|str|unicode|Binary*) -- The
           HashKey of the requested item.  The type of the value must
           match the type defined in the schema for the table.

         * **range_key** (*int|long|float|str|unicode|Binary*) -- The
           optional RangeKey of the requested item. The type of the
           value must match the type defined in the schema for the
           table.

         * **consistent_read** (*bool*) -- If True, a consistent read
           request is issued.  Otherwise, an eventually consistent
           request is issued.

      Return type:
         bool

      Returns:
         "True" if the Item exists, "False" if not.

   item_count

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

      Retrieve an existing item from the table.

      Parameters:
         * **hash_key** (*int|long|float|str|unicode|Binary*) -- The
           HashKey of the requested item.  The type of the value must
           match the type defined in the schema for the table.

         * **range_key** (*int|long|float|str|unicode|Binary*) -- The
           optional RangeKey of the requested item. The type of the
           value must match the type defined in the schema for the
           table.

         * **attributes_to_get** (*list*) -- A list of attribute
           names. If supplied, only the specified attribute names will
           be returned.  Otherwise, all attributes will be returned.

         * **consistent_read** (*bool*) -- If True, a consistent read
           request is issued.  Otherwise, an eventually consistent
           request is issued.

         * **item_class** (*Class*) -- Allows you to override the
           class used to generate the items. This should be a subclass
           of "boto.dynamodb.item.Item"

   name

   new_item(hash_key=None, range_key=None, attrs=None, item_class=<class 'boto.dynamodb.item.Item'>)

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

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

         >>> my_item = my_table.new_item(hash_key='a', range_key=1,

            attrs={'key1': 'val1', 'key2': 'val2'})

         >>> my_item
         {u'bar': 1, u'foo': 'a', 'key1': 'val1', 'key2': 'val2'}

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

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

      The effect is the same.

      Parameters:
         * **hash_key** (*int|long|float|str|unicode|Binary*) -- The
           HashKey of the new item.  The type of the value must match
           the type defined in the schema for the table.

         * **range_key** (*int|long|float|str|unicode|Binary*) -- The
           optional RangeKey of the new item. The type of the value
           must match the type defined in the schema for the table.

         * **attrs** (*dict*) -- A dictionary of key value pairs used
           to populate the new item.

         * **item_class** (*Class*) -- Allows you to override the
           class used to generate the items. This should be a subclass
           of "boto.dynamodb.item.Item"

   query(hash_key, *args, **kw)

      Perform a query on the table.

      Parameters:
         * **hash_key** (*int|long|float|str|unicode|Binary*) -- The
           HashKey of the requested item.  The type of the value must
           match the type defined in the schema for the table.

         * **range_key_condition**
           ("boto.dynamodb.condition.Condition") --

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

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

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

         * **attributes_to_get** (*list*) -- A list of attribute
           names. If supplied, only the specified attribute names will
           be returned.  Otherwise, all attributes will be returned.

         * **request_limit** (*int*) -- The maximum number of items to
           retrieve from Amazon DynamoDB on each request.  You may
           want to set a specific request_limit based on the
           provisioned throughput of your table.  The default behavior
           is to retrieve as many results as possible per request.

         * **max_results** (*int*) -- The maximum number of results
           that will be retrieved from Amazon DynamoDB in total.  For
           example, if you only wanted to see the first 100 results
           from the query, regardless of how many were actually
           available, you could set max_results to 100 and the
           generator returned from the query method will only yeild
           100 results max.

         * **consistent_read** (*bool*) -- If True, a consistent read
           request is issued.  Otherwise, an eventually consistent
           request is issued.

         * **scan_index_forward** (*bool*) -- Specified forward or
           backward traversal of the index.  Default is forward
           (True).

         * **exclusive_start_key** (*list or tuple*) -- Primary key of
           the item from which to continue an earlier query.  This
           would be provided as the LastEvaluatedKey in that query.

         * **count** (*bool*) -- If True, Amazon DynamoDB returns a
           total number of items for the Query operation, even if the
           operation has no matching items for the assigned filter.

         * **item_class** (*Class*) -- Allows you to override the
           class used to generate the items. This should be a subclass
           of "boto.dynamodb.item.Item"

   read_units

   refresh(wait_for_active=False, retry_seconds=5)

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

      Parameters:
         * **wait_for_active** (*bool*) -- If True, this command will
           not return until the table status, as returned from Amazon
           DynamoDB, is 'ACTIVE'.

         * **retry_seconds** (*int*) -- If wait_for_active is True,
           this parameter controls the number of seconds of delay
           between calls to update_table in Amazon DynamoDB.  Default
           is 5 seconds.

   scan(*args, **kw)

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

      Parameters:
         * **scan_filter** (*A dict*) --

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

              * EQ - equal (1)

              * NE - not equal (1)

              * LE - less than or equal (1)

              * LT - less than (1)

              * GE - greater than or equal (1)

              * GT - greater than (1)

              * NOT_NULL - attribute exists (0, use None)

              * NULL - attribute does not exist (0, use None)

              * CONTAINS - substring or value in list (1)

              * NOT_CONTAINS - absence of substring or value in list
                (1)

              * BEGINS_WITH - substring prefix (1)

              * IN - exact match in list (N)

              * BETWEEN - >= first value, <= second value (2)

         * **attributes_to_get** (*list*) -- A list of attribute
           names. If supplied, only the specified attribute names will
           be returned.  Otherwise, all attributes will be returned.

         * **request_limit** (*int*) -- The maximum number of items to
           retrieve from Amazon DynamoDB on each request.  You may
           want to set a specific request_limit based on the
           provisioned throughput of your table.  The default behavior
           is to retrieve as many results as possible per request.

         * **max_results** (*int*) -- The maximum number of results
           that will be retrieved from Amazon DynamoDB in total.  For
           example, if you only wanted to see the first 100 results
           from the query, regardless of how many were actually
           available, you could set max_results to 100 and the
           generator returned from the query method will only yeild
           100 results max.

         * **count** (*bool*) -- If True, Amazon DynamoDB returns a
           total number of items for the Scan operation, even if the
           operation has no matching items for the assigned filter.

         * **exclusive_start_key** (*list or tuple*) -- Primary key of
           the item from which to continue an earlier query.  This
           would be provided as the LastEvaluatedKey in that query.

         * **item_class** (*Class*) -- Allows you to override the
           class used to generate the items. This should be a subclass
           of "boto.dynamodb.item.Item"

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

      Return type:
         "boto.dynamodb.layer2.TableGenerator"

   schema

   size_bytes

   status

   update_from_response(response)

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

   update_throughput(read_units, write_units)

      Update the ProvisionedThroughput for the Amazon DynamoDB Table.

      Parameters:
         * **read_units** (*int*) -- The new value for
           ReadCapacityUnits.

         * **write_units** (*int*) -- The new value for
           WriteCapacityUnits.

   write_units

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

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

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


boto.dynamodb.schema
====================

class class boto.dynamodb.schema.Schema(schema_dict)

   Represents a DynamoDB schema.

   Variables:
      * **hash_key_name** -- The name of the hash key of the schema.

      * **hash_key_type** -- The DynamoDB type specification for the
        hash key of the schema.

      * **range_key_name** -- The name of the range key of the schema
        or None if no range key is defined.

      * **range_key_type** -- The DynamoDB type specification for the
        range key of the schema or None if no range key is defined.

      * **dict** -- The underlying Python dictionary that needs to be
        passed to Layer1 methods.

   classmethod create(hash_key, range_key=None)

      Convenience method to create a schema object.

      Example usage:

         schema = Schema.create(hash_key=('foo', 'N'))
         schema2 = Schema.create(hash_key=('foo', 'N'),
                                 range_key=('bar', 'S'))

      Parameters:
         * **hash_key** (*tuple*) -- A tuple of (hash_key_name,
           hash_key_type)

         * **hash_key** -- A tuple of (range_key_name, range_key_type)

   dict

   hash_key_name

   hash_key_type

   range_key_name

   range_key_type


boto.dynamodb.item
==================

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

   An item in Amazon DynamoDB.

   Variables:
      * **hash_key** -- The HashKey of this item.

      * **range_key** -- The RangeKey of this item or None if no
        RangeKey is defined.

      * **hash_key_name** -- The name of the HashKey associated with
        this item.

      * **range_key_name** -- The name of the RangeKey associated with
        this item.

      * **table** -- The Table this item belongs to.

   add_attribute(attr_name, attr_value)

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

      Parameters:
         * **attr_name** (*str*) -- Name of the attribute you want to
           alter.

         * **attr_value** (*int|long|float|set*) -- Value which is to
           be added to the attribute.

   delete(expected_value=None, return_values=None)

      Delete the item from DynamoDB.

      Parameters:
         * **expected_value** (*dict*) -- A dictionary of name/value
           pairs that you expect.  This dictionary should have
           name/value pairs where the name is the name of the
           attribute and the value is either the value you are
           expecting or False if you expect the attribute not to
           exist.

         * **return_values** (*str*) -- Controls the return of
           attribute name-value pairs before then were changed.
           Possible values are: None or 'ALL_OLD'. If 'ALL_OLD' is
           specified and the item is overwritten, the content of the
           old item is returned.

   delete_attribute(attr_name, attr_value=None)

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

      Parameters:
         * **attr_name** (*str*) -- Name of the attribute you want to
           alter.

         * **attr_value** (*set*) -- A set of values to be removed
           from the attribute. This parameter is optional. If None,
           the whole attribute is removed from the item.

   hash_key

   hash_key_name

   put(expected_value=None, return_values=None)

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

      Parameters:
         * **expected_value** (*dict*) -- A dictionary of name/value
           pairs that you expect.  This dictionary should have
           name/value pairs where the name is the name of the
           attribute and the value is either the value you are
           expecting or False if you expect the attribute not to
           exist.

         * **return_values** (*str*) -- Controls the return of
           attribute name-value pairs before then were changed.
           Possible values are: None or 'ALL_OLD'. If 'ALL_OLD' is
           specified and the item is overwritten, the content of the
           old item is returned.

   put_attribute(attr_name, attr_value)

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

      Parameters:
         * **attr_name** (*str*) -- Name of the attribute you want to
           alter.

         * **attr_value** (*int|long|float|str|set*) -- New value of
           the attribute.

   range_key

   range_key_name

   save(expected_value=None, return_values=None)

      Commits pending updates to Amazon DynamoDB.

      Parameters:
         * **expected_value** (*dict*) -- A dictionary of name/value
           pairs that you expect.  This dictionary should have
           name/value pairs where the name is the name of the
           attribute and the value is either the value you are
           expecting or False if you expect the attribute not to
           exist.

         * **return_values** (*str*) -- Controls the return of
           attribute name/value pairs before they were updated.
           Possible values are: None, 'ALL_OLD', 'UPDATED_OLD',
           'ALL_NEW' or 'UPDATED_NEW'. If 'ALL_OLD' is specified and
           the item is overwritten, the content of the old item is
           returned. If 'ALL_NEW' is specified, then all the
           attributes of the new version of the item are returned. If
           'UPDATED_NEW' is specified, the new versions of only the
           updated attributes are returned.


boto.dynamodb.batch
===================

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

   Used to construct a BatchGet request.

   Variables:
      * **table** -- The Table object from which the item is
        retrieved.

      * **keys** -- A list of scalar or tuple values.  Each element in
        the list represents one Item to retrieve.  If the schema for
        the table has both a HashKey and a RangeKey, each element in
        the list should be a tuple consisting of (hash_key,
        range_key).  If the schema for the table contains only a
        HashKey, each element in the list should be a scalar value of
        the appropriate type for the table schema. NOTE: The maximum
        number of items that can be retrieved for a single operation
        is 100. Also, the number of items retrieved is constrained by
        a 1 MB size limit.

      * **attributes_to_get** -- A list of attribute names. If
        supplied, only the specified attribute names will be returned.
        Otherwise, all attributes will be returned.

      * **consistent_read** -- Specify whether or not to use a
        consistent read. Defaults to False.

   to_dict()

      Convert the Batch object into the format required for Layer1.

class class boto.dynamodb.batch.BatchList(layer2)

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

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

      Add a Batch to this BatchList.

      Parameters:
         * **table** ("boto.dynamodb.table.Table") -- The Table object
           in which the items are contained.

         * **keys** (*list*) -- A list of scalar or tuple values.
           Each element in the list represents one Item to retrieve.
           If the schema for the table has both a HashKey and a
           RangeKey, each element in the list should be a tuple
           consisting of (hash_key, range_key).  If the schema for the
           table contains only a HashKey, each element in the list
           should be a scalar value of the appropriate type for the
           table schema. NOTE: The maximum number of items that can be
           retrieved for a single operation is 100. Also, the number
           of items retrieved is constrained by a 1 MB size limit.

         * **attributes_to_get** (*list*) -- A list of attribute
           names. If supplied, only the specified attribute names will
           be returned.  Otherwise, all attributes will be returned.

   resubmit()

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

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

   submit()

   to_dict()

      Convert a BatchList object into format required for Layer1.

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

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

   Variables:
      * **table** -- The Table object from which the item is
        retrieved.

      * **puts** -- A list of "boto.dynamodb.item.Item" objects that
        you want to write to DynamoDB.

      * **deletes** -- A list of scalar or tuple values.  Each element
        in the list represents one Item to delete.  If the schema for
        the table has both a HashKey and a RangeKey, each element in
        the list should be a tuple consisting of (hash_key,
        range_key).  If the schema for the table contains only a
        HashKey, each element in the list should be a scalar value of
        the appropriate type for the table schema.

   to_dict()

      Convert the Batch object into the format required for Layer1.

class class boto.dynamodb.batch.BatchWriteList(layer2)

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

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

      Add a BatchWrite to this BatchWriteList.

      Parameters:
         * **table** ("boto.dynamodb.table.Table") -- The Table object
           in which the items are contained.

         * **puts** (list of "boto.dynamodb.item.Item" objects) -- A
           list of items that you want to write to DynamoDB.

         * **deletes** (*A list*) -- A list of scalar or tuple values.
           Each element in the list represents one Item to delete.  If
           the schema for the table has both a HashKey and a RangeKey,
           each element in the list should be a tuple consisting of
           (hash_key, range_key).  If the schema for the table
           contains only a HashKey, each element in the list should be
           a scalar value of the appropriate type for the table
           schema.

   submit()

   to_dict()

      Convert a BatchWriteList object into format required for Layer1.


boto.dynamodb.types
===================

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

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

   encode()

class class boto.dynamodb.types.Dynamizer

   Control serialization/deserialization of types.

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

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

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

   decode(attr)

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

   encode(attr)

      Encodes a python type to the format expected by DynamoDB.

class class boto.dynamodb.types.LossyFloatDynamizer

   Use float/int instead of Decimal for numeric types.

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

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

boto.dynamodb.types.convert_binary(n)

boto.dynamodb.types.convert_num(s)

boto.dynamodb.types.dynamize_value(val)

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

boto.dynamodb.types.float_to_decimal(f)

boto.dynamodb.types.get_dynamodb_type(val)

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

boto.dynamodb.types.is_binary(n)

boto.dynamodb.types.is_num(n)

boto.dynamodb.types.is_str(n)

boto.dynamodb.types.item_object_hook(dct)

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

boto.dynamodb.types.serialize_num(val)

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