Unified and simplified API for all serializers

This patch is a proposition to the oslo.serialization for making a
more convenient API. Let me explain briefly why the current library
isn't very convenient for its users. Imagine that a library user
want to implement a function having some (de-)serialization inside.
The user also wants to make serialization configurable through
an additional argument to the function (e.g. some id like "json",
"msgpack" etc.). One can achieve this behaviour by importing all
necessary serializers (an import per a serializer) and adding
some logic for selecting an appropriate serialization mechanism
depending on id. But what if some new serializer is added to the
oslo.serialization? Then all users of the library will have to make
changes in their code. It's not good, and I think it would be better
if all changes concerning serializers were in the oslo.serialization
library. Therefore I think it is a good idea to have a module which
will bring together all implemented serializers under a unified and
somewhat simplified (because in most cases default values for some
parameters are fine) object oriented API, so that future users of the
library will be able to get any available serializer by its id
(importing only one module). Also it is worth saying that the patch
doesn't affect already written code, so there won't be any problems
with the backward compatibility.

May be this implementation isn't the best one, but I hope
the community will appreciate the idea and propose possible
improvements.

Change-Id: Idb12666255a990dfc8f8ff6b43e941b3481b9c1c

oslo_serialization/serializer/base_serializer.py

@@ -0,0 +1,58 @@
+#    Copyright 2016 Mirantis, Inc.
+#
+#    Licensed under the Apache License, Version 2.0 (the "License"); you may
+#    not use this file except in compliance with the License. You may obtain
+#    a copy of the License at
+#
+#         http://www.apache.org/licenses/LICENSE-2.0
+#
+#    Unless required by applicable law or agreed to in writing, software
+#    distributed under the License is distributed on an "AS IS" BASIS, WITHOUT
+#    WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. See the
+#    License for the specific language governing permissions and limitations
+#    under the License.
+
+"""
+Unified and simplified API for oslo.serialization's serializers.
+"""
+
+
+import abc
+import six
+
+
+@six.add_metaclass(abc.ABCMeta)
+class BaseSerializer(object):
+    """Generic (de-)serialization definition abstract base class."""
+
+    @abc.abstractmethod
+    def dump(self, obj, fp):
+        """Serialize ``obj`` as a stream to ``fp``.
+
+        :param obj: python object to be serialized
+        :param fp: ``.write()``-supporting file-like object
+        """
+
+    @abc.abstractmethod
+    def dump_as_bytes(self, obj):
+        """Serialize ``obj`` to a byte string.
+
+        :param obj: python object to be serialized
+        :returns: byte string
+        """
+
+    @abc.abstractmethod
+    def load(self, fp):
+        """Deserialize ``fp`` to a python object.
+
+        :param fp: ``.read()``-supporting file-like object
+        :returns: python object
+        """
+
+    @abc.abstractmethod
+    def load_from_bytes(self, s):
+        """Deserialize ``s`` to a python object.
+
+        :param s: byte string to be deserialized
+        :returns: python object
+        """

oslo_serialization/serializer/json_serializer.py

@@ -0,0 +1,38 @@
+#    Copyright 2016 Mirantis, Inc.
+#
+#    Licensed under the Apache License, Version 2.0 (the "License"); you may
+#    not use this file except in compliance with the License. You may obtain
+#    a copy of the License at
+#
+#         http://www.apache.org/licenses/LICENSE-2.0
+#
+#    Unless required by applicable law or agreed to in writing, software
+#    distributed under the License is distributed on an "AS IS" BASIS, WITHOUT
+#    WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. See the
+#    License for the specific language governing permissions and limitations
+#    under the License.
+
+
+from oslo_serialization import jsonutils
+from oslo_serialization.serializer.base_serializer import BaseSerializer
+
+
+class JSONSerializer(BaseSerializer):
+    """JSON serializer based on the jsonutils module."""
+
+    def __init__(self, default=jsonutils.to_primitive, encoding='utf-8'):
+        self._default = default
+        self._encoding = encoding
+
+    def dump(self, obj, fp):
+        return jsonutils.dump(obj, fp)
+
+    def dump_as_bytes(self, obj):
+        return jsonutils.dump_as_bytes(obj, default=self._default,
+                                       encoding=self._encoding)
+
+    def load(self, fp):
+        return jsonutils.load(fp, encoding=self._encoding)
+
+    def load_from_bytes(self, s):
+        return jsonutils.loads(s, encoding=self._encoding)

oslo_serialization/serializer/msgpack_serializer.py

@@ -0,0 +1,36 @@
+#    Copyright 2016 Mirantis, Inc.
+#
+#    Licensed under the Apache License, Version 2.0 (the "License"); you may
+#    not use this file except in compliance with the License. You may obtain
+#    a copy of the License at
+#
+#         http://www.apache.org/licenses/LICENSE-2.0
+#
+#    Unless required by applicable law or agreed to in writing, software
+#    distributed under the License is distributed on an "AS IS" BASIS, WITHOUT
+#    WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. See the
+#    License for the specific language governing permissions and limitations
+#    under the License.
+
+
+from oslo_serialization import msgpackutils
+from oslo_serialization.serializer.base_serializer import BaseSerializer
+
+
+class MessagePackSerializer(BaseSerializer):
+    """MessagePack serializer based on the msgpackutils module."""
+
+    def __init__(self, registry=None):
+        self._registry = registry
+
+    def dump(self, obj, fp):
+        return msgpackutils.dump(obj, fp, registry=self._registry)
+
+    def dump_as_bytes(self, obj):
+        return msgpackutils.dumps(obj, registry=self._registry)
+
+    def load(self, fp):
+        return msgpackutils.load(fp, registry=self._registry)
+
+    def load_from_bytes(self, s):
+        return msgpackutils.loads(s, registry=self._registry)