redismap / docs / converters.rst

Full commit


Converters allow Redismap to store data types besides str. Converters can be classes or instances, and do not have to inherit from any specific class.

Converter Interface

Converters are required to implement two methods:

This accepts a value of some type. It should return a str to be stored in the database.
This accepts a str from the database and should deserialize it back to whatever type it was originally.

Should either method fail, it should raise either TypeError or ValueError. to_redis should accept other types that can be coerced to the type being converted (for example, Float will accept int and Decimal in addition to float, but it will only return float from from_redis).

If the value is numeric or sequential in some form, it is also a good idea to provide to_zscore and from_zscore methods.

This also accepts a value of some type, but it should return a float to use as the score in a sorted set.
This should take the float value and deserialize it.

Note that there may be multiple converters for a type, that store the value in different ways. For example, DateTime and Timestamp both store datetime.datetime instances, but in keys, DateTime stores them as ISO 8601 datetimes and Timestamp stores them as UNIX timestamps. In this case, Redismap uses DateTime as the "default," but you should choose whichever one is appropriate for your application.

Builtin Converters

Converter Types

These are classes that, rather than being converters themselves, are used to build converters.