API¶
High Level API¶
DynamoDB Models for PynamoDB
-
class
pynamodb.models.
Model
(hash_key: Optional[Any] = None, range_key: Optional[Any] = None, _user_instantiated: bool = True, **attributes)¶ Defines a PynamoDB Model
This model is backed by a table in DynamoDB. You can create the table by with the
create_table
method.-
exception
DoesNotExist
(msg: Optional[str] = None, cause: Optional[Exception] = None)¶ Raised when an item queried does not exist
-
classmethod
batch_get
(items: Iterable[Union[Any, Iterable[Any]]], consistent_read: Optional[bool] = None, attributes_to_get: Optional[Sequence[str]] = None, settings: pynamodb.settings.OperationSettings = <pynamodb.settings.OperationSettings object>) → Iterator[_T]¶ BatchGetItem for this model
Parameters: items – Should be a list of hash keys to retrieve, or a list of tuples if range keys are used.
-
classmethod
batch_write
(auto_commit: bool = True, settings: pynamodb.settings.OperationSettings = <pynamodb.settings.OperationSettings object>) → pynamodb.models.BatchWrite[~_T][_T]¶ Returns a BatchWrite context manager for a batch operation.
Parameters: auto_commit – If true, the context manager will commit writes incrementally as items are written to as necessary to honor item count limits in the DynamoDB API (see BatchWrite). Regardless of the value passed here, changes automatically commit on context exit (whether successful or not).
-
classmethod
count
(hash_key: Optional[Any] = None, range_key_condition: Optional[pynamodb.expressions.condition.Condition] = None, filter_condition: Optional[pynamodb.expressions.condition.Condition] = None, consistent_read: bool = False, index_name: Optional[str] = None, limit: Optional[int] = None, rate_limit: Optional[float] = None, settings: pynamodb.settings.OperationSettings = <pynamodb.settings.OperationSettings object>) → int¶ Provides a filtered count
Parameters: - hash_key – The hash key to query. Can be None.
- range_key_condition – Condition for range key
- filter_condition – Condition used to restrict the query results
- consistent_read – If True, a consistent read is performed
- index_name – If set, then this index is used
- rate_limit – If set then consumed capacity will be limited to this amount per second
-
classmethod
create_table
(wait: bool = False, read_capacity_units: Optional[int] = None, write_capacity_units: Optional[int] = None, billing_mode: Optional[str] = None, ignore_update_ttl_errors: bool = False) → Any¶ Create the table for this model
Parameters: - wait – If set, then this call will block until the table is ready for use
- read_capacity_units – Sets the read capacity units for this table
- write_capacity_units – Sets the write capacity units for this table
- billing_mode – Sets the billing mode ‘PROVISIONED’ (default) or ‘PAY_PER_REQUEST’ for this table
-
delete
(condition: Optional[pynamodb.expressions.condition.Condition] = None, settings: pynamodb.settings.OperationSettings = <pynamodb.settings.OperationSettings object>, *, add_version_condition: bool = True) → Any¶ Deletes this object from DynamoDB.
Parameters: add_version_condition – For models which have a VersionAttribute
, specifies whether the item should only be deleted if its current version matches the expected one. Set to False for a ‘delete anyway’ strategy.Raises: pynamodb.exceptions.DeleteError – If the record can not be deleted
-
classmethod
delete_table
() → Any¶ Delete the table for this model
-
classmethod
describe_table
() → Any¶ Returns the result of a DescribeTable operation on this model’s table
-
deserialize
(attribute_values: Dict[str, Dict[str, Any]]) → None¶ Sets attributes sent back from DynamoDB on this object
-
classmethod
exists
() → bool¶ Returns True if this table exists, False otherwise
-
classmethod
from_raw_data
(data: Dict[str, Any]) → _T¶ Returns an instance of this class from the raw data
Parameters: data – A serialized DynamoDB object
-
classmethod
get
(hash_key: Any, range_key: Optional[Any] = None, consistent_read: bool = False, attributes_to_get: Optional[Sequence[str]] = None, settings: pynamodb.settings.OperationSettings = <pynamodb.settings.OperationSettings object>) → _T¶ Returns a single object using the provided keys
Parameters: - hash_key – The hash key of the desired item
- range_key – The range key of the desired item, only used when appropriate.
- consistent_read –
- attributes_to_get –
Raises: ModelInstance.DoesNotExist – if the object to be updated does not exist
-
classmethod
query
(hash_key: Any, range_key_condition: Optional[pynamodb.expressions.condition.Condition] = None, filter_condition: Optional[pynamodb.expressions.condition.Condition] = None, consistent_read: bool = False, index_name: Optional[str] = None, scan_index_forward: Optional[bool] = None, limit: Optional[int] = None, last_evaluated_key: Optional[Dict[str, Dict[str, Any]]] = None, attributes_to_get: Optional[Iterable[str]] = None, page_size: Optional[int] = None, rate_limit: Optional[float] = None, settings: pynamodb.settings.OperationSettings = <pynamodb.settings.OperationSettings object>) → pynamodb.pagination.ResultIterator[~_T][_T]¶ Provides a high level query API
Parameters: - hash_key – The hash key to query
- range_key_condition – Condition for range key
- filter_condition – Condition used to restrict the query results
- consistent_read – If True, a consistent read is performed
- index_name – If set, then this index is used
- limit – Used to limit the number of results returned
- scan_index_forward – If set, then used to specify the same parameter to the DynamoDB API. Controls descending or ascending results
- last_evaluated_key – If set, provides the starting point for query.
- attributes_to_get – If set, only returns these elements
- page_size – Page size of the query to DynamoDB
- rate_limit – If set then consumed capacity will be limited to this amount per second
-
refresh
(consistent_read: bool = False, settings: pynamodb.settings.OperationSettings = <pynamodb.settings.OperationSettings object>) → None¶ Retrieves this object’s data from dynamodb and syncs this local object
Parameters: - consistent_read – If True, then a consistent read is performed.
- settings – per-operation settings
Raises: ModelInstance.DoesNotExist – if the object to be updated does not exist
-
save
(condition: Optional[pynamodb.expressions.condition.Condition] = None, settings: pynamodb.settings.OperationSettings = <pynamodb.settings.OperationSettings object>, *, add_version_condition: bool = True) → Dict[str, Any]¶ Save this object to dynamodb
-
classmethod
scan
(filter_condition: Optional[pynamodb.expressions.condition.Condition] = None, segment: Optional[int] = None, total_segments: Optional[int] = None, limit: Optional[int] = None, last_evaluated_key: Optional[Dict[str, Dict[str, Any]]] = None, page_size: Optional[int] = None, consistent_read: Optional[bool] = None, index_name: Optional[str] = None, rate_limit: Optional[float] = None, attributes_to_get: Optional[Sequence[str]] = None, settings: pynamodb.settings.OperationSettings = <pynamodb.settings.OperationSettings object>) → pynamodb.pagination.ResultIterator[~_T][_T]¶ Iterates through all items in the table
Parameters: - filter_condition – Condition used to restrict the scan results
- segment – If set, then scans the segment
- total_segments – If set, then specifies total segments
- limit – Used to limit the number of results returned
- last_evaluated_key – If set, provides the starting point for scan.
- page_size – Page size of the scan to DynamoDB
- consistent_read – If True, a consistent read is performed
- index_name – If set, then this index is used
- rate_limit – If set then consumed capacity will be limited to this amount per second
- attributes_to_get – If set, specifies the properties to include in the projection expression
-
serialize
(null_check: bool = True) → Dict[str, Dict[str, Any]]¶ Serialize attribute values for DynamoDB
-
update
(actions: List[pynamodb.expressions.update.Action], condition: Optional[pynamodb.expressions.condition.Condition] = None, settings: pynamodb.settings.OperationSettings = <pynamodb.settings.OperationSettings object>, *, add_version_condition: bool = True) → Any¶ Updates an item using the UpdateItem operation.
Parameters: - actions – a list of Action updates to apply
- condition – an optional Condition on which to update
- settings – per-operation settings
- add_version_condition – For models which have a
VersionAttribute
, specifies whether only to update if the version matches the model that is currently loaded. Set to False for a ‘last write wins’ strategy. Regardless, the version will always be incremented to prevent “rollbacks” by concurrentsave()
calls.
Raises: - ModelInstance.DoesNotExist – if the object to be updated does not exist
- pynamodb.exceptions.UpdateError – if the condition is not met
-
classmethod
update_ttl
(ignore_update_ttl_errors: bool) → None¶ Attempt to update the TTL on the table. Certain implementations (eg: dynalite) do not support updating TTLs and will fail.
-
exception
PynamoDB attributes
-
class
pynamodb.attributes.
Attribute
(hash_key: bool = False, range_key: bool = False, null: Optional[bool] = None, default: Union[_T, Callable[[...], _T], None] = None, default_for_new: Union[Any, Callable[[...], _T], None] = None, attr_name: Optional[str] = None)¶ An attribute of a model
-
deserialize
(value: Any) → Any¶ Performs any needed deserialization on the value
-
serialize
(value: Any) → Any¶ This method should return a dynamodb compatible value
-
-
class
pynamodb.attributes.
BinaryAttribute
(hash_key: bool = False, range_key: bool = False, null: Optional[bool] = None, default: Union[_T, Callable[[...], _T], None] = None, default_for_new: Union[Any, Callable[[...], _T], None] = None, attr_name: Optional[str] = None)¶ A binary attribute
-
deserialize
(value)¶ Returns a decoded byte string from a base64 encoded value
-
serialize
(value)¶ Returns a base64 encoded binary string
-
-
class
pynamodb.attributes.
BinarySetAttribute
(hash_key: bool = False, range_key: bool = False, null: Optional[bool] = None, default: Union[_T, Callable[[...], _T], None] = None, default_for_new: Union[Any, Callable[[...], _T], None] = None, attr_name: Optional[str] = None)¶ A binary set
-
deserialize
(value)¶ Returns a set of decoded byte strings from base64 encoded values.
-
serialize
(value)¶ Returns a list of base64 encoded binary strings. Encodes empty sets as “None”.
-
-
class
pynamodb.attributes.
BooleanAttribute
(hash_key: bool = False, range_key: bool = False, null: Optional[bool] = None, default: Union[_T, Callable[[...], _T], None] = None, default_for_new: Union[Any, Callable[[...], _T], None] = None, attr_name: Optional[str] = None)¶ A class for boolean attributes
-
deserialize
(value)¶ Performs any needed deserialization on the value
-
serialize
(value)¶ This method should return a dynamodb compatible value
-
-
class
pynamodb.attributes.
DiscriminatorAttribute
(attr_name: Optional[str] = None)¶ -
deserialize
(value)¶ Returns the class corresponding to the given discriminator value.
-
serialize
(value)¶ Returns the discriminator value corresponding to the given class.
-
-
class
pynamodb.attributes.
DynamicMapAttribute
(**attributes)¶ A map attribute that supports declaring attributes (like an AttributeContainer) but will also store any other values that are set on it (like a raw MapAttribute).
>>> class MyDynamicMapAttribute(DynamicMapAttribute): >>> a_date_time = UTCDateTimeAttribute() # raw map attributes cannot serialize/deserialize datetime values >>> >>> dynamic_map = MyDynamicMapAttribute() >>> dynamic_map.a_date_time = datetime.utcnow() >>> dynamic_map.a_number = 5 >>> dynamic_map.serialize() # {'a_date_time': {'S': 'xxx'}, 'a_number': {'N': '5'}}
-
deserialize
(values)¶ Decode as a dict.
-
serialize
(values, *, null_check: bool = True)¶ This method should return a dynamodb compatible value
-
-
class
pynamodb.attributes.
JSONAttribute
(hash_key: bool = False, range_key: bool = False, null: Optional[bool] = None, default: Union[_T, Callable[[...], _T], None] = None, default_for_new: Union[Any, Callable[[...], _T], None] = None, attr_name: Optional[str] = None)¶ A JSON Attribute
Encodes JSON to unicode internally
-
deserialize
(value)¶ Deserializes JSON
-
serialize
(value) → Optional[str]¶ Serializes JSON to unicode
-
-
class
pynamodb.attributes.
ListAttribute
(hash_key: bool = False, range_key: bool = False, null: Optional[bool] = None, default: Union[Any, Callable[[...], Any], None] = None, attr_name: Optional[str] = None, of: Optional[Type[_T]] = None)¶ -
deserialize
(values)¶ Decode from list of AttributeValue types.
-
serialize
(values, *, null_check: bool = True)¶ Encode the given list of objects into a list of AttributeValue types.
-
-
class
pynamodb.attributes.
MapAttribute
(**attributes)¶ A Map Attribute
The MapAttribute class can be used to store a JSON document as “raw” name-value pairs, or it can be subclassed and the document fields represented as class attributes using Attribute instances.
To support the ability to subclass MapAttribute and use it as an AttributeContainer, instances of MapAttribute behave differently based both on where they are instantiated and on their type. Because of this complicated behavior, a bit of an introduction is warranted.
Models that contain a MapAttribute define its properties using a class attribute on the model. For example, below we define “MyModel” which contains a MapAttribute “my_map”:
- class MyModel(Model):
- my_map = MapAttribute(attr_name=”dynamo_name”, default={})
When instantiated in this manner (as a class attribute of an AttributeContainer class), the MapAttribute class acts as an instance of the Attribute class. The instance stores data about the attribute (in this example the dynamo name and default value), and acts as a data descriptor, storing any value bound to it on the attribute_values dictionary of the containing instance (in this case an instance of MyModel).
Unlike other Attribute types, the value that gets bound to the containing instance is a new instance of MapAttribute, not an instance of the primitive type. For example, a UnicodeAttribute stores strings in the attribute_values of the containing instance; a MapAttribute does not store a dict but instead stores a new instance of itself. This difference in behavior is necessary when subclassing MapAttribute in order to access the Attribute data descriptors that represent the document fields.
For example, below we redefine “MyModel” to use a subclass of MapAttribute as “my_map”:
- class MyMapAttribute(MapAttribute):
- my_internal_map = MapAttribute()
- class MyModel(Model):
- my_map = MyMapAttribute(attr_name=”dynamo_name”, default = {})
In order to set the value of my_internal_map on an instance of MyModel we need the bound value for “my_map” to be an instance of MapAttribute so that it acts as a data descriptor:
MyModel().my_map.my_internal_map = {‘foo’: ‘bar’}
That is the attribute access of “my_map” must return a MyMapAttribute instance and not a dict.
When an instance is used in this manner (bound to an instance of an AttributeContainer class), the MapAttribute class acts as an AttributeContainer class itself. The instance does not store data about the attribute, and does not act as a data descriptor. The instance stores name-value pairs in its internal attribute_values dictionary.
Thus while MapAttribute multiply inherits from Attribute and AttributeContainer, a MapAttribute instance does not behave as both an Attribute AND an AttributeContainer. Rather an instance of MapAttribute behaves EITHER as an Attribute OR as an AttributeContainer, depending on where it was instantiated.
So, how do we create this dichotomous behavior? All MapAttribute instances are initialized as AttributeContainers only. During construction of AttributeContainer classes (subclasses of MapAttribute and Model), any instances that are class attributes are transformed from AttributeContainers to Attributes (via the _make_attribute method call).
-
deserialize
(values)¶ Decode as a dict.
-
serialize
(values, *, null_check: bool = True)¶ This method should return a dynamodb compatible value
-
class
pynamodb.attributes.
NullAttribute
(hash_key: bool = False, range_key: bool = False, null: Optional[bool] = None, default: Union[_T, Callable[[...], _T], None] = None, default_for_new: Union[Any, Callable[[...], _T], None] = None, attr_name: Optional[str] = None)¶ -
deserialize
(value)¶ Performs any needed deserialization on the value
-
serialize
(value)¶ This method should return a dynamodb compatible value
-
-
class
pynamodb.attributes.
NumberAttribute
(hash_key: bool = False, range_key: bool = False, null: Optional[bool] = None, default: Union[_T, Callable[[...], _T], None] = None, default_for_new: Union[Any, Callable[[...], _T], None] = None, attr_name: Optional[str] = None)¶ A number attribute
-
deserialize
(value)¶ Decode numbers from JSON
-
serialize
(value)¶ Encode numbers as JSON
-
-
class
pynamodb.attributes.
NumberSetAttribute
(hash_key: bool = False, range_key: bool = False, null: Optional[bool] = None, default: Union[_T, Callable[[...], _T], None] = None, default_for_new: Union[Any, Callable[[...], _T], None] = None, attr_name: Optional[str] = None)¶ A number set attribute
-
deserialize
(value)¶ Returns a set from a JSON list of numbers.
-
serialize
(value)¶ Encodes a set of numbers as a JSON list. Encodes empty sets as “None”.
-
-
class
pynamodb.attributes.
TTLAttribute
(hash_key: bool = False, range_key: bool = False, null: Optional[bool] = None, default: Union[_T, Callable[[...], _T], None] = None, default_for_new: Union[Any, Callable[[...], _T], None] = None, attr_name: Optional[str] = None)¶ A time-to-live attribute that signifies when the item expires and can be automatically deleted. It can be assigned with a timezone-aware datetime value (for absolute expiry time) or a timedelta value (for expiry relative to the current time), but always reads as a UTC datetime value.
-
deserialize
(value)¶ Deserializes a timestamp (Unix time) as a UTC datetime.
-
serialize
(value)¶ Serializes a datetime as a timestamp (Unix time).
-
-
class
pynamodb.attributes.
UTCDateTimeAttribute
(hash_key: bool = False, range_key: bool = False, null: Optional[bool] = None, default: Union[_T, Callable[[...], _T], None] = None, default_for_new: Union[Any, Callable[[...], _T], None] = None, attr_name: Optional[str] = None)¶ An attribute for storing a UTC Datetime
-
deserialize
(value)¶ Takes a UTC datetime string and returns a datetime object
-
serialize
(value)¶ Takes a datetime object and returns a string
-
-
class
pynamodb.attributes.
UnicodeAttribute
(hash_key: bool = False, range_key: bool = False, null: Optional[bool] = None, default: Union[_T, Callable[[...], _T], None] = None, default_for_new: Union[Any, Callable[[...], _T], None] = None, attr_name: Optional[str] = None)¶ A unicode attribute
-
class
pynamodb.attributes.
UnicodeSetAttribute
(hash_key: bool = False, range_key: bool = False, null: Optional[bool] = None, default: Union[_T, Callable[[...], _T], None] = None, default_for_new: Union[Any, Callable[[...], _T], None] = None, attr_name: Optional[str] = None)¶ A unicode set
-
deserialize
(value)¶ Returns a set from a list of strings.
-
serialize
(value)¶ Returns a list of strings. Encodes empty sets as “None”.
-
-
class
pynamodb.attributes.
VersionAttribute
(hash_key: bool = False, range_key: bool = False, null: Optional[bool] = None, default: Union[_T, Callable[[...], _T], None] = None, default_for_new: Union[Any, Callable[[...], _T], None] = None, attr_name: Optional[str] = None)¶ A number attribute that implements optimistic locking.
-
deserialize
(value)¶ Decode numbers from JSON and cast to int.
-
serialize
(value)¶ Cast value to int then encode as JSON
-
PynamoDB Indexes
-
class
pynamodb.indexes.
AllProjection
¶ An ALL projection
-
class
pynamodb.indexes.
GlobalSecondaryIndex
¶ A global secondary index
-
class
pynamodb.indexes.
IncludeProjection
(non_attr_keys: Optional[List[str]] = None)¶ An INCLUDE projection
-
class
pynamodb.indexes.
Index
¶ Base class for secondary indexes
-
classmethod
count
(hash_key: Any, range_key_condition: Optional[pynamodb.expressions.condition.Condition] = None, filter_condition: Optional[pynamodb.expressions.condition.Condition] = None, consistent_read: bool = False, limit: Optional[int] = None, rate_limit: Optional[float] = None) → int¶ Count on an index
-
classmethod
query
(hash_key: Any, range_key_condition: Optional[pynamodb.expressions.condition.Condition] = None, filter_condition: Optional[pynamodb.expressions.condition.Condition] = None, consistent_read: Optional[bool] = False, scan_index_forward: Optional[bool] = None, limit: Optional[int] = None, last_evaluated_key: Optional[Dict[str, Dict[str, Any]]] = None, attributes_to_get: Optional[List[str]] = None, page_size: Optional[int] = None, rate_limit: Optional[float] = None) → pynamodb.pagination.ResultIterator[~_M][_M]¶ Queries an index
-
classmethod
scan
(filter_condition: Optional[pynamodb.expressions.condition.Condition] = None, segment: Optional[int] = None, total_segments: Optional[int] = None, limit: Optional[int] = None, last_evaluated_key: Optional[Dict[str, Dict[str, Any]]] = None, page_size: Optional[int] = None, consistent_read: Optional[bool] = None, rate_limit: Optional[float] = None, attributes_to_get: Optional[List[str]] = None) → pynamodb.pagination.ResultIterator[~_M][_M]¶ Scans an index
-
classmethod
-
class
pynamodb.indexes.
KeysOnlyProjection
¶ Keys only projection
-
class
pynamodb.indexes.
LocalSecondaryIndex
¶ A local secondary index
-
class
pynamodb.indexes.
Projection
¶ A class for presenting projections
-
class
pynamodb.transactions.
TransactGet
(*args, **kwargs)¶ -
get
(model_cls: Type[_M], hash_key: Any, range_key: Optional[Any] = None) → pynamodb.models._ModelFuture[~_M][_M]¶ Adds the operation arguments for an item to list of models to get returns a _ModelFuture object as a placeholder
Parameters: - model_cls –
- hash_key –
- range_key –
Returns:
-
-
class
pynamodb.transactions.
TransactWrite
(client_request_token: Optional[str] = None, return_item_collection_metrics: Optional[str] = None, **kwargs)¶
-
class
pynamodb.transactions.
Transaction
(connection: pynamodb.connection.base.Connection, return_consumed_capacity: Optional[str] = None)¶ Base class for a type of transaction operation
-
class
pynamodb.pagination.
PageIterator
(operation: Callable, args: Any, kwargs: Dict[str, Any], rate_limit: Optional[float] = None, settings: pynamodb.settings.OperationSettings = <pynamodb.settings.OperationSettings object>)¶ PageIterator handles Query and Scan result pagination.
http://docs.aws.amazon.com/amazondynamodb/latest/developerguide/Query.html#Query.Pagination http://docs.aws.amazon.com/amazondynamodb/latest/developerguide/Scan.html#Scan.Pagination
-
class
pynamodb.pagination.
RateLimiter
(rate_limit: float, time_module: Optional[Any] = None)¶ RateLimiter limits operations to a pre-set rate of units/seconds
- Example:
- Initialize a RateLimiter with the desired rate
- rate_limiter = RateLimiter(rate_limit)
- Now, every time before calling an operation, call acquire()
- rate_limiter.acquire()
- And after an operation, update the number of units consumed
- rate_limiter.consume(units)
-
acquire
() → None¶ Sleeps the appropriate amount of time to follow the rate limit restriction
Returns: None
-
consume
(units: int) → None¶ Records the amount of units consumed.
Parameters: units – Number of units consumed Returns: None
-
rate_limit
¶ A limit of units per seconds
-
class
pynamodb.pagination.
ResultIterator
(operation: Callable, args: Any, kwargs: Dict[str, Any], map_fn: Optional[Callable] = None, limit: Optional[int] = None, rate_limit: Optional[float] = None, settings: pynamodb.settings.OperationSettings = <pynamodb.settings.OperationSettings object>)¶ ResultIterator handles Query and Scan item pagination.
http://docs.aws.amazon.com/amazondynamodb/latest/developerguide/Query.html#Query.Pagination http://docs.aws.amazon.com/amazondynamodb/latest/developerguide/Scan.html#Scan.Pagination
Low Level API¶
PynamoDB lowest level connection
-
class
pynamodb.connection.
Connection
(region: Optional[str] = None, host: Optional[str] = None, read_timeout_seconds: Optional[float] = None, connect_timeout_seconds: Optional[float] = None, max_retry_attempts: Optional[int] = None, base_backoff_ms: Optional[int] = None, max_pool_connections: Optional[int] = None, extra_headers: Optional[Mapping[str, str]] = None, aws_access_key_id: Optional[str] = None, aws_secret_access_key: Optional[str] = None, aws_session_token: Optional[str] = None)¶ A higher level abstraction over botocore
-
add_meta_table
(meta_table: pynamodb.connection.base.MetaTable) → None¶ Adds information about the table’s schema.
-
batch_get_item
(table_name: str, keys: Sequence[str], consistent_read: Optional[bool] = None, return_consumed_capacity: Optional[str] = None, attributes_to_get: Optional[Any] = None, settings: pynamodb.settings.OperationSettings = <pynamodb.settings.OperationSettings object>) → Dict[KT, VT]¶ Performs the batch get item operation
-
batch_write_item
(table_name: str, put_items: Optional[Any] = None, delete_items: Optional[Any] = None, return_consumed_capacity: Optional[str] = None, return_item_collection_metrics: Optional[str] = None, settings: pynamodb.settings.OperationSettings = <pynamodb.settings.OperationSettings object>) → Dict[KT, VT]¶ Performs the batch_write_item operation
-
client
¶ Returns a botocore dynamodb client
-
create_table
(table_name: str, attribute_definitions: Optional[Any] = None, key_schema: Optional[Any] = None, read_capacity_units: Optional[int] = None, write_capacity_units: Optional[int] = None, global_secondary_indexes: Optional[Any] = None, local_secondary_indexes: Optional[Any] = None, stream_specification: Optional[Dict[KT, VT]] = None, billing_mode: str = 'PROVISIONED', tags: Optional[Dict[str, str]] = None) → Dict[KT, VT]¶ Performs the CreateTable operation
-
delete_item
(table_name: str, hash_key: str, range_key: Optional[str] = None, condition: Optional[pynamodb.expressions.condition.Condition] = None, return_values: Optional[str] = None, return_consumed_capacity: Optional[str] = None, return_item_collection_metrics: Optional[str] = None, settings: pynamodb.settings.OperationSettings = <pynamodb.settings.OperationSettings object>) → Dict[KT, VT]¶ Performs the DeleteItem operation and returns the result
-
delete_table
(table_name: str) → Dict[KT, VT]¶ Performs the DeleteTable operation
-
describe_table
(table_name: str) → Dict[KT, VT]¶ Performs the DescribeTable operation
-
dispatch
(operation_name: str, operation_kwargs: Dict[KT, VT], settings: pynamodb.settings.OperationSettings = <pynamodb.settings.OperationSettings object>) → Dict[KT, VT]¶ Dispatches operation_name with arguments operation_kwargs
Raises TableDoesNotExist if the specified table does not exist
-
get_attribute_type
(table_name: str, attribute_name: str, value: Optional[Any] = None) → str¶ Returns the proper attribute type for a given attribute name :param value: The attribute value an be supplied just in case the type is already included
-
get_consumed_capacity_map
(return_consumed_capacity: str) → Dict[KT, VT]¶ Builds the consumed capacity map that is common to several operations
-
get_exclusive_start_key_map
(table_name: str, exclusive_start_key: str) → Dict[KT, VT]¶ Builds the exclusive start key attribute map
-
get_identifier_map
(table_name: str, hash_key: str, range_key: Optional[str] = None, key: str = 'Key') → Dict[KT, VT]¶ Builds the identifier map that is common to several operations
-
get_item
(table_name: str, hash_key: str, range_key: Optional[str] = None, consistent_read: bool = False, attributes_to_get: Optional[Any] = None, settings: pynamodb.settings.OperationSettings = <pynamodb.settings.OperationSettings object>) → Dict[KT, VT]¶ Performs the GetItem operation and returns the result
-
get_item_attribute_map
(table_name: str, attributes: Any, item_key: str = 'Item', pythonic_key: bool = True) → Dict[KT, VT]¶ Builds up a dynamodb compatible AttributeValue map
-
get_item_collection_map
(return_item_collection_metrics: str) → Dict[KT, VT]¶ Builds the item collection map
-
get_meta_table
(table_name: str) → pynamodb.connection.base.MetaTable¶ Returns information about the table’s schema.
-
get_return_values_map
(return_values: str) → Dict[KT, VT]¶ Builds the return values map that is common to several operations
-
get_return_values_on_condition_failure_map
(return_values_on_condition_failure: str) → Dict[KT, VT]¶ Builds the return values map that is common to several operations
-
list_tables
(exclusive_start_table_name: Optional[str] = None, limit: Optional[int] = None) → Dict[KT, VT]¶ Performs the ListTables operation
-
parse_attribute
(attribute: Any, return_type: bool = False) → Any¶ Returns the attribute value, where the attribute can be a raw attribute value, or a dictionary containing the type: {‘S’: ‘String value’}
-
put_item
(table_name: str, hash_key: str, range_key: Optional[str] = None, attributes: Optional[Any] = None, condition: Optional[pynamodb.expressions.condition.Condition] = None, return_values: Optional[str] = None, return_consumed_capacity: Optional[str] = None, return_item_collection_metrics: Optional[str] = None, settings: pynamodb.settings.OperationSettings = <pynamodb.settings.OperationSettings object>) → Dict[KT, VT]¶ Performs the PutItem operation and returns the result
-
query
(table_name: str, hash_key: str, range_key_condition: Optional[pynamodb.expressions.condition.Condition] = None, filter_condition: Optional[Any] = None, attributes_to_get: Optional[Any] = None, consistent_read: bool = False, exclusive_start_key: Optional[Any] = None, index_name: Optional[str] = None, limit: Optional[int] = None, return_consumed_capacity: Optional[str] = None, scan_index_forward: Optional[bool] = None, select: Optional[str] = None, settings: pynamodb.settings.OperationSettings = <pynamodb.settings.OperationSettings object>) → Dict[KT, VT]¶ Performs the Query operation and returns the result
-
scan
(table_name: str, filter_condition: Optional[Any] = None, attributes_to_get: Optional[Any] = None, limit: Optional[int] = None, return_consumed_capacity: Optional[str] = None, exclusive_start_key: Optional[str] = None, segment: Optional[int] = None, total_segments: Optional[int] = None, consistent_read: Optional[bool] = None, index_name: Optional[str] = None, settings: pynamodb.settings.OperationSettings = <pynamodb.settings.OperationSettings object>) → Dict[KT, VT]¶ Performs the scan operation
-
session
¶ Returns a valid botocore session
-
transact_get_items
(get_items: Sequence[Dict[KT, VT]], return_consumed_capacity: Optional[str] = None, settings: pynamodb.settings.OperationSettings = <pynamodb.settings.OperationSettings object>) → Dict[KT, VT]¶ Performs the TransactGet operation and returns the result
-
transact_write_items
(condition_check_items: Sequence[Dict[KT, VT]], delete_items: Sequence[Dict[KT, VT]], put_items: Sequence[Dict[KT, VT]], update_items: Sequence[Dict[KT, VT]], client_request_token: Optional[str] = None, return_consumed_capacity: Optional[str] = None, return_item_collection_metrics: Optional[str] = None, settings: pynamodb.settings.OperationSettings = <pynamodb.settings.OperationSettings object>) → Dict[KT, VT]¶ Performs the TransactWrite operation and returns the result
-
update_item
(table_name: str, hash_key: str, range_key: Optional[str] = None, actions: Optional[Sequence[pynamodb.expressions.update.Action]] = None, condition: Optional[pynamodb.expressions.condition.Condition] = None, return_consumed_capacity: Optional[str] = None, return_item_collection_metrics: Optional[str] = None, return_values: Optional[str] = None, settings: pynamodb.settings.OperationSettings = <pynamodb.settings.OperationSettings object>) → Dict[KT, VT]¶ Performs the UpdateItem operation
-
update_table
(table_name: str, read_capacity_units: Optional[int] = None, write_capacity_units: Optional[int] = None, global_secondary_index_updates: Optional[Any] = None) → Dict[KT, VT]¶ Performs the UpdateTable operation
-
update_time_to_live
(table_name: str, ttl_attribute_name: str) → Dict[KT, VT]¶ Performs the UpdateTimeToLive operation
-
-
class
pynamodb.connection.
TableConnection
(table_name: str, region: Optional[str] = None, host: Optional[str] = None, connect_timeout_seconds: Optional[float] = None, read_timeout_seconds: Optional[float] = None, max_retry_attempts: Optional[int] = None, base_backoff_ms: Optional[int] = None, max_pool_connections: Optional[int] = None, extra_headers: Optional[Mapping[str, str]] = None, aws_access_key_id: Optional[str] = None, aws_secret_access_key: Optional[str] = None, aws_session_token: Optional[str] = None, *, meta_table: Optional[pynamodb.connection.base.MetaTable] = None)¶ A higher level abstraction over botocore
-
batch_get_item
(keys: Sequence[str], consistent_read: Optional[bool] = None, return_consumed_capacity: Optional[str] = None, attributes_to_get: Optional[Any] = None, settings: pynamodb.settings.OperationSettings = <pynamodb.settings.OperationSettings object>) → Dict[KT, VT]¶ Performs the batch get item operation
-
batch_write_item
(put_items: Optional[Any] = None, delete_items: Optional[Any] = None, return_consumed_capacity: Optional[str] = None, return_item_collection_metrics: Optional[str] = None, settings: pynamodb.settings.OperationSettings = <pynamodb.settings.OperationSettings object>) → Dict[KT, VT]¶ Performs the batch_write_item operation
-
create_table
(attribute_definitions: Optional[Any] = None, key_schema: Optional[Any] = None, read_capacity_units: Optional[int] = None, write_capacity_units: Optional[int] = None, global_secondary_indexes: Optional[Any] = None, local_secondary_indexes: Optional[Any] = None, stream_specification: Optional[Dict[KT, VT]] = None, billing_mode: str = 'PROVISIONED', tags: Optional[Dict[str, str]] = None) → Dict[KT, VT]¶ Performs the CreateTable operation and returns the result
-
delete_item
(hash_key: str, range_key: Optional[str] = None, condition: Optional[pynamodb.expressions.condition.Condition] = None, return_values: Optional[str] = None, return_consumed_capacity: Optional[str] = None, return_item_collection_metrics: Optional[str] = None, settings: pynamodb.settings.OperationSettings = <pynamodb.settings.OperationSettings object>) → Dict[KT, VT]¶ Performs the DeleteItem operation and returns the result
-
delete_table
() → Dict[KT, VT]¶ Performs the DeleteTable operation and returns the result
-
describe_table
() → Dict[KT, VT]¶ Performs the DescribeTable operation and returns the result
-
get_item
(hash_key: str, range_key: Optional[str] = None, consistent_read: bool = False, attributes_to_get: Optional[Any] = None, settings: pynamodb.settings.OperationSettings = <pynamodb.settings.OperationSettings object>) → Dict[KT, VT]¶ Performs the GetItem operation and returns the result
-
get_meta_table
() → pynamodb.connection.base.MetaTable¶ Returns a MetaTable
-
put_item
(hash_key: str, range_key: Optional[str] = None, attributes: Optional[Any] = None, condition: Optional[pynamodb.expressions.condition.Condition] = None, return_values: Optional[str] = None, return_consumed_capacity: Optional[str] = None, return_item_collection_metrics: Optional[str] = None, settings: pynamodb.settings.OperationSettings = <pynamodb.settings.OperationSettings object>) → Dict[KT, VT]¶ Performs the PutItem operation and returns the result
-
query
(hash_key: str, range_key_condition: Optional[pynamodb.expressions.condition.Condition] = None, filter_condition: Optional[Any] = None, attributes_to_get: Optional[Any] = None, consistent_read: bool = False, exclusive_start_key: Optional[Any] = None, index_name: Optional[str] = None, limit: Optional[int] = None, return_consumed_capacity: Optional[str] = None, scan_index_forward: Optional[bool] = None, select: Optional[str] = None, settings: pynamodb.settings.OperationSettings = <pynamodb.settings.OperationSettings object>) → Dict[KT, VT]¶ Performs the Query operation and returns the result
-
scan
(filter_condition: Optional[Any] = None, attributes_to_get: Optional[Any] = None, limit: Optional[int] = None, return_consumed_capacity: Optional[str] = None, segment: Optional[int] = None, total_segments: Optional[int] = None, exclusive_start_key: Optional[str] = None, consistent_read: Optional[bool] = None, index_name: Optional[str] = None, settings: pynamodb.settings.OperationSettings = <pynamodb.settings.OperationSettings object>) → Dict[KT, VT]¶ Performs the scan operation
-
update_item
(hash_key: str, range_key: Optional[str] = None, actions: Optional[Sequence[pynamodb.expressions.update.Action]] = None, condition: Optional[pynamodb.expressions.condition.Condition] = None, return_consumed_capacity: Optional[str] = None, return_item_collection_metrics: Optional[str] = None, return_values: Optional[str] = None, settings: pynamodb.settings.OperationSettings = <pynamodb.settings.OperationSettings object>) → Dict[KT, VT]¶ Performs the UpdateItem operation
-
update_table
(read_capacity_units: Optional[int] = None, write_capacity_units: Optional[int] = None, global_secondary_index_updates: Optional[Any] = None) → Dict[KT, VT]¶ Performs the UpdateTable operation and returns the result
-
update_time_to_live
(ttl_attr_name: str) → Dict[KT, VT]¶ Performs the UpdateTimeToLive operation and returns the result
-
Exceptions¶
-
exception
pynamodb.exceptions.
PynamoDBConnectionError
(msg: Optional[str] = None, cause: Optional[Exception] = None)¶ A base class for connection errors
-
exception
pynamodb.exceptions.
DeleteError
(msg: Optional[str] = None, cause: Optional[Exception] = None)¶ Raised when an error occurs deleting an item
-
exception
pynamodb.exceptions.
QueryError
(msg: Optional[str] = None, cause: Optional[Exception] = None)¶ Raised when queries fail
-
exception
pynamodb.exceptions.
ScanError
(msg: Optional[str] = None, cause: Optional[Exception] = None)¶ Raised when a scan operation fails
-
exception
pynamodb.exceptions.
PutError
(msg: Optional[str] = None, cause: Optional[Exception] = None)¶ Raised when an item fails to be created
-
exception
pynamodb.exceptions.
UpdateError
(msg: Optional[str] = None, cause: Optional[Exception] = None)¶ Raised when an item fails to be updated
-
exception
pynamodb.exceptions.
GetError
(msg: Optional[str] = None, cause: Optional[Exception] = None)¶ Raised when an item fails to be retrieved
-
exception
pynamodb.exceptions.
TableError
(msg: Optional[str] = None, cause: Optional[Exception] = None)¶ An error involving a dynamodb table operation
-
exception
pynamodb.exceptions.
TableDoesNotExist
(table_name: str)¶ Raised when an operation is attempted on a table that doesn’t exist
-
exception
pynamodb.exceptions.
DoesNotExist
(msg: Optional[str] = None, cause: Optional[Exception] = None)¶ Raised when an item queried does not exist
-
exception
pynamodb.exceptions.
TransactWriteError
(msg: Optional[str] = None, cause: Optional[Exception] = None)¶ Raised when a TransactWrite operation fails
-
exception
pynamodb.exceptions.
TransactGetError
(msg: Optional[str] = None, cause: Optional[Exception] = None)¶ Raised when a TransactGet operation fails
-
exception
pynamodb.exceptions.
InvalidStateError
(msg: Optional[str] = None, cause: Optional[Exception] = None)¶ Raises when the internal state of an operation context is invalid
-
exception
pynamodb.exceptions.
AttributeDeserializationError
(attr_name: str, attr_type: str)¶ Raised when attribute type is invalid
-
exception
pynamodb.exceptions.
AttributeNullError
(attr_name: str)¶
-
class
pynamodb.exceptions.
CancellationReason
(*, code: str, message: Optional[str])¶ A reason for a transaction cancellation.