Change serialization interface to be an object (#245)

* Change serialization interface to be an object

Rather than passing separate serialization and deserialization methods
to a pymemcache client, pass an object implementing a very simple
two-method interface.

This is a rather significant breaking change and should be part of an
x.0.0 major release.

Resolves #56

As suggested in that issue, this is a cleaner interface, as there's no
sensible context in which you would provide only one of these two
methods and it should therefore be thought of as a
serialization/deserialization protocol.

Also adds a note to the documentation's Best Practices list that you
should use the built-in serializer object unless you have a reason to do
otherwise.

* Support "de/serializer" in addition to "serde"

In order to support older client usage in addition to the new
serialization object (protocol), restore the "serializer" and
"deserializer" arguments to the Client classes.
These are marked as deprecated and will be automatically wrapped into a
small "serde" object.

In order to make the various object names more distinguishable and more
informative, the built-in default serializer is now called
"python_memcache_pickle_serde"

Additionally, default client.serde to a "no-op serializer".
This object does no transforms on the data. By putting this in place, we
can skip some conditionals in the code around presence or absence of a
serializer and therefore simplify internally (at the cost of an extra,
unnecessary, functional call in some cases).

It also simplifies logic around the handling of flags because we are now
*guaranteed* the presence of a serializer object which returns some
flags. i.e. "default flags" are no longer the responsibility of the
various serializer usage sites.
This is done carefully to ensure that passing a `serializer` without a
`deserializer` is respected.

4 files changed, 49 insertions, 49 deletions

diff --git a/pymemcache/test/test_client.py b/pymemcache/test/test_client.py
index a84e9c5..bfee6e1 100644
--- a/pymemcache/test/test_client.py
+++ b/pymemcache/test/test_client.py
@@ -665,10 +665,14 @@ class TestClient(ClientTestMixin, unittest.TestCase):
         assert result is False
 
     def test_serialization(self):
-        def _ser(key, value):
-            return json.dumps(value), 0
+        class JsonSerde(object):
+            def serialize(self, key, value):
+                return json.dumps(value).encode('ascii'), 0
+
+            def deserialize(self, key, value, flags):
+                return json.loads(value.decode('ascii'))
 
-        client = self.make_client([b'STORED\r\n'], serializer=_ser)
+        client = self.make_client([b'STORED\r\n'], serde=JsonSerde())
         client.set('key', {'c': 'd'})
         assert client.sock.send_bufs == [
             b'set key 0 0 10 noreply\r\n{"c": "d"}\r\n'
@@ -1205,22 +1209,23 @@ class TestMockClient(ClientTestMixin, unittest.TestCase):
         assert result == b'value'
 
     def test_deserialization(self):
-        def _serializer(key, value):
-            if isinstance(value, dict):
-                return json.dumps(value).encode('UTF-8'), 1
-            return value, 0
+        class JsonSerde(object):
+            def serialize(self, key, value):
+                if isinstance(value, dict):
+                    return json.dumps(value).encode('UTF-8'), 1
+                return value, 0
 
-        def _deserializer(key, value, flags):
-            if flags == 1:
-                return json.loads(value.decode('UTF-8'))
-            return value
+            def deserialize(self, key, value, flags):
+                if flags == 1:
+                    return json.loads(value.decode('UTF-8'))
+                return value
 
         client = self.make_client([
             b'STORED\r\n',
             b'VALUE key1 0 5\r\nhello\r\nEND\r\n',
             b'STORED\r\n',
             b'VALUE key2 0 18\r\n{"hello": "world"}\r\nEND\r\n',
-        ], serializer=_serializer, deserializer=_deserializer)
+        ], serde=JsonSerde())
 
         result = client.set(b'key1', b'hello', noreply=False)
         result = client.get(b'key1')
diff --git a/pymemcache/test/test_integration.py b/pymemcache/test/test_integration.py
index ad7a6fd..9ba6f97 100644
--- a/pymemcache/test/test_integration.py
+++ b/pymemcache/test/test_integration.py
@@ -26,9 +26,8 @@ from pymemcache.exceptions import (
     MemcacheClientError
 )
 from pymemcache.serde import (
-    get_python_memcache_serializer,
-    python_memcache_serializer,
-    python_memcache_deserializer
+    PickleSerde,
+    pickle_serde
 )
 
 
@@ -233,15 +232,16 @@ def test_misc(client_class, host, port, socket_module):
 
 @pytest.mark.integration()
 def test_serialization_deserialization(host, port, socket_module):
-    def _ser(key, value):
-        return json.dumps(value).encode('ascii'), 1
+    class JsonSerde(object):
+        def serialize(self, key, value):
+            return json.dumps(value).encode('ascii'), 1
 
-    def _des(key, value, flags):
-        if flags == 1:
-            return json.loads(value.decode('ascii'))
-        return value
+        def deserialize(self, key, value, flags):
+            if flags == 1:
+                return json.loads(value.decode('ascii'))
+            return value
 
-    client = Client((host, port), serializer=_ser, deserializer=_des,
+    client = Client((host, port), serde=JsonSerde(),
                     socket_module=socket_module)
     client.flush_all()
 
@@ -252,15 +252,14 @@ def test_serialization_deserialization(host, port, socket_module):
 
 
 def serde_serialization_helper(client_class, host, port,
-                               socket_module, serializer):
+                               socket_module, serde):
     def check(value):
         client.set(b'key', value, noreply=False)
         result = client.get(b'key')
         assert result == value
         assert type(result) is type(value)
 
-    client = client_class((host, port), serializer=serializer,
-                          deserializer=python_memcache_deserializer,
+    client = client_class((host, port), serde=serde,
                           socket_module=socket_module)
     client.flush_all()
 
@@ -281,7 +280,7 @@ def serde_serialization_helper(client_class, host, port,
 @pytest.mark.integration()
 def test_serde_serialization(client_class, host, port, socket_module):
     serde_serialization_helper(client_class, host, port,
-                               socket_module, python_memcache_serializer)
+                               socket_module, pickle_serde)
 
 
 @pytest.mark.integration()
@@ -289,7 +288,7 @@ def test_serde_serialization0(client_class, host, port, socket_module):
     serde_serialization_helper(
         client_class, host, port,
         socket_module,
-        get_python_memcache_serializer(pickle_version=0))
+        PickleSerde(pickle_version=0))
 
 
 @pytest.mark.integration()
@@ -297,7 +296,7 @@ def test_serde_serialization2(client_class, host, port, socket_module):
     serde_serialization_helper(
         client_class, host, port,
         socket_module,
-        get_python_memcache_serializer(pickle_version=2))
+        PickleSerde(pickle_version=2))
 
 
 @pytest.mark.integration()
diff --git a/pymemcache/test/test_serde.py b/pymemcache/test/test_serde.py
index e14568b..1850160 100644
--- a/pymemcache/test/test_serde.py
+++ b/pymemcache/test/test_serde.py
@@ -1,9 +1,9 @@
 # -*- coding: utf-8 -*-
 from unittest import TestCase
 
-from pymemcache.serde import (python_memcache_serializer,
-                              get_python_memcache_serializer,
-                              python_memcache_deserializer, FLAG_BYTES,
+from pymemcache.serde import (pickle_serde,
+                              PickleSerde,
+                              FLAG_BYTES,
                               FLAG_PICKLE, FLAG_INTEGER, FLAG_LONG, FLAG_TEXT)
 import pytest
 import six
@@ -22,10 +22,10 @@ class CustomInt(int):
 
 @pytest.mark.unit()
 class TestSerde(TestCase):
-    serializer = python_memcache_serializer
+    serde = pickle_serde
 
     def check(self, value, expected_flags):
-        serialized, flags = self.serializer(b'key', value)
+        serialized, flags = self.serde.serialize(b'key', value)
         assert flags == expected_flags
 
         # pymemcache stores values as byte strings, so we immediately the value
@@ -33,7 +33,7 @@ class TestSerde(TestCase):
         if not isinstance(serialized, six.binary_type):
             serialized = six.text_type(serialized).encode('ascii')
 
-        deserialized = python_memcache_deserializer(b'key', serialized, flags)
+        deserialized = self.serde.deserialize(b'key', serialized, flags)
         assert deserialized == value
 
     def test_bytes(self):
@@ -66,20 +66,21 @@ class TestSerde(TestCase):
 
 @pytest.mark.unit()
 class TestSerdePickleVersion0(TestCase):
-    serializer = get_python_memcache_serializer(pickle_version=0)
+    serde = PickleSerde(pickle_version=0)
 
 
 @pytest.mark.unit()
 class TestSerdePickleVersion1(TestCase):
-    serializer = get_python_memcache_serializer(pickle_version=1)
+    serde = PickleSerde(pickle_version=1)
 
 
 @pytest.mark.unit()
 class TestSerdePickleVersion2(TestCase):
-    serializer = get_python_memcache_serializer(pickle_version=2)
+    serde = PickleSerde(pickle_version=2)
 
 
 @pytest.mark.unit()
 class TestSerdePickleVersionHighest(TestCase):
-    serializer = get_python_memcache_serializer(
-        pickle_version=pickle.HIGHEST_PROTOCOL)
+    serde = PickleSerde(
+        pickle_version=pickle.HIGHEST_PROTOCOL
+    )
diff --git a/pymemcache/test/utils.py b/pymemcache/test/utils.py
index 301e2e6..b5ff72c 100644
--- a/pymemcache/test/utils.py
+++ b/pymemcache/test/utils.py
@@ -10,6 +10,7 @@ import time
 import six
 
 from pymemcache.exceptions import MemcacheIllegalInputError
+from pymemcache.serde import LegacyWrappingSerde
 
 
 class MockMemcacheClient(object):
@@ -20,8 +21,7 @@ class MockMemcacheClient(object):
 
     def __init__(self,
                  server=None,
-                 serializer=None,
-                 deserializer=None,
+                 serde=None,
                  connect_timeout=None,
                  timeout=None,
                  no_delay=False,
@@ -32,8 +32,7 @@ class MockMemcacheClient(object):
 
         self._contents = {}
 
-        self.serializer = serializer
-        self.deserializer = deserializer
+        self.serde = serde or LegacyWrappingSerde(None, None)
         self.allow_unicode_keys = allow_unicode_keys
 
         # Unused, but present for interface compatibility
@@ -63,9 +62,7 @@ class MockMemcacheClient(object):
             del self._contents[key]
             return default
 
-        if self.deserializer:
-            return self.deserializer(key, value, flags)
-        return value
+        return self.serde.deserialize(key, value, flags)
 
     def get_many(self, keys):
         out = {}
@@ -94,9 +91,7 @@ class MockMemcacheClient(object):
             except (UnicodeEncodeError, UnicodeDecodeError):
                 raise MemcacheIllegalInputError
 
-        flags = 0
-        if self.serializer:
-            value, flags = self.serializer(key, value)
+        value, flags = self.serde.serialize(key, value)
 
         if expire:
             expire += time.time()