changes based on feedback

2 files changed, 31 insertions, 16 deletions

diff --git a/docs/narr/sessions.rst b/docs/narr/sessions.rst
index 413dc5b8e..d9befec82 100644
--- a/docs/narr/sessions.rst
+++ b/docs/narr/sessions.rst
@@ -101,10 +101,14 @@ Remember that sessions should be short-lived and thus the number of clients affe
             self.json = JSONSerializer()
 
         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
+            """
+            Accept a Python object and return bytes.
+
+            During a migration, you may want to catch serialization errors here,
+            and keep using pickle while finding spots in your app that are not
+            storing JSON-serializable objects. You may also want to integrate
+            a fall-back to picke serialization here as well.
+            """
             return self.json.dumps(appstruct)
 
         def loads(self, bstruct):
@@ -114,8 +118,9 @@ Remember that sessions should be short-lived and thus the number of clients affe
             except ValueError:
                 try:
                     return pickle.loads(bstruct)
-                # at least ValueError, AttributeError, ImportError but more to be safe
                 except Exception:
+					# this block should catch at least:
+					# ValueError, AttributeError, ImportError; but more to be safe
                     raise ValueError
 
     # somewhere in your configuration code
diff --git a/src/pyramid/session.py b/src/pyramid/session.py
index adfe28a39..efac52140 100644
--- a/src/pyramid/session.py
+++ b/src/pyramid/session.py
@@ -49,15 +49,24 @@ class PickleSerializer(object):
 
     .. 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.
+        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.
+        Pyramid will require JSON-serializable objects in :app:`Pyramid` 2.0.
 
-    Please see :ref:`pickle_session_deprecation`.
+        Please see :ref:`pickle_session_deprecation`.
 
-    Also, please see: #2709, #3353, #3413
+        Also, please see these tickets: 
+
+        * 2.0 feature request: Require that sessions are JSON serializable #2709
+          https://github.com/pylons/pyramid/issues/2709
+
+        * deprecate pickleable sessions, recommend json #3353
+          https://github.com/Pylons/pyramid/pull/3353
+
+        * change to use JSONSerializer for SignedCookieSessionFactory #3413
+          https://github.com/Pylons/pyramid/pull/3413
 
     A serializer that uses the pickle protocol to dump Python data to bytes.
 
@@ -75,8 +84,9 @@ class PickleSerializer(object):
         """Accept bytes and return a Python object."""
         try:
             return pickle.loads(bstruct)
-        # at least ValueError, AttributeError, ImportError but more to be safe
         except Exception:
+            # this block should catch at least:
+            # ValueError, AttributeError, ImportError; but more to be safe
             raise ValueError
 
     def dumps(self, appstruct):
@@ -452,10 +462,10 @@ def SignedCookieSessionFactory(
 
     .. warning::
 
-       In :app:`Pyramid` 2.0 the default ``serializer`` option changed to
-       use :class:`pyramid.session.JSONSerializer`. See
-       :ref:`pickle_session_deprecation` for more information about why this
-       change was made.
+        In :app:`Pyramid` 2.0 the default ``serializer`` option changed to
+        use :class:`pyramid.session.JSONSerializer`. See
+        :ref:`pickle_session_deprecation` for more information about why this
+        change was made.
 
     .. versionadded: 1.5a3