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.

1 files changed, 17 insertions, 12 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')