use zope.deprecation for warning about the UnencryptedCookieSessionFactoryConfig deprecation (it will happen at import time, rather than usage time, which is good for tests); add a few sphinx directives for deprecated and versionadded

2 files changed, 29 insertions, 13 deletions

diff --git a/pyramid/session.py b/pyramid/session.py
index 6ffef7a22..60a5f7a63 100644
--- a/pyramid/session.py
+++ b/pyramid/session.py
@@ -4,8 +4,8 @@ import hashlib
 import hmac
 import os
 import time
-import warnings
 
+from zope.deprecation import deprecated
 from zope.interface import implementer
 
 from pyramid.compat import (
@@ -133,11 +133,13 @@ def BaseCookieSessionFactory(
     set_on_exception=True,
     ):
     """
+    .. versionadded:: 1.5
+    
     Configure a :term:`session factory` which will provide cookie-based
-    sessions.  The return value of this function is a
-    :term:`session factory`, which may be provided as the ``session_factory``
-    argument of a :class:`pyramid.config.Configurator` constructor, or used
-    as the ``session_factory`` argument of the
+    sessions.  The return value of this function is a :term:`session factory`,
+    which may be provided as the ``session_factory`` argument of a
+    :class:`pyramid.config.Configurator` constructor, or used as the
+    ``session_factory`` argument of the
     :meth:`pyramid.config.Configurator.set_session_factory` method.
 
     The session factory returned by this function will create sessions
@@ -355,6 +357,7 @@ def BaseCookieSessionFactory(
 
     return CookieSession
 
+
 def UnencryptedCookieSessionFactoryConfig(
     secret,
     timeout=1200,
@@ -369,6 +372,9 @@ def UnencryptedCookieSessionFactoryConfig(
     signed_deserialize=signed_deserialize,
     ):
     """
+    .. deprecated:: 1.5
+       Use :func:`pyramid.session.SignedCookieSessionFactory` instead.
+    
     Configure a :term:`session factory` which will provide unencrypted
     (but signed) cookie-based sessions.  The return value of this
     function is a :term:`session factory`, which may be provided as
@@ -424,14 +430,6 @@ def UnencryptedCookieSessionFactoryConfig(
       is valid. Default: ``signed_deserialize`` (using pickle).
     """
 
-    warnings.warn(
-        ('The UnencryptedCookieSessionFactoryConfig is deprecated as of '
-         'Pyramid 1.5, and will be replaced by the '
-         'SignedCookieSessionFactory in future versions.'),
-        DeprecationWarning,
-        stacklevel=2
-        )
-
     return BaseCookieSessionFactory(
         lambda v: signed_serialize(v, secret),
         lambda v: signed_deserialize(v, secret),
@@ -446,6 +444,12 @@ def UnencryptedCookieSessionFactoryConfig(
         set_on_exception=cookie_on_exception,
     )
 
+deprecated(
+    'UnencryptedCookieSessionFactoryConfig',
+    'The UnencryptedCookieSessionFactoryConfig callable is deprecated as of '
+    'Pyramid 1.5.  Use ``pyramid.session.SignedCookieSessionFactory`` instead.'
+    )
+
 def SignedCookieSessionFactory(
     secret,
     cookie_name='session',
@@ -463,6 +467,8 @@ def SignedCookieSessionFactory(
     deserialize=None,
     ):
     """
+    .. versionadded:: 1.5
+    
     Configure a :term:`session factory` which will provide signed
     cookie-based sessions.  The return value of this
     function is a :term:`session factory`, which may be provided as
diff --git a/pyramid/tests/test_session.py b/pyramid/tests/test_session.py
index 382cf8eb5..eba123ce5 100644
--- a/pyramid/tests/test_session.py
+++ b/pyramid/tests/test_session.py
@@ -371,6 +371,16 @@ class TestSignedCookieSession(SharedCookieSessionTests, unittest.TestCase):
         self.assertEqual(session, {})
 
 class TestUnencryptedCookieSession(SharedCookieSessionTests, unittest.TestCase):
+    def setUp(self):
+        super(TestUnencryptedCookieSession, self).setUp()
+        from zope.deprecation import __show__
+        __show__.off()
+
+    def tearDown(self):
+        super(TestUnencryptedCookieSession, self).tearDown()
+        from zope.deprecation import __show__
+        __show__.on()
+        
     def _makeOne(self, request, **kw):
         from pyramid.session import UnencryptedCookieSessionFactoryConfig
         self._rename_cookie_var(kw, 'path', 'cookie_path')