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, 6 insertions, 0 deletions

diff --git a/ChangeLog.rst b/ChangeLog.rst
index 321e51c..fb8b628 100644
--- a/ChangeLog.rst
+++ b/ChangeLog.rst
@@ -7,6 +7,12 @@ New in version 3.0.0 (unreleased)
 * Validate integer inputs for ``expire``, ``delay``, ``incr``, ``decr``, and
   ``memlimit`` -- non-integer values now raise ``MemcacheIllegalInputError``
 
+* The serialization API has been reworked. Instead of consuming a serializer
+  and deserializer as separate arguments, client objects now expect an argument
+  `serde` to be an object which implements `serialize` and `deserialize`
+  as methods. (`serialize` and `deserialize` are still supported but considered
+  deprecated)
+
 New in version 2.2.2
 --------------------
 * Fix ``long_description`` string in Python packaging.