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 is None

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 DynamoDB

https://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 a MapGuesser and ParseGuesser 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 a MapGuesser and a ParseGuesser 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']