DynamoDBAccess¶
DynamoDB access
- exception awsimple.dynamodb.DBItemNotFound(key)¶
Bases:
AWSimpleException
- class awsimple.dynamodb.DictKey(partition, sort)¶
Bases:
tupleCreate 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:
CacheAccessAWS 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:
AWSimpleExceptionDynamoDB Table Not Found exception (doesn’t require access to a boto3 client instance).
- 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¶