awstin.dynamodb package¶
awstin.dynamodb module¶
-
class
awstin.dynamodb.
Attr
(attribute_name: Optional[str] = None)[source]¶ 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)[source]¶ Bases:
object
A client for use of DynamoDB via awstin.
Tables are accessed via data models. See documentation for details.
-
class
awstin.dynamodb.
DynamoModel
(**kwargs)[source]¶ 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
-
class
awstin.dynamodb.
Key
(attribute_name: Optional[str] = None)[source]¶ 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)[source]¶ 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)[source]¶ 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)[source]¶ Put an item in the table
- Parameters
item (DynamoModel) – The item to put in the table
-
query
(query_expression, filter_expression=None)[source]¶ 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)[source]¶ 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)[source]¶ 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.testing module¶
-
awstin.dynamodb.testing.
create_serverless_tables
(sls_filename: str, delay: float = 5.0, max_attempts: int = 10)[source]¶ 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)[source]¶ 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