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. Most arguments are passed directly to `http.cookies.Morsel` directly. See https://developer.mozill
(
self,
name: str,
value: Union[str, bytes],
domain: Optional[str] = None,
expires: Optional[Union[float, Tuple, datetime.datetime]] = None,
path: str = "/",
expires_days: Optional[float] = None,
# Keyword-only args start here for historical reasons.
*,
max_age: Optional[int] = None,
httponly: bool = False,
secure: bool = False,
samesite: Optional[str] = None,
**kwargs: Any,
)
| 655 | return default |
| 656 | |
| 657 | def set_cookie( |
| 658 | self, |
| 659 | name: str, |
| 660 | value: Union[str, bytes], |
| 661 | domain: Optional[str] = None, |
| 662 | expires: Optional[Union[float, Tuple, datetime.datetime]] = None, |
| 663 | path: str = "/", |
| 664 | expires_days: Optional[float] = None, |
| 665 | # Keyword-only args start here for historical reasons. |
| 666 | *, |
| 667 | max_age: Optional[int] = None, |
| 668 | httponly: bool = False, |
| 669 | secure: bool = False, |
| 670 | samesite: Optional[str] = None, |
| 671 | **kwargs: Any, |
| 672 | ) -> None: |
| 673 | """Sets an outgoing cookie name/value with the given options. |
| 674 | |
| 675 | Newly-set cookies are not immediately visible via `get_cookie`; |
| 676 | they are not present until the next request. |
| 677 | |
| 678 | Most arguments are passed directly to `http.cookies.Morsel` directly. |
| 679 | See https://developer.mozilla.org/en-US/docs/Web/HTTP/Headers/Set-Cookie |
| 680 | for more information. |
| 681 | |
| 682 | ``expires`` may be a numeric timestamp as returned by `time.time`, |
| 683 | a time tuple as returned by `time.gmtime`, or a |
| 684 | `datetime.datetime` object. ``expires_days`` is provided as a convenience |
| 685 | to set an expiration time in days from today (if both are set, ``expires`` |
| 686 | is used). |
| 687 | |
| 688 | .. deprecated:: 6.3 |
| 689 | Keyword arguments are currently accepted case-insensitively. |
| 690 | In Tornado 7.0 this will be changed to only accept lowercase |
| 691 | arguments. |
| 692 | """ |
| 693 | # The cookie library only accepts type str, in both python 2 and 3 |
| 694 | name = escape.native_str(name) |
| 695 | value = escape.native_str(value) |
| 696 | if re.search(r"[\x00-\x20]", value): |
| 697 | # Legacy check for control characters in cookie values. This check is no longer needed |
| 698 | # since the cookie library escapes these characters correctly now. It will be removed |
| 699 | # in the next feature release. |
| 700 | raise ValueError(f"Invalid cookie {name!r}: {value!r}") |
| 701 | for attr_name, attr_value in [ |
| 702 | ("name", name), |
| 703 | ("domain", domain), |
| 704 | ("path", path), |
| 705 | ("samesite", samesite), |
| 706 | ]: |
| 707 | # Cookie attributes may not contain control characters or semicolons (except when |
| 708 | # escaped in the value). A check for control characters was added to the http.cookies |
| 709 | # library in a Feb 2026 security release; as of March it still does not check for |
| 710 | # semicolons. |
| 711 | # |
| 712 | # When a semicolon check is added to the standard library (and the release has had time |
| 713 | # for adoption), this check may be removed, but be mindful of the fact that this may |
| 714 | # change the timing of the exception (to the generation of the Set-Cookie header in |
no test coverage detected