Add support for custom serializers

See #48 for rationale

Author: msiemens

docs/extend.rst

@@ -1,6 +1,38 @@
 How to Extend TinyDB
 ====================
 
+Write a Serializer
+------------------
+
+TinyDB's default storage is fairly limited when it comes to supported data types.
+If you need more flexibility, you can implement a Serializer. This allows TinyDB
+to handle classes it otherwise couldn't serialize. Let's see how a Serializer
+for ``datetime`` objects could look like:
+
+.. code-block:: python
+
+    from datetime import datetime
+
+    class DateTimeSerializer(Serializer):
+        NAME = 'TinyDate'  # A unique name
+        OBJ_CLASS = datetime  # The class this serializer handles
+
+        def encode(self, obj):
+            return obj.strftime('%Y-%m-%dT%H:%M:%S')
+
+        def decode(self, s):
+            return datetime.strptime(s, '%Y-%m-%dT%H:%M:%S')
+
+We can use this Serializer like this:
+
+.. code-block:: python
+
+    >>> db = TinyDB('db.json')
+    >>> db.register_serializer(DateTimeSerializer())
+    >>> db.insert({'date': datetime(2000, 1, 1, 12, 0, 0)})
+    >>> db.all()
+    [{'date': datetime.datetime(2000, 1, 1, 12, 0)}]
+
 Write a custom Storage
 ----------------------
 

docs/usage.rst

@@ -427,8 +427,9 @@ What's next
 Congratulations, you've made through the user guide! Now go and build something
 awesome or dive deeper into TinyDB with these ressources:
 
-- Want to learn how to customize TinyDB and what extensions exist?
-  Check out :doc:`extend`.
+- Want to learn how to customize TinyDB (custom serializers, storages,
+  middlewares) and what extensions exist? Check out :doc:`extend` and
+  :doc:`extensions`.
 - Want to study the API in detail? Read :doc:`api`.
 - Interested in contributing to the TinyDB development guide? Go on to the
   :doc:`contribute`.

tinydb/database.py

@@ -43,6 +43,7 @@ def __init__(self, *args, **kwargs):
         storage = kwargs.pop('storage', JSONStorage)
         #: :type: Storage
         self._storage = storage(*args, **kwargs)
+        self._serializers = []
 
         self._table_cache = {}
         self._table = self.table('_default')
@@ -101,6 +102,19 @@ def purge_tables(self):
         self._write({})
         self._table_cache.clear()
 
+    def register_serializer(self, serializer):
+        """
+        Register a new Serializer.
+
+        When reading from/writing to the underlying storage, TinyDB
+        will run all objects through the list of registered serializers
+        allowing each one to handle objects it recognizes.
+
+        :param serializer: an instance of the serializer
+        :type serializer: tinydb.serialize.Serializer
+        """
+        self._serializers.append(serializer)
+
     def _read(self):
         """
         Reading access to the backend.
@@ -123,7 +137,22 @@ def _read_table(self, table):
         """
 
         try:
-            return self._read()[table]
+            data = self._read()[table]
+
+            # Run deserialization
+            for serializer in self._serializers:
+                tag = '{{{}}}:'.format(serializer.NAME)
+
+                for eid in data:
+                    for field in data[eid]:
+                        try:
+                            if data[eid][field].startswith(tag):
+                                encoded = data[eid][field][len(tag):]
+                                data[eid][field] = serializer.decode(encoded)
+                        except AttributeError:
+                            pass  # Not a string
+
+            return data
         except (KeyError, TypeError):
             return {}
 
@@ -152,8 +181,18 @@ def _write_table(self, values, table):
         data = self._read()
         data[table] = values
 
+        # Run serialization
+        for serializer in self._serializers:
+            for eid in data:
+                for field in data[eid]:
+                    if isinstance(data[eid][field], serializer.OBJ_CLASS):
+                        data[eid][field] = '{{{}}}:{}'.format(
+                            serializer.NAME,
+                            serializer.encode(data[eid][field])
+                        )
+
+        # Finally, store the data
         self._write(data)
-        return
 
     # Methods that are executed on the default table
     # Because magic methods are not handlet by __getattr__ we need to forward

tinydb/utils.py

@@ -103,3 +103,19 @@ def catch_warning(warning_cls):
         warnings.filterwarnings('error', category=warning_cls)
 
         yield
+
+
+class AbstractAttribute(object):
+    """An abstract class attribute.
+
+    Use this instead of an abstract property when you don't expect the
+    attribute to be implemented by a property.
+    """
+
+    __isabstractmethod__ = True
+
+    def __init__(self, doc=""):
+        self.__doc__ = doc
+
+    def __get__(self, obj, cls):
+        return self