From f0d67b41b3b1223822186e861184b48ae1d3be20 Mon Sep 17 00:00:00 2001
From: Ben Darnell <ben@bendarnell.com>
Date: Sat, 20 May 2017 12:29:55 -0400
Subject: [PATCH] web: Clarify cookie method docs

Be explicit that get_cookie cannot see the cookies set within the
current request, avoiding confusion as seen in #1993
---
 tornado/web.py | 31 +++++++++++++++++++++++++++----
 1 file changed, 27 insertions(+), 4 deletions(-)

diff --git a/tornado/web.py b/tornado/web.py
index d79889fa3..64425b949 100644
--- a/tornado/web.py
+++ b/tornado/web.py
@@ -521,18 +521,28 @@ class RequestHandler(object):
         return self.request.cookies
 
     def get_cookie(self, name, default=None):
-        """Gets the value of the cookie with the given name, else default."""
+        """Returns the value of the request cookie with the given name.
+
+        If the named cookie is not present, returns ``default``.
+
+        This method only returns cookies that were present in the request.
+        It does not see the outgoing cookies set by `set_cookie` in this
+        handler.
+        """
         if self.request.cookies is not None and name in self.request.cookies:
             return self.request.cookies[name].value
         return default
 
     def set_cookie(self, name, value, domain=None, expires=None, path="/",
                    expires_days=None, **kwargs):
-        """Sets the given cookie name/value with the given options.
+        """Sets an outgoing cookie name/value with the given options.
+
+        Newly-set cookies are not immediately visible via `get_cookie`;
+        they are not present until the next request.
 
-        Additional keyword arguments are set on the Cookie.Morsel
+        Additional keyword arguments are set on the cookies.Morsel
         directly.
-        See https://docs.python.org/2/library/cookie.html#Cookie.Morsel
+        See https://docs.python.org/3/library/http.cookies.html#http.cookies.Morsel
         for available attributes.
         """
         # The cookie library only accepts type str, in both python 2 and 3
@@ -574,6 +584,9 @@ class RequestHandler(object):
         path and domain to clear a cookie as were used when that cookie
         was set (but there is no way to find out on the server side
         which values were used for a given cookie).
+
+        Similar to `set_cookie`, the effect of this method will not be
+        seen until the following request.
         """
         expires = datetime.datetime.utcnow() - datetime.timedelta(days=365)
         self.set_cookie(name, value="", path=path, expires=expires,
@@ -585,6 +598,9 @@ class RequestHandler(object):
         See `clear_cookie` for more information on the path and domain
         parameters.
 
+        Similar to `set_cookie`, the effect of this method will not be
+        seen until the following request.
+
         .. versionchanged:: 3.2
 
            Added the ``path`` and ``domain`` parameters.
@@ -609,6 +625,9 @@ class RequestHandler(object):
         Secure cookies may contain arbitrary byte values, not just unicode
         strings (unlike regular cookies)
 
+        Similar to `set_cookie`, the effect of this method will not be
+        seen until the following request.
+
         .. versionchanged:: 3.2.1
 
            Added the ``version`` argument.  Introduced cookie version 2
@@ -648,6 +667,10 @@ class RequestHandler(object):
         The decoded cookie value is returned as a byte string (unlike
         `get_cookie`).
 
+        Similar to `get_cookie`, this method only returns cookies that
+        were present in the request. It does not see outgoing cookies set by
+        `set_secure_cookie` in this handler.
+
         .. versionchanged:: 3.2.1
 
            Added the ``min_version`` argument.  Introduced cookie version 2;
-- 
2.47.2