gh-92936: update http.cookies docs post GH-113663

[nburns]

#92936 (comment)

Updates http.cookie docs to reflect changes from #113663

• Issue: SimpleCookie() fails for json-like values with embedded double-quotes #92936

---

📚 Documentation preview 📚: https://cpython-previews--137566.org.readthedocs.build/

[picnixz]

Also add a What's New entry (Doc/whatsnew/3.15.rst).

[picnixz]

Please avoid force-pushing. It makes incremental review harder. We squash-merge commits at the end.

[nburns]

I sure will, thanks for all your help!

[picnixz]

Now I'm wondering, shouldn't we have quotes? I actually didn't check how browsers do but do they escape quotes? (we have an example above that escape the quotes which is why I'm asking).

[nburns]

IIRC: A string like that is technically not included in the RFC, but all the major browsers support strings like that.

There was a big 3rd party (zoom) that was putting JSON in cookies for a while, and all the cookies after that one would just get truncated by the python cookie module. In our case our session cookie came after the 3rd party one, resulting in users being "logged out" in a super hard to debug way.

So as a more direct answer to your question ITT: We shouldn't care about quotes, and if someone cares to escape quotes inside their cookies that's up to them. Ideally the cookies module should put as few restrictions on the value of a cookie as possible (while still being able to parse the cookies), since that's an application level consideration.

[nburns]

yt-dlp/yt-dlp#4780 and aio-libs/aiohttp#7993 have both taken it upon themselves to write a whole cookie parsing module to work around this issue

[picnixz]

So, browsers do support strings like these. If that is the case, then it's fine. Historically, the module applies strict parsing so if this is not allowed by the RFC, we shouldn't do it either and that's an issue with the applications themselves. However, we relaxed the rules so this is an acceptable change.

[orsenthil]

I think, we should demonstrate with an escaped double quote, for json like value in the docs. We wont get a doubt if it is a valid json / valid python string.

>>> import http.cookies
>>> C = http.cookies.SimpleCookie()
>>> C.load('cookies=7; mixins="{\"chips\": \"dark chocolate\"}"; state="gooey"')
>>> C
<SimpleCookie: cookies='7' mixins='{"chips": "dark chocolate"}' state='gooey'>

Previous behavior was wrong for this state too.

Python 3.13.4 (main, Jun  3 2025, 15:34:24) [GCC 11.4.0] on linux
Type "help", "copyright", "credits" or "license" for more information.
>>> import http.cookies
>>> C = http.cookies.SimpleCookie()
>>> C.load('cookies=7; mixins="{\"chips\": \"dark chocolate\"}"; state="gooey"')
>>> C
<SimpleCookie: cookies='7'>

>>> C.load('cookies=7; mixins="{"chips": "dark chocolate"}"; state="gooey"')
>>> C
<SimpleCookie: cookies='7'>

[nburns]

I think the / is getting consumed?

>>> C = cookies.SimpleCookie()
>>> C.load('cookies=7; mixins="{"chips": "dark chocolate"}"; state="gooey"')
>>> print(C)
Set-Cookie: cookies=7
Set-Cookie: mixins="{"chips": "dark chocolate"}"
Set-Cookie: state="gooey"
>>> C = cookies.SimpleCookie()
>>> C.load(r'cookies=7; mixins="{\"chips\": \"dark chocolate\"}"; state="gooey"')
>>> print(C)
Set-Cookie: cookies=7
Set-Cookie: mixins="{\"chips\": \"dark chocolate\"}"
Set-Cookie: state="gooey"

since

>>> '\"' == '"'
True

[orsenthil]

Yeah, In the docs, I was wondering if giving an example that is more valid of ways of representing json or python string would help. Like my snippet above. Otherwise, this double-quotes within double-quotes in docs, I suspect, will invite more questions in the future. WDYT?

[nburns]

I agree the unescaped-quote-inside-quotes is kinda weird looking, but in the case of the bug, that was exactly the problem that was breaking cookie parsing. Not opposed to changing don't want to also make some docs that are misleading, or otherwise odd.

[nburns]

Is it acceptable to use other modules in examples? Maybe something like this which shows it's json in a cookie:

>>> C = http.cookies.SimpleCookie()
>>> C.load(f'mixins="{json.dumps({"chips": "dark chocolate"})}";')
>>> print(C)
Set-Cookie: mixins="{"chips": "dark chocolate"}"

[orsenthil]

Maybe something like this which shows it's json in a cookie

This is better. It is find to use stdlib module json in this example as demonstrates the json handling with the cookie. Please update the example with this suggestion.