From 0921db8b34c6b1967f249d42dee6b652a3b987ef Mon Sep 17 00:00:00 2001 From: Chris McDonough Date: Mon, 28 Oct 2013 17:24:30 -0400 Subject: wording and specify return value --- pyramid/security.py | 28 +++++++++++++--------------- 1 file changed, 13 insertions(+), 15 deletions(-) diff --git a/pyramid/security.py b/pyramid/security.py index 0d10b3998..b0fd38678 100644 --- a/pyramid/security.py +++ b/pyramid/security.py @@ -380,18 +380,19 @@ class AuthenticationAPIMixin(object): def remember_userid(self, principal, on_exception=False, **kw): """ Sets a sequence of header tuples (e.g. ``[('Set-Cookie', - 'foo=abc')]``) on this request's response. - These headers are suitable for 'remembering' a set of credentials - implied by the data passed as ``principal`` and ``*kw`` using the - current :term:`authentication policy`. Common usage might look - like so within the body of a view function (``response`` is - assumed to be a :term:`WebOb` -style :term:`response` object - computed previously by the view code):: + 'foo=abc')]``) on the response eventually returned using a response + callback. These headers are used for 'remembering' a set of + credentials implied by the data passed as ``principal`` and ``*kw`` + using the current :term:`authentication policy`. Common usage might + look like so within the body of a view function:: .. code-block:: python request.remember_userid('chrism', password='123', max_age='86400') + This method always returns ``None``; it is called only for its side + effects. + If no :term:`authentication policy` is in use, this function will do nothing. If used, the composition and meaning of ``**kw`` must be agreed upon by the calling code and @@ -431,18 +432,15 @@ class AuthenticationAPIMixin(object): def forget_userid(self, on_exception=False): """ Sets a sequence of header tuples (e.g. ``[('Set-Cookie', 'foo=abc')]``) suitable for 'forgetting' the set of credentials - possessed by the currently authenticated user on the response. - A common usage might look like so within the body of a view function - (``response`` is assumed to be an :term:`WebOb` -style - :term:`response` object computed previously by the view code):: - - .. code-block:: python - - request.forget_userid() + possessed by the currently authenticated user on the response based on + the current :term:`authentication policy`, using a response callback. If no :term:`authentication policy` is in use, this function will be a noop. + This method always returns ``None``; it is called only for its side + effects. + One special keyword value is understood by this method: ``on_exception``. Usually if an exception occurs within the same request after this method is called, the headers provided by the -- cgit v1.2.3