diff --git a/docs/_newsfragments/1445.misc.rst b/docs/_newsfragments/1445.misc.rst new file mode 100644 index 000000000..e8af76927 --- /dev/null +++ b/docs/_newsfragments/1445.misc.rst @@ -0,0 +1,5 @@ +Documented the US-ASCII restriction on the ``name`` and ``value`` arguments +of :meth:`falcon.Response.set_cookie`. The implementation has always rejected +non-ASCII inputs (raising ``KeyError`` for ``name`` and ``ValueError`` for +``value``), but the parameter and ``Raises`` entries did not call this out; +the docstring now matches the runtime behaviour. diff --git a/falcon/response.py b/falcon/response.py index 314a1aac0..edfd304bc 100644 --- a/falcon/response.py +++ b/falcon/response.py @@ -372,8 +372,14 @@ def set_cookie( # noqa: C901 listed below correspond to those defined in `RFC 6265`_. Args: - name (str): Cookie name - value (str): Cookie value + name (str): Cookie name. Per :rfc:`6265#section-4.1.1`, cookie + names are restricted to US-ASCII characters; non-ASCII + values (e.g. multi-byte UTF-8 strings) raise ``KeyError``. + value (str): Cookie value. As with ``name``, the value must be + US-ASCII encodable; non-ASCII values raise ``ValueError``. + Encode non-ASCII payloads (for example with + :func:`urllib.parse.quote` or :mod:`base64`) before + passing them to this method. Keyword Args: expires (datetime): Specifies when the cookie should expire. @@ -471,8 +477,10 @@ def set_cookie( # noqa: C901 .. versionadded:: 4.0 Raises: - KeyError: `name` is not a valid cookie name. - ValueError: `value` is not a valid cookie value. + KeyError: `name` is not a valid cookie name (for example, + it contains non-ASCII characters). + ValueError: `value` is not a valid cookie value (for example, + it contains non-ASCII characters). .. _RFC 6265: http://tools.ietf.org/html/rfc6265