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, 39 insertions, 27 deletions

diff --git a/docs/getting_started.rst b/docs/getting_started.rst
index be9e0c1..4e1b9ef 100644
--- a/docs/getting_started.rst
+++ b/docs/getting_started.rst
@@ -49,20 +49,20 @@ Serialization
      import json
      from pymemcache.client.base import Client
 
-     def json_serializer(key, value):
-         if type(value) == str:
-             return value, 1
-         return json.dumps(value), 2
-
-     def json_deserializer(key, value, flags):
-        if flags == 1:
-            return value
-        if flags == 2:
-            return json.loads(value)
-        raise Exception("Unknown serialization format")
-
-     client = Client(('localhost', 11211), serializer=json_serializer,
-                     deserializer=json_deserializer)
+     class JsonSerde(object):
+         def serialize(self, key, value):
+             if isinstance(value, str):
+                 return value, 1
+             return json.dumps(value), 2
+
+         def deserialize(self, key, value, flags):
+            if flags == 1:
+                return value
+            if flags == 2:
+                return json.loads(value)
+            raise Exception("Unknown serialization format")
+
+     client = Client(('localhost', 11211), serde=JsonSerde())
      client.set('key', {'a':'b', 'c':'d'})
      result = client.get('key')
 
@@ -77,34 +77,44 @@ pymemcache provides a default
     class Foo(object):
       pass
 
-    client = Client(('localhost', 11211),
-        serializer=serde.python_memcache_serializer,
-        deserializer=serde.python_memcache_deserializer)
+    client = Client(('localhost', 11211), serde=serde.pickle_serde)
     client.set('key', Foo())
     result client.get('key')
 
 The serializer uses the highest pickle protocol available. In order to make
 sure multiple versions of Python can read the protocol version, you can specify
-the version with :func:`pymemcache.serde.get_python_memcache_serializer`.
+the version by explicitly instantiating :class:`pymemcache.serde.PickleSerde`:
 
 .. code-block:: python
 
-    client = Client(('localhost', 11211),
-        serializer=serde.get_python_memcache_serializer(pickle_version=2),
-        deserializer=serde.python_memcache_deserializer)
+    client = Client(
+        ('localhost', 11211),
+        serde=serde.PickleSerde(pickle_version=2)
+    )
 
 
 Deserialization with Python 3
 -----------------------------
 
+Values passed to the `serde.deserialize()` method will be bytestrings. It is
+therefore necessary to encode and decode them correctly. Here's a version of
+the `JsonSerde` from above which is more careful with encodings:
+
 .. code-block:: python
 
-    def json_deserializer(key, value, flags):
-        if flags == 1:
-            return value.decode('utf-8')
-        if flags == 2:
-            return json.loads(value.decode('utf-8'))
-        raise Exception("Unknown serialization format")
+     class JsonSerde(object):
+         def serialize(self, key, value):
+             if isinstance(value, str):
+                 return value.encode('utf-8'), 1
+             return json.dumps(value).encode('utf-8'), 2
+
+         def deserialize(self, key, value, flags):
+            if flags == 1:
+                return value.decode('utf-8')
+            if flags == 2:
+                return json.loads(value.decode('utf-8'))
+            raise Exception("Unknown serialization format")
+
 
 Key Constraints
 ---------------
@@ -140,6 +150,8 @@ Best Practices
    errors, from killing your web requests. Do not use this flag if you need to
    know about errors from memcache, and make sure you have some other way to
    detect memcache server failures.
+ - Unless you have a known reason to do otherwise, use the provided serializer
+   in `pymemcache.serde.pickle_serde` for any de/serialization of objects.
 
 .. WARNING::