update the public api for remember

3 files changed, 36 insertions, 4 deletions

diff --git a/docs/api/security.rst b/docs/api/security.rst
index 814b68e5a..88086dbbf 100644
--- a/docs/api/security.rst
+++ b/docs/api/security.rst
@@ -16,7 +16,7 @@ Authentication API Functions
 
 .. autofunction:: forget
 
-.. autofunction:: remember
+.. autofunction:: remember(request, userid, **kwargs)
 
 Authorization API Functions
 ---------------------------
diff --git a/pyramid/security.py b/pyramid/security.py
index 3cef7ee5a..cbb4b895f 100644
--- a/pyramid/security.py
+++ b/pyramid/security.py
@@ -17,6 +17,8 @@ Authenticated = 'system.Authenticated'
 Allow = 'Allow'
 Deny = 'Deny'
 
+_marker = object()
+
 class AllPermissionsList(object):
     """ Stand in 'permission list' to represent all permissions """
     def __iter__(self):
@@ -115,7 +117,7 @@ deprecated(
     '"effective_principals" attribute of the Pyramid request instead.'
     )
 
-def remember(request, userid, **kw):
+def remember(request, userid=_marker, **kw):
     """
     Returns a sequence of header tuples (e.g. ``[('Set-Cookie', 'foo=abc')]``)
     on this request's response.
@@ -138,7 +140,24 @@ def remember(request, userid, **kw):
     always return an empty sequence. If used, the composition and
     meaning of ``**kw`` must be agreed upon by the calling code and
     the effective authentication policy.
+    
+    .. deprecated:: 1.6
+        Renamed the ``principal`` argument to ``userid`` to clarify its
+        purpose.
     """
+    if userid is _marker:
+        principal = kw.pop('principal', _marker)
+        if principal is _marker:
+            raise TypeError(
+                'remember() missing 1 required positional argument: '
+                '\'userid\'')
+        else:
+            deprecated(
+                'principal',
+                'The "principal" argument was deprecated in Pyramid 1.6. '
+                'It will be removed in Pyramid 1.9. Use the "userid" '
+                'argument instead.')
+            userid = principal
     policy = _get_authentication_policy(request)
     if policy is None:
         return []
diff --git a/pyramid/tests/test_security.py b/pyramid/tests/test_security.py
index 027f9cda0..6d75ac8e3 100644
--- a/pyramid/tests/test_security.py
+++ b/pyramid/tests/test_security.py
@@ -134,9 +134,9 @@ class TestRemember(unittest.TestCase):
     def tearDown(self):
         testing.tearDown()
 
-    def _callFUT(self, *arg):
+    def _callFUT(self, *arg, **kwarg):
         from pyramid.security import remember
-        return remember(*arg)
+        return remember(*arg, **kwarg)
 
     def test_no_authentication_policy(self):
         request = _makeRequest()
@@ -159,6 +159,19 @@ class TestRemember(unittest.TestCase):
         result = self._callFUT(request, 'me')
         self.assertEqual(result, [('X-Pyramid-Test', 'me')])
 
+    def test_with_deprecated_principal_arg(self):
+        request = _makeRequest()
+        registry = request.registry
+        _registerAuthenticationPolicy(registry, 'yo')
+        result = self._callFUT(request, principal='me')
+        self.assertEqual(result, [('X-Pyramid-Test', 'me')])
+
+    def test_with_missing_arg(self):
+        request = _makeRequest()
+        registry = request.registry
+        _registerAuthenticationPolicy(registry, 'yo')
+        self.assertRaises(TypeError, lambda: self._callFUT(request))
+
 class TestForget(unittest.TestCase):
     def setUp(self):
         testing.setUp()