From: Ben Darnell <ben@bendarnell.com>
Date: Sat, 28 Jan 2023 19:10:16 +0000 (+0000)
Subject: web: List all set_cookie arguments instead of kwargs
X-Git-Tag: v6.3.0b1~11^2~1
X-Git-Url: http://git.ipfire.org/cgi-bin/gitweb.cgi?a=commitdiff_plain;h=06043625ac83622daa28d954747b16f70f26e1cd;p=thirdparty%2Ftornado.git

web: List all set_cookie arguments instead of kwargs

Multiple arguments needed special cases anyway, so it's better to
just be explicit about what's supported.

set_signed_cookie still uses kwarg forwarding since we don't need
to worry about the special cases at this level and using
explicit arguments would involve duplicating defaults in multiple
places.
---

diff --git a/tornado/web.py b/tornado/web.py
index 42306a7fe..c1230260f 100644
--- a/tornado/web.py
+++ b/tornado/web.py
@@ -603,21 +603,28 @@ class RequestHandler(object):
         expires: Optional[Union[float, Tuple, datetime.datetime]] = None,
         path: str = "/",
         expires_days: Optional[float] = None,
-        **kwargs: Any
+        # Keyword-only args start here for historical reasons.
+        *,
+        max_age: Optional[int] = None,
+        httponly: bool = False,
+        secure: bool = False,
+        samesite: Optional[str] = None,
     ) -> None:
         """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.
 
-        expires may be a numeric timestamp as returned by `time.time`,
+        Most arguments are passed directly to `http.cookies.Morsel` directly.
+        See https://developer.mozilla.org/en-US/docs/Web/HTTP/Headers/Set-Cookie
+        for more information.
+
+        ``expires`` may be a numeric timestamp as returned by `time.time`,
         a time tuple as returned by `time.gmtime`, or a
-        `datetime.datetime` object.
+        `datetime.datetime` object. ``expires_days`` is provided as a convenience
+        to set an expiration time in days from today (if both are set, ``expires``
+        is used).
 
-        Additional keyword arguments are set on the cookies.Morsel
-        directly.
-        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
         name = escape.native_str(name)
@@ -641,16 +648,17 @@ class RequestHandler(object):
             morsel["expires"] = httputil.format_timestamp(expires)
         if path:
             morsel["path"] = path
-        for k, v in kwargs.items():
-            if k == "max_age":
-                k = "max-age"
-
-            # skip falsy values for httponly and secure flags because
-            # SimpleCookie sets them regardless
-            if k in ["httponly", "secure"] and not v:
-                continue
-
-            morsel[k] = v
+        if max_age:
+            # Note change from _ to -.
+            morsel["max-age"] = str(max_age)
+        if httponly:
+            # Note that SimpleCookie ignores the value here. The presense of an
+            # httponly (or secure) key is treated as true.
+            morsel["httponly"] = True
+        if secure:
+            morsel["secure"] = True
+        if samesite:
+            morsel["samesite"] = samesite
 
     def clear_cookie(
         self, name: str, path: str = "/", domain: Optional[str] = None