DynamoDBAccess

DynamoDB access

exception awsimple.dynamodb.DBItemNotFound(key)

Bases: AWSimpleException

class awsimple.dynamodb.DictKey(partition, sort)

Bases: tuple

Create new instance of DictKey(partition, sort)

partition

Alias for field number 0

sort

Alias for field number 1

class awsimple.dynamodb.DynamoDBAccess(table_name: str | None = None, **kwargs)

Bases: CacheAccess

AWS DynamoDB access

AWS DynamoDB access

Parameters:
  • table_name – DynamoDB table name

  • kwargs – kwargs

create_table(partition_key: str, sort_key: str | None = None, secondary_index: str | None = None, partition_key_type: ~typing.Type[str] | ~typing.Type[int] | ~typing.Type[bytes] = <class 'str'>, sort_key_type: ~typing.Type[str] | ~typing.Type[int] | ~typing.Type[bytes] = <class 'str'>, secondary_key_type: ~typing.Type[str] | ~typing.Type[int] | ~typing.Type[bytes] = <class 'str'>) → bool

Create a DynamoDB table.

Parameters:
  • partition_key – DynamoDB partition key (AKA hash key)

  • sort_key – DynamoDB sort key

  • secondary_index – secondary index key

  • partition_key_type – partition key type of str, int, bytes (str default)

  • sort_key_type – sort key type of str, int, bytes (str default)

  • secondary_key_type – secondary key type of str, int, bytes (str default)

Returns:

True if table created

delete_all_items() → int

Delete all the items in a table.

Caution: since DynamoDB doesn’t have a built-in mechanism to delete all items, items are deleted one at a time (we don’t do a table delete/create since it’s almost impossible to re-create all the indexes and potential references to other AWS resources). Therefore, executing this on large tables will take time and potentially cost money. You may want to do a delete/create you can programmatically recreate the table and its references.

(This is similar to a SQL “DELETE” with no WHERE clause.)

Returns:

number of items deleted

delete_item(partition_key: str | None = None, partition_value: str | int | None = None, sort_key: str | None = None, sort_value: str | int | None = None)

Delete table item

Parameters:
  • partition_key – item partition (aka hash) key

  • partition_value – item partition (aka hash) value

  • sort_key – item sort key (if exists)

  • sort_value – item sort value (if sort key exists)

delete_table() → bool

Deletes the current table. (This is more like the SQL “DROP TABLE”, not like a SQL “DELETE”, which only deletes rows. See DynamoDBAccess.delete_all_items() to delete all the items but leave the table itself.)

Returns:

True if actually deleted, False if it didn’t exist in the first place

dump_to_csv(file_path: Path)

Dump the table to a CSV file.

Parameters:

file_path – output CSV file path

get_cache_file_path() → Path
get_item(partition_key: str | None = None, partition_value: str | int | None = None, sort_key: str | None = None, sort_value: str | int | None = None) → dict

Get a DB item using the primary keys. Raise DBItemNotFound if item does not exist.

Parameters:
  • partition_key – partition key (optional - if not given or None AWSimple will provide it)

  • partition_value – partition value (str or int)

  • sort_key – sort key (optional in case sort not used, but if sort used and not given or None AWSimple will provide it)

  • sort_value – sort value (optional str or int)

Returns:

item dict or raises DBItemNotFound if item does not exist

get_item_count() → int

Get the number of items in the table.

Returns:

number of items in the table

get_primary_keys_dict() → Dict[KeyType, str]

Get the table’s primary keys (cached per instance). Raise TableNotFound if table does not exist.

Returns:

a dict with the primary key partition key and (optionally) sort key

get_primary_partition_key() → str
get_primary_sort_key() → str | None
get_secondary_indexes() → List[Dict[KeyType, str]]

Get the secondary indexes as a list of dicts with the key as the KeyType (cached per instance).

Returns:

list of dicts with secondary keys

get_table_names() → List[str]

get all DynamoDB tables

Returns:

a list of DynamoDB table names

put_item(item: dict)

Put (write) a DynamoDB table dict item.

Parameters:

item – item

put_item_if_not_exists(item: dict)

Put (write) a DynamoDB table dict item if it doesn’t already exist. If the item already exists, it is not modified and DynamoDBItemAlreadyExists is raised.

Parameters:

item – item

query(*args, **kwargs) → List[dict]

Query exact match using arg pairs or keyword args. Primary or secondary indexes allowed.

Parameters:

args – key, value pairs or keyword args

Returns:

a list of DB rows matching the query

query_begins_with(*args, **kwargs) → List[dict]

Query if begins with using arg pairs or keyword args. Primary or secondary indexes allowed.

Parameters:

args – key, value pairs or keyword args

Returns:

a list of DB rows matching the query

query_one(partition_key: str | None = None, partition_value=None, direction: QuerySelection = QuerySelection.highest, secondary_index_name: str | None = None) → dict | None

Query and return one or none items, optionally using the sort key to provide either the start or end of the ordered (sorted) set of items.

This is particularly useful when the table uses a sort key that orders the items, and you want one value that is at one of the ends of that sort. For example, if the sort key is an epoch timestamp (number) and direction is QueryDirection.highest, the most recent item is returned.

Parameters:
  • partition_key – partition key (optional - if not given AWSimple will use the primary partition key)

  • partition_value – partition value to match (exactly)

  • direction – the range extreme to retrieve (Range.lowest or Range.highest)

  • secondary_index_name – secondary index (if not using primary index)

Returns:

an item or None if not found

rows_to_dict(rows: list, sort_key: Callable | None = None) → dict

Get table rows as a sorted dict. dict key is the DynamoDB primary key, either as a single value (if only Partition Key used) or a 2 element named tuple (if Partition and Sort key used). Input row ends up being sorted.

Parameters:
  • rows – table rows (sorted after call)

  • sort_key – function to use to get the sort key from the row or omit to sort based on DynamoDB Primary Key

Returns:

dict of data with Primary Key used as key

scan_table() → list

returns entire lookup table

Returns:

table contents

scan_table_as_dict(sort_key: Callable | None = None) → dict

Scan table and return result as a dict with the key being the table’s Primary Key.

Parameters:
  • sort_key

  • sort_key – function to use to get the sort key from the row or omit to sort based on DynamoDB Primary Key

Returns:

dict of data with Primary Key used as key

scan_table_cached(invalidate_cache: bool = False) → list

Read data table(s) from AWS with caching. This is meant for static or slowly changing tables.

Parameters:

invalidate_cache – True to initially invalidate the cache (forcing a table scan)

Returns:

a list with the (possibly cached) table data

scan_table_cached_as_dict(invalidate_cache: bool = False, sort_key: Callable | None = None) → dict

Scan table and return result as a dict with the key being the table’s Primary Key.

Parameters:
  • invalidate_cache – True to initially invalidate the cache (forcing a table scan)

  • sort_key – function to use to get the sort key from the row or omit to sort based on DynamoDB Primary Key

Returns:

dict of data with Primary Key used as key

table_exists() → bool

Test if table exists

Returns:

True if table exists

upsert_item(partition_key: str | None = None, partition_value: str | int | None = None, sort_key: str | None = None, sort_value: str | int | None = None, item: dict | None = None)

Upsert (update or insert) table item

Parameters:
  • partition_key – item partition (aka hash) key

  • partition_value – item partition (aka hash) value

  • sort_key – item sort key (if exists)

  • sort_value – item sort value (if sort key exists)

  • item – item data

exception awsimple.dynamodb.DynamoDBTableNotFound(table_name: str)

Bases: AWSimpleException

DynamoDB Table Not Found exception (doesn’t require access to a boto3 client instance).

class awsimple.dynamodb.KeyType(*values)

Bases: Enum

partition = 'HASH'
sort = 'RANGE'
class awsimple.dynamodb.QuerySelection(*values)

Bases: Enum

highest = 1
lowest = 0
awsimple.dynamodb.convert_serializable_special_cases(o)

Convert an object to a type that is fairly generally serializable (e.g. json serializable). This only handles the cases that need converting. The json module handles all the rest. For JSON, with json.dump or json.dumps with argument default=convert_serializable. Example: json.dumps(my_animal, indent=4, default=convert_serializable)

Parameters:

o – object to be converted to a type that is serializable

Returns:

a serializable representation

awsimple.dynamodb.dict_to_dynamodb(input_value: Any, convert_images: bool = True, raise_exception: bool = True) → Any

makes a dictionary follow boto3 item standards

Parameters:
  • input_value – input dictionary

  • convert_images – set to False to skip over images (they can be too large)

  • raise_exception – set to False to not raise exceptions on issues

Returns:

converted version of the original dictionary

awsimple.dynamodb.dynamodb_to_dict(item) → dict

Convert a DynamoDB item to a serializable dict

Parameters:

item – DynamoDB item

Returns:

serializable dict

awsimple.dynamodb.dynamodb_to_json(item, indent=None) → str

Convert a DynamoDB item to JSON

Parameters:
  • item – DynamoDB item

  • indent – JSON indent

Returns:

JSON encoded string

awsimple.dynamodb.get_accommodated_clock_skew() → float