add consumed capacity to the table resource

[ovidiutirsa-en]

Added ability to get consumed capacity for Dynamodb Table resource batch write operation similar to the one for the low-level client. Related to issue #1278.

Input parameter name and return values are handled very similar to the low-level client batch_write_item.

All values from ReturnConsumedCapacity are accepted for the new return_consumed_capacity parameter - 'INDEXES', 'TOTAL', 'NONE'. If the parameter is not provided, it will behave the same as 'NONE'.

The change is backwards compatible.

Assumption: The batch_write_item can operate on multiple tables at once and returns an array of ConsumedCapacity objects, one per table. When calling it on a Table resource, the operations will all be called for the same table. The consumed_capacity attribute of the batch writer will return an optional array of only one ConsumedCapacity object - the one for the Table resource.

Example:

import boto3


dynamo = boto3.resource('dynamodb')
table = dynamo.Table('MusicSample')
items = [
    {'Artist': 'artist1', 'SongTitle': 'song1', 'AlbumTitle': 'album1'},
    {'Artist': 'artist2', 'SongTitle': 'song2', 'AlbumTitle': 'album2'},
    {'Artist': 'artist3', 'SongTitle': 'song3', 'AlbumTitle': 'album3'},
]

# No capacity
with table.batch_writer() as batch:
    for item in items:
        batch.put_item(Item=item)
print('Return consumed capacity not set:\n', batch.consumed_capacity)

# Capacity set to 'NONE'
with table.batch_writer(return_consumed_capacity='NONE') as batch:
    for item in items:
        batch.put_item(Item=item)
print(
    'Return consumed capacity set to NONE:\n',
    batch.consumed_capacity
)

# Capacity set to 'TOTAL'
with table.batch_writer(return_consumed_capacity='TOTAL') as batch:
    for item in items:
        batch.put_item(Item=item)
print(
    'Return consumed capacity set to TOTAL:\n',
    batch.consumed_capacity
)

# Capacity set to 'INDEXES'
with table.batch_writer(return_consumed_capacity='INDEXES') as batch:
    for item in items:
        batch.put_item(Item=item)
print(
    'Return consumed capacity set to INDEXES:\n',
    batch.consumed_capacity
)

Output:

Return consumed capacity not set:
 None
Return consumed capacity set to NONE:
 None
Return consumed capacity set to TOTAL:
 [{'TableName': 'MusicSample', 'CapacityUnits': 3.0}]
Return consumed capacity set to INDEXES:
 [{'TableName': 'MusicSample', 'CapacityUnits': 3.0, 'Table': {'CapacityUnits': 3.0}}]