Translators¶
BaseDatatypeTranslator¶
-
class
cerami.datatype.translator.
BaseDatatypeTranslator
(datatype)¶ The base class for all Translators
Translators are responsible for translating between a model’s data and DynamoDB. All requests need to have the data formatted in a specific way, and all responses from DynamoDB are formatted similarly. A Translatoris responsible for converting to and from this DynamoDB structure.
-
datatype
¶ a DynamoDataType object the translator is used with
-
condition_type
¶ The condition_type of the datatype. It defines in DynamoDB the type of key used in the dictionary (“N”, “M”, “S”, …)
For example:
translator = BaseDatatypeTranslator(Person.email) translator.to_dynamodb("test@test.com") { "S": "test@test.com" } translator.to_cerami({"S": "test@test.com"}) "test@test.com"
-
__init__
(datatype)¶ constructor for the BaseDatatypeTranslator
- Parameters
datatype – a DynamoDataType object the translator is used with
-
format_for_cerami
(value)¶ Convert the value from DynamoDB into a format for the Model
- Parameters
value – anything that should be converted from a DynamoDB dict’s value value should never be None, reconstruct will not pass it here
- Returns
the value as is. All child classes should override this method to convert the value however necessary.
-
format_for_dynamodb
(value)¶ returns the value formatted for dynamodb
This method is called by
to_dynamodb()
to convert the value itself into a format that is expected for DynamoDB. For example, all Number datatypes need to be converted to strings in before being submitted.- Parameters
value – anything. It is the actual value that is submitted to DynamoDB
- Returns
the value as is. Any child class should override this method to convert the value as necessary.
-
to_cerami
(dynamodb_dict)¶ return the value from the DynamoDB dict for model instantiation
DynamoDB returns all attributes as a dict. Reconstructing reads this dict and parses the value. The return value can be used as the attribute on the Model. Reconstructing is only responsible for parsing the data as-is from DynamoDB. The process of assigning default values is done by the datatype itself.
- Parameters
dynaomdb_dict – A DynamoDB dictionary, whose key is the condition type of this instance and value is what needs to be parsed. The key can also be
"NULL"
which represents null values in DynamoDB- Returns
the parsed value from the dynamodb_dict. It will return
None
when the key of the dynamodb_dict is"NULL"
.
For example:
translator = BaseDatatypeTranslator(Person.email) translator.to_cerami({"S": "test@test.com"}) "test@test.com"
-
to_dynamodb
(value)¶ return the value and its condition_type in the DynamoDB dict format
Translating is done when converting the model into a form readable by DynamoDB. It involves two steps. First it must return a dict of the value. Second it must convert the value using the format_for_dynamodb() method
- Parameters
value – anything that should be converted into a DynamoDB formatted dict
- Returns
a dict in a format expected by DynamoDB. Its key is the condition_type of this instance and value the return value of
format_for_dynamodb()
. It will automatically return{"NULL": True}
when the value passed in isNone
For example:
translator = BaseDatatypeTranslator(Person.email) translator.to_dynamodb("test@test.com") { "S": "test@test.com" }
-
StringTranslator¶
-
class
cerami.datatype.translator.
StringTranslator
(datatype)¶ A Translator class for converting string fields into DynamoDB strings
For example:
translator = StringTranslator(String()) translator.to_dynamodb("hello world") {'S': "hello world"} translator.to_cerami({'S': "hello world"}) "hello world"
IntegerTranslator¶
-
class
cerami.datatype.translator.
IntegerTranslator
(datatype)¶ A Translator class for converting number fields into DynamoDB dictionaries
It rounds down to convert any number into an integer
For example:
translator = IntegerTranslator(Number()) translator.to_dynamodb(30.6) {'N': '30'} translator.to_cerami({'N': '30'}) 30
DecimalTranslator¶
-
class
cerami.datatype.translator.
DecimalTranslator
(datatype)¶ A Translator class for converting decimal number fields into DynaomDB dictionaries
For example:
translator = DecimalTranslator(Number()) translator.to_dynamodb(30) {'N': '30'} translator.to_dynamodb(30.69213) {'N': '30.69213'} translator.to_cerami({'N': '30'}) Decimal('30') translator.to_cerami({'N': '30.69213'}) Decimal('30.69213')
BooleanTranslator¶
-
class
cerami.datatype.translator.
BooleanTranslator
(datatype)¶ A Translator class for converting fields into DynamoDB booleans
For example:
translator = BooleanTranslator(Boolean()) translator.to_dynamodb(True) {'BOOL': True} translator.to_cerami({'BOOL': True}) True
ByteTranslator¶
-
class
cerami.datatype.translator.
ByteTranslator
(datatype)¶ A Translator class for byte encoding data
This translator is typically used with the ByteBuffer datatype. This class will automatically encode the value passed.
For example:
translator = ByteTranslator(DynamoDataType(condition_type="B")) # You can pass a string if you wanted to for example translator.to_dynamodb("hello world") {'B': b'hello world'} # But the string will not be returned when reconstructing translator.to_cerami({'B': b'hello world'}) b'helo world'
DatetimeTranslator¶
-
class
cerami.datatype.translator.
DatetimeTranslator
(datatype)¶ A Translator class for Datetimes
This translator is typically used with the
Datetime
datatype. This class will automatically convert the passed in datetime to UTC as is required by DynamoDBhttps://docs.aws.amazon.com/amazondynamodb/latest/developerguide/DynamoDBMapper.DataTypes.html
For example:
import datetime translator = DatetimeTranslator(String()) translator.to_dynamodb(datetime.datetime.now()) {'S': '2020-05-22T00:03:46.664845+00:00'} translator.to_cerami({'S': '2020-05-22T00:03:46.664845+00:00'}) datetime.datetime(2020, 5, 22, 0, 4, 33, 144061, tzinfo=tzutc())
DictTranslator¶
-
class
cerami.datatype.translator.
DictTranslator
(datatype, map_guesser, parse_guesser)¶ A Translator class for Dicts
This translator is typically used with the
Map
datatype. DynamoDB requires all nested values to also match their DynamoDB format when making requests. This class uses aMapGuesser
andParseGuesser
to decide how to resolve and reconstruct each key/value pair.-
datatype
¶ a DynamoDataType object the translator is used with
-
condition_type
¶ The condition_type of the datatype
-
map_guesser
¶ a MapGuesser object, typically associated with the datatype
-
parse_guesser
¶ A ParseGuesser object, typically associated with the datatype
For example:
translator = DictTranslator( DynamoDataType(condition_type="M"), DefaultMapGuesser(), DefaultParseGuesser()) translator.to_dynamodb({ "email": "test@test.com", "number": 123, }) { "M": { "email": { "S": "test@test.com" }, "number": { "N": "123" } } } translator.to_cerami({"M": {"email": {"S": "test@test.com"}}}) { "email": "test@test.com", }
-
ModelTranslator¶
-
class
cerami.datatype.translator.
ModelTranslator
(datatype)¶ A Translator class for converting Models to DynamoDB dictionaries
The ModelTranslator must be initialized with a ModelMap datatype. It depends on the model_cls attribute to know which columns and datatypes to use.
The benefit of using a ModelTranslator over a DictMapper is there is no guess work. Because all columns are defined, it automatically knows the datatypes to use.
For example:
child = Child(gender="female", age=2) translator = ModelTranslator(ModelMap(model_cls=Child)) translator.to_dynamodb(child) { "M": { "gender": { "S": "female" }, "age": { "N": "2" }, "name": { "NULL": True, }, } } translator.to_cerami({"M": {"name": {"S": "Baby"}}}) <Child object>
ListTranslator¶
-
class
cerami.datatype.translator.
ListTranslator
(datatype, map_guesser, parse_guesser)¶ A Translator class for Lists
This translator is typically used with the
List
datatype. DynamoDB requires all items of a List to also match the DynamoDB format when making requests. This class uses aMapGuesser
and aParseGuesser
to decide how to format each key/value pair-
datatype
¶ a DynamoDataType object the translator is used with
-
condition_type
¶ The condition_type of the datatype
-
map_guesser
¶ a MapGuesser object, typically associated with the datatype
-
parse_guesser
¶ A ParseGuesser object, typically associated with the datatype
For example:
translator = ListTranslator( DynamoDataType(condition_type="L"), DefaultMapGuesser(), DefaultParseGuesser()) translator.to_dynamodb(["test@test.com", 123]) { "L": [ { "S": "test@test.com" }, { "N": "123" } ] } translator.to_cerami({'L': [{'S': 'test@test.com'}, {'N': '123'}]}) ["test@test.com", 123]
-
UniformListTranslator¶
-
class
cerami.datatype.translator.
UniformListTranslator
(translator)¶ A Translator class for UniformLists
Unlike the ListTranslator, the UniformListTranslatordoes not need to guess which datatype each item in the array is.
For example:
translator = UniformListTranslator(StringTranslator(String())) translator.to_dynamodb(["hello", "world"]) { "L": [ { "S": "hello" }, { "S": "world" } ] } translator.to_cerami({"L": [{"S": "hello"}, {"S": "world"}]}) ["hello", "world"]
SetTranslator¶
-
class
cerami.datatype.translator.
SetTranslator
(translator)¶ A Translator class for converting a Set into a DynamoDB dictionary
For example:
translator = SetTranslator(StringTranslator(String())) translator.to_dynamodb(["hello", "world"]) {'SS': ['hello', 'world']} translator.to_cerami({'SS': ['hello', 'world']}) ['hello', 'world']