Maps and Lists (Collections)¶
Map¶
-
class
cerami.datatype.
Map
(map_guesser=None, parse_guesser=None, default=None, column_name='')¶ A class to represent generic Map datatypes
A Map is used to store nested data within a record. It is essentially a dict where each key/value is stored in the database. Since the values can be anything, a MapGuesser and ParseGuesser are used to determine the datatype of these nested attributes. These guessers are passed to the constructor, and can be customized to return specific datatypes if you know the structure of the nested objects.
-
__init__
(map_guesser=None, parse_guesser=None, default=None, column_name='')¶ constructor for Map
- Parameters
map_guesser – an object inheriting from DefaultMapGuesser Defaults to the DefaultMapGuesser
parse_guesser – an object inheriting from DefaultParseGuesser Defaults to the DefaultParseGuesser.
default – a default value for the column. It can be a value or function
column_name – a string defining the name of the column on the table
-
between
(greater_than, less_than)¶ Build a BetweenExpression
BetweenExpression can be used with the filter() on the model or as a KeyConditionExpression on the sort key of a query
- Parameters
greater_than – a value that the query is greater than or equal to
less_than – a value that the query is less than or equal to
- Returns
A BetweenExpression
For example:
Person.scan.filter(Person.age.between(10, 20))
-
build
(val)¶ build the column value based on the val passed in
building is called automatically by the DynamoDataAttribute when the model is initialized. It will use the default value when present if the val passed in is None
- Parameters
val – A value that will be used to build the attribute on the instance
- Returns
The passed in val or the default when the default is set
-
in_
(*values)¶ Build an InExpression
InExpressions can only be used with filter() on the model, it cannot be part of a KeyConditionExpression. The will filter for the table for values that match exactly any of the values passed in as arguments
- Parameters
values – anything value to use to filter the table
- Returns
An InExpression
For example:
Person.scan.filter(Person.name.in_("Mom", "Dad"))
-
key
(datatype, key)¶ build a duplicate datatype with the column_name using a dot notiation
When forming a Request that involves a specific key from the Map, that item can be specified using the key() method.
- Parameters
datatype – a DynamoDataType instance representing the nested value
key – the name of the nested value
- Returns
A copy of the datatype with an new keyname
For example:
Parent.scan.filter(MyModel.child.key(String(), 'name') == 'Zac')
-
set_column_name
(val)¶ Update the column_name of this instance
- Parameters
value – a string for the new column name
-
List¶
-
class
cerami.datatype.
List
(map_guesser=None, parse_guesser=None, default=None, column_name='')¶ A class to represent generic List datatypes
A List is used to store a collection of values of a varying length. It is essentially an array where each item is the value stored in the database. Since values can be anything, a MapGueser and ParseGuesser are used to determine the datatype of the array’s items. These guessers are passed to the constructor, and can be customized to return specific datatypes if you know the structure of the array and each item.
-
__init__
(map_guesser=None, parse_guesser=None, default=None, column_name='')¶ constructor for List
- Parameters
map_guesser – An object inheriting from DefaultMapGuesser Defaults to the DefaultMapGuesser
parse_guesser – An object inheriting from DefaultParseGuesser Defaults to the DefaultParseGuesser.
default – a default value for the column. It can be a value or function
column_name – a string defining the name of the column on the table
-
append
(array)¶ Build an expression to add the array to the end of the existing column data
It can only be used in SET UpdateExpressions.
- Parameters
array – can be a list or single value to be appended. When it is a single value, it is automatically put inside its own array, before building the expression.
- Returns
A ListAppendExpression
For example:
Person.update \ .key(Person.email == "test@test.com") .set(Person.toys.append({"color": "red", "name": "car"})
-
between
(greater_than, less_than)¶ Build a BetweenExpression
BetweenExpression can be used with the filter() on the model or as a KeyConditionExpression on the sort key of a query
- Parameters
greater_than – a value that the query is greater than or equal to
less_than – a value that the query is less than or equal to
- Returns
A BetweenExpression
For example:
Person.scan.filter(Person.age.between(10, 20))
-
build
(val)¶ build the column value based on the val passed in
building is called automatically by the DynamoDataAttribute when the model is initialized. It will use the default value when present if the val passed in is None
- Parameters
val – A value that will be used to build the attribute on the instance
- Returns
The passed in val or the default when the default is set
-
in_
(*values)¶ Build an InExpression
InExpressions can only be used with filter() on the model, it cannot be part of a KeyConditionExpression. The will filter for the table for values that match exactly any of the values passed in as arguments
- Parameters
values – anything value to use to filter the table
- Returns
An InExpression
For example:
Person.scan.filter(Person.name.in_("Mom", "Dad"))
-
index
(idx, datatype)¶ build a duplicate datatype with the _index set to idx
When forming a Request that involves a specific item in the List, that item can be specified using this index() method.
- Parameters
idx – a number for the index of the desired item in the list
datatype – a DynamoDataType object representing the item indexed
- Returns
A copy of the datatype with _index set
- Raises
ValueError – An error when the datatype is not an instance of DynamoDataType
For example:
MyModel.scan.filter(MyModel.my_list.index(1, String()) == 'world')
-
set_column_name
(val)¶ Update the column_name of this instance
- Parameters
value – a string for the new column name
-
DefaultMapGuesser¶
-
class
cerami.datatype.
DefaultMapGuesser
¶ A class to guess what datatype to send to DynamoDB based the attribute value
A generic map or list type can have anything as its keys and values. There is no way to know what the Datatypes should be used for certainty because many of the datatypes defined (like Datetimes) all are converted to a String before saved in the table. This class will look at the values and decide which Datatype to use.
This class can be extended to handle your specific use cases. For example, if you know that the key “my_datetime” should always return a Datetime datatype, the guess() method can be overridden to handle specific cases.
-
guess
(key, value)¶ guess the datatype from the value
Guessing for mapping means we are trying to figure out the datatype in order to convert it into a dict usable by dynamodb. So this guesser will makes its guess based on value directly
- Parameters
key – the string of the column_name
value – the value of the column_name
- Returns
A DynamoDataType object
-
DefaultParseGuesser¶
-
class
cerami.datatype.
DefaultParseGuesser
¶ A class to decide what datatype to use toe
A generic map or list type can have anything as its keys and values. There is no way to know what the Datatypes should be used for certainty because many of the datatypes defined (like Datetimes) all are converted to a String before saved in the table. This class will look at the condition_type to determine what Datatype should be used
This class can be extended to handle your specific use cases. For example, if you know that the key “my_datetime” should always return a Datetime datatype, the guess() method can be overridden to handle specific cases.
-
guess
(key, value)¶ guess the datatype from the key within value
we are guessing on something like {‘M’: {‘test’: {‘S’: ‘hello’}}} where key is ‘test’ and value is {‘S’: ‘hello’} this will fetch the inner key (‘S’) and guess from this value
- Parameters
key – the column_name of the attribute
value – a dict whose key is the condition_type and value is the value of the column.
Returns: A DynamoDataType object
Example: guess(‘my_string’, {‘S’: ‘hello’})
-