merge upstream

5 files changed, 34 insertions, 17 deletions

diff --git a/docs/narr/sessions.rst b/docs/narr/sessions.rst
index c2cc60de8..2da524d4c 100644
--- a/docs/narr/sessions.rst
+++ b/docs/narr/sessions.rst
@@ -85,32 +85,49 @@ This is a stricter contract than the previous requirement that all objects be pi
 This is a backward-incompatible change.
 Previously, if a client-side session implementation was compromised, it left the application vulnerable to remote code execution attacks using specially-crafted sessions that execute code when deserialized.
 
+Please reference the following tickets if detailed information on these changes is needed:
+
+* `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>`_.
+
 For users with compatibility concerns, it's possible to craft a serializer that can handle both formats until you are satisfied that clients have had time to reasonably upgrade.
 Remember that sessions should be short-lived and thus the number of clients affected should be small (no longer than an auth token, at a maximum). An example serializer:
 
 .. 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):
-            # 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)
+        def dumps(self, appstruct):
+            """
+            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 pickle serialization here as well.
+            """
+            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)
+                except Exception:
+                    # this block should catch at least:
+                    # ValueError, AttributeError, ImportError; but more to be safe
+                    raise ValueError
 
     # somewhere in your configuration code
     serializer = JSONSerializerWithPickleFallback()
diff --git a/docs/quick_tutorial/databases/tutorial/models.py b/docs/quick_tutorial/databases/tutorial/models.py
index b27c38417..8e6649d49 100644
--- a/docs/quick_tutorial/databases/tutorial/models.py
+++ b/docs/quick_tutorial/databases/tutorial/models.py
@@ -13,10 +13,10 @@ from sqlalchemy.orm import (
     sessionmaker,
     )
 
-from zope.sqlalchemy import ZopeTransactionExtension
+from zope.sqlalchemy import register
 
-DBSession = scoped_session(
-    sessionmaker(extension=ZopeTransactionExtension()))
+DBSession = scoped_session(sessionmaker())
+register(DBSession)
 Base = declarative_base()
 
 
@@ -32,4 +32,4 @@ class Root(object):
                (Allow, 'group:editors', 'edit')]
 
     def __init__(self, request):
-        pass
\ No newline at end of file
+        pass
diff --git a/docs/quick_tutorial/json.rst b/docs/quick_tutorial/json.rst
index 44d1de8cb..19d346199 100644
--- a/docs/quick_tutorial/json.rst
+++ b/docs/quick_tutorial/json.rst
@@ -63,7 +63,7 @@ Steps
 
    .. code-block:: bash
 
-    $ $VENV/bin/pserve development.ini --reload
+    $VENV/bin/pserve development.ini --reload
 
 #. Open http://localhost:6543/howdy.json in your browser and you will see the
    resulting JSON response.
diff --git a/docs/quick_tutorial/view_classes.rst b/docs/quick_tutorial/view_classes.rst
index 1307857b7..c9f61f5a3 100644
--- a/docs/quick_tutorial/view_classes.rst
+++ b/docs/quick_tutorial/view_classes.rst
@@ -78,7 +78,7 @@ To ease the transition to view classes, we didn't introduce any new
 functionality. We simply changed the view functions to methods on a view class,
 then updated the tests.
 
-In our ``TutorialViews`` view class, you can see that our two view classes are
+In our ``TutorialViews`` view class, you can see that our two view functions are
 logically grouped together as methods on a common class. Since the two views
 shared the same template, we could move that to a ``@view_defaults`` decorator
 at the class level.
diff --git a/docs/whatsnew-2.0.rst b/docs/whatsnew-2.0.rst
index 4448e0f69..b5f349166 100644
--- a/docs/whatsnew-2.0.rst
+++ b/docs/whatsnew-2.0.rst
@@ -58,7 +58,7 @@ flexibility in authorization implementations, especially those that do not
 match the ACL pattern.  If you were previously using
 :class:`pyramid.authorization.ACLAuthorizationPolicy`, you can achieve the same
 results by writing your own ``permits`` method using
-:class:`pyraid.authorization.ACLHelper`.  For more details on implementing an
+:class:`pyramid.authorization.ACLHelper`.  For more details on implementing an
 ACL, see :ref:`assigning_acls`.
 
 Pyramid does not provide any built-in security policies.  Similiar