deprecate PickleSerializer

4 files changed, 36 insertions, 10 deletions

diff --git a/CHANGES.rst b/CHANGES.rst
index 987d5c3d4..b70e8f4f8 100644
--- a/CHANGES.rst
+++ b/CHANGES.rst
@@ -4,6 +4,8 @@ unreleased
 Features
 --------
 
+- Deprecated ``pyramid.session.PickleSerializer``.
+
 - Changed the default ``serializer`` on
   ``pyramid.session.SignedCookieSessionFactory`` to use
   ``pyramid.session.JSONSerializer`` instead of
diff --git a/docs/narr/sessions.rst b/docs/narr/sessions.rst
index c2cc60de8..413dc5b8e 100644
--- a/docs/narr/sessions.rst
+++ b/docs/narr/sessions.rst
@@ -91,26 +91,32 @@ Remember that sessions should be short-lived and thus the number of clients affe
 .. code-block:: python
     :linenos:
 
+    import pickle
     from pyramid.session import JSONSerializer
-    from pyramid.session import PickleSerializer
     from pyramid.session import SignedCookieSessionFactory
 
+
     class JSONSerializerWithPickleFallback(object):
         def __init__(self):
             self.json = JSONSerializer()
-            self.pickle = PickleSerializer()
 
-        def dumps(self, value):
+        def dumps(self, appstruct):
+            """Accept a Python object and return bytes."""
             # maybe catch serialization errors here and keep using pickle
             # while finding spots in your app that are not storing
             # JSON-serializable objects, falling back to pickle
-            return self.json.dumps(value)
+            return self.json.dumps(appstruct)
 
-        def loads(self, value):
+        def loads(self, bstruct):
+            """Accept bytes and return a Python object."""
             try:
-                return self.json.loads(value)
+                return self.json.loads(bstruct)
             except ValueError:
-                return self.pickle.loads(value)
+                try:
+                    return pickle.loads(bstruct)
+                # at least ValueError, AttributeError, ImportError but more to be safe
+                except Exception:
+                    raise ValueError
 
     # somewhere in your configuration code
     serializer = JSONSerializerWithPickleFallback()
diff --git a/src/pyramid/session.py b/src/pyramid/session.py
index 70ac4f55f..adfe28a39 100644
--- a/src/pyramid/session.py
+++ b/src/pyramid/session.py
@@ -44,10 +44,24 @@ def manage_changed(wrapped):
 
 
 class PickleSerializer(object):
-    """ A serializer that uses the pickle protocol to dump Python
-    data to bytes.
+    """
+    .. deprecated:: 2.0
+
+    .. warning::
+
+    In :app:`Pyramid` 2.0 the default ``serializer`` option changed to
+    use :class:`pyramid.session.JSONSerializer`, and ``PickleSerializer`
+    has been been removed from active Pyramid code.
+
+    Pyramid will require JSON-serializable objects in :app:`Pyramid` 2.0.
+
+    Please see :ref:`pickle_session_deprecation`.
+
+    Also, please see: #2709, #3353, #3413
+
+    A serializer that uses the pickle protocol to dump Python data to bytes.
 
-    This is the default serializer used by Pyramid.
+    This was the default serializer used by Pyramid, but has been deprecated.
 
     ``protocol`` may be specified to control the version of pickle used.
     Defaults to :attr:`pickle.HIGHEST_PROTOCOL`.
diff --git a/tests/test_session.py b/tests/test_session.py
index 8e5e82bb2..582a7ed4a 100644
--- a/tests/test_session.py
+++ b/tests/test_session.py
@@ -564,6 +564,10 @@ class Test_manage_changed(unittest.TestCase):
 
 
 class TestPickleSerializer(unittest.TestCase):
+    """
+    .. deprecated:: 2.0
+    """
+
     def _makeOne(self):
         from pyramid.session import PickleSerializer