awstin.dynamodb package

awstin.dynamodb module

class awstin.dynamodb.Attr(attribute_name: Optional[str] = None)

Bases: awstin.dynamodb.orm.BaseAttribute

Used to define and query non-key attributes on a dynamodb table data model

add(expression)

Add to an attribute (numerical add or addition to a set). Corresponds to ADD as part of the update expression in Table.update_item.

Parameters

expression (UpdateOperand) – Value to add

attribute_type(value)

Filter results by attribute type

Parameters

value (str) – Index for a DynamoDB attribute type (e.g. “N” for Number)

begins_with(value)

Filter results by a key or attribute beginning with a value

Parameters

value (str) – Starting string for returned results

between(low, high)

Filter results by range (inclusive)

Parameters

• low (Any) – Low end of the range

• high (Any) – High end of the range

contains(value)

Filter results by attributes that are containers and contain the target value

Parameters

values (Any) – Result must contain this item

delete(expression)

Delete part of a set attribute. Corresponds to DELETE as part of the update expression in Table.update_item.

Parameters

expression (UpdateOperand) – Value to delete

exists()

Filter results by existence of an attribute

if_not_exists(value)

Conditionally return a value if this attribute doesn’t exist on the model

in_(values)

Filter results by existence in a set

Parameters

values (list of Any) – Allowed values of returned results

not_exists()

Filter results by non-existence of an attribute

remove()

Remove an attribute. Corresponds to REMOVE as part of the update expression in Table.update_item.

set(expression)

Set an attribute to a new value. Corresponds to SET as part of the update expression in Table.update_item.

Parameters

expression (UpdateOperand) – New value, or an expression defining a new value

size()

Filter by size of a collection

class awstin.dynamodb.DynamoDB(timeout=5.0, max_retries=3)

Bases: object

A client for use of DynamoDB via awstin.

Tables are accessed via data models. See documentation for details.

list_tables()

Return a list of all table names in this DynamoDB instance.

Returns

Table names

Return type

list of str

class awstin.dynamodb.DynamoModel(**kwargs)

Bases: object

Class defining an ORM model for a DynamoDB table.

Subclasses must have a _table_name_ attribute. Attributes making up the data model should be Attr or Key instances.

Subclasses representing indexes should also have an _index_name_ attribute

classmethod deserialize(data)

Deserialize JSON into a DynamoModel subclass. Internally converts Decimal to float in the deserialization.

Parameters

data (dict of (str, Any)) – Serialized model

Returns

The deserialized data model

Return type

DynamoModel

serialize()

Serialize a DynamoModel subclass to JSON that can be inserted into DynamoDB. Internally converts float to Decimal.

Returns

The serialized JSON entry

Return type

dict of (str, Any)

class awstin.dynamodb.Key(attribute_name: Optional[str] = None)

Bases: awstin.dynamodb.orm.BaseAttribute

Used to define and query hash and sort key attributes on a dynamodb table data model

add(expression)

Add to an attribute (numerical add or addition to a set). Corresponds to ADD as part of the update expression in Table.update_item.

Parameters

expression (UpdateOperand) – Value to add

attribute_type(value)

Filter results by attribute type

Parameters

value (str) – Index for a DynamoDB attribute type (e.g. “N” for Number)

begins_with(value)

Filter results by a key or attribute beginning with a value

Parameters

value (str) – Starting string for returned results

between(low, high)

Filter results by range (inclusive)

Parameters

• low (Any) – Low end of the range

• high (Any) – High end of the range

contains(value)

Filter results by attributes that are containers and contain the target value

Parameters

values (Any) – Result must contain this item

delete(expression)

Delete part of a set attribute. Corresponds to DELETE as part of the update expression in Table.update_item.

Parameters

expression (UpdateOperand) – Value to delete

exists()

Filter results by existence of an attribute

if_not_exists(value)

Conditionally return a value if this attribute doesn’t exist on the model

in_(values)

Filter results by existence in a set

Parameters

values (list of Any) – Allowed values of returned results

not_exists()

Filter results by non-existence of an attribute

remove()

Remove an attribute. Corresponds to REMOVE as part of the update expression in Table.update_item.

set(expression)

Set an attribute to a new value. Corresponds to SET as part of the update expression in Table.update_item.

Parameters

expression (UpdateOperand) – New value, or an expression defining a new value

size()

Filter by size of a collection

class awstin.dynamodb.Table(dynamodb_client, data_model)

Bases: object

Interface to a DynamoDB table.

Items can be retrieved from the table by a shorthand depending on the primary key. If it’s only a partition key, items can be retrieved by the value of the partition key:

my_table["hashval"]

If it’s a partition and sort key, items can be retrived by a hashkey, sortkey tuple:

my_table["hashval", 123]

Items can also be retrieved in a dict-like way:

my_table[{"HashKeyName": "hashval", "SortKeyName": 123}]

delete_item(key, condition_expression=None)

Delete an item, given either a primary key as a dict, or given simply the value of the partition key if there is no sort key

Parameters

• key (Any) – Primary key of the entry to delete, specified as a hash key value, composite key tuple, or a dict

• condition_expression (Query, optional) – Optional condition expression for the delete, intended to make the operation idempotent

Returns

deleted – True if the delete, False if the condition was not satisfied

Return type

bool

Raises

botocore.exceptions.ClientError – If there’s an error in the request.

put_item(item)

Put an item in the table

Parameters

item (DynamoModel) – The item to put in the table

query(query_expression, filter_expression=None)

Yield items from the table matching some query expression and optional filter expression. Lazily paginates items internally.

Parameters

• query_expression (Query) – A Key query constructed with awstin’s query syntax

• filter_expression (Query) – An additional post-query filter expression constructed with awstin’s query syntax

Yields

item (DynamoModel) – An item in the table matching thw query

scan(scan_filter=None)

Yield items in from the table, optionally matching the given filter expression. Lazily paginates items internally.

Parameters

scan_filter (Query) – An optional query constructed with awstin’s query framework

Yields

item (DynamoModel) – An item in the table matching the filter

update_item(key, update_expression, condition_expression=None)

Update an item in the table given an awstin update expression.

Can optionally have a condition expression.

Parameters

• key (Any) – Primary key, specified as a hash key value, composite key tuple, or a dict

• update_expression (awstin.dynamodb.orm.UpdateOperator) – Update expression. See docs for construction.

• condition_expression (Query, optional) – Optional condition expression

Returns

Updated model, or None if the condition expression fails

Return type

DynamoModel or None

awstin.dynamodb.list_append(left, right)

Set a value to the combination of two lists in an update expression

awstin.dynamodb.testing module

awstin.dynamodb.testing.create_serverless_tables(sls_filename: str, delay: float = 5.0, max_attempts: int = 10)

Parse a serverless.yml file, deploying any tables found in the resources section.

This is currently very basic functionality that needs fleshing out. See k2bd/awstin#99

Parameters

• sls_filename (str) – Location of the serverless.yml file

• delay (float, optional) – Delay in seconds between checks if the table exists

• max_attempts (int, optional) – Max number of attempts to check if the table exists, after which the client gives up

awstin.dynamodb.testing.temporary_dynamodb_table(data_model, hashkey_name, hashkey_type='S', sortkey_name=None, sortkey_type='S', delay=5.0, max_attempts=10, extra_attributes=None, **extra_kwargs)

Context manager creating a temporary DynamoDB table for testing.

Ensures that the table is created and destroyed before entering and exiting the context.

Parameters

• data_model (DynamoModel) – Model to interface with this table

• hashkey_name (str) – Name of the hash key of the table

• hashkey_type (str, optional) – Type of the hash key (“S”, “N”, or “B”). Default “S”

• sortkey_name (str, optional) – Optional sort key for the temporary table

• sortkey_type (str, optional) – Type of the sort key if there is one (“S”, “N”, or “B”). Default “S”

• delay (float, optional) – Delay in seconds between checks if the table exists

• max_attempts (int, optional) – Max number of attempts to check if the table exists, after which the client gives up.

• extra_attributes (dict, optional) – Additional attribute definitions (boto3 specification)

• **extra_kwargs (dict) – Additional keyword arguments to pass to create_table