Cookies(cookies=<CookieJar>) aliases the input instead of copying it

[tritsystem]

AI disclosure: this was investigated and written with the assistance of Claude (Anthropic). I independently reproduced it against a fresh clone of main myself before posting — repro below, runnable standalone.

Summary

Cookies.__init__ (httpx/_models.py) handles four documented input types (CookieTypes = dict | list | Cookies | CookieJar). Three of the four branches build a fresh CookieJar() and copy the input's contents in. The fourth — a raw http.cookiejar.CookieJar, also a documented input type — just aliases it directly:

def __init__(self, cookies: CookieTypes | None = None) -> None:
    if cookies is None or isinstance(cookies, dict):
        self.jar = CookieJar()
        ...
    elif isinstance(cookies, list):
        self.jar = CookieJar()
        ...
    elif isinstance(cookies, Cookies):
        self.jar = CookieJar()
        ...
    else:
        self.jar = cookies   # <-- direct alias, not a copy

So constructing a Client/AsyncClient with an existing CookieJar means any cookie the client later sets, or extracts from a response, silently mutates the caller's own CookieJar object — and any cookies already in that jar are shared, not copied. This breaks the property the other three input types honor: that a Cookies/Client instance owns independent state after construction.

Reproduction

from http.cookiejar import CookieJar
import httpx

jar = CookieJar()
client = httpx.Client(cookies=jar)
print(client.cookies.jar is jar)   # True -- should be a copy, like every other input type

client.cookies.set("foo", "bar")
print(list(jar))   # the CALLER's own jar now contains "foo" -- silent mutation

Real output from running this against today's main:

client.cookies.jar is jar: True
after client.cookies.set(), caller's own jar now contains: [Cookie(name='foo', value='bar', ...)]

No network needed to reproduce — plain construction is enough.

Why I think it's worth a look

Most likely to bite code that keeps its own CookieJar around for persistence (e.g. http.cookiejar.LWPCookieJar/MozillaCookieJar for saving to disk) and passes it to a Client, expecting the same independent-copy behavior the other three input types (dict, list, Cookies) already provide. The inconsistency — 3 of 4 branches copy, 1 doesn't, with no comment explaining a deliberate difference — reads like an oversight rather than intent.

Happy to put together a PR (fresh CookieJar() + copy loop, matching the Cookies branch's own pattern) if this is confirmed as worth fixing.

[amasen02]

This is actually intentional and follows standard Python HTTP networking conventions (such as urllib.request.HTTPCookieProcessor(cookiejar)).

Why CookieJar is aliased rather than cloned

Passing an explicit http.cookiejar.CookieJar instance (or subclass) is the primary mechanism in Python for stateful persistence and custom policy:

1. Persistent Jars (MozillaCookieJar / LWPCookieJar):
   When users pass a file-backed jar:

   from http.cookiejar import MozillaCookieJar
   import httpx
   
   jar = MozillaCookieJar("cookies.txt")
   with httpx.Client(cookies=jar) as client:
       client.get("https://example.com/login")
   jar.save()  # <--- Expects cookies extracted during the session to be present

   If httpx.Cookies instantiated a fresh CookieJar() and copied cookies over, it would instantiate a generic http.cookiejar.CookieJar(). Any cookies received in server responses (Set-Cookie) would be written to the internal replica, completely bypassing the caller's MozillaCookieJar, rendering jar.save() empty and breaking persistence.

2. Custom CookiePolicy:
   CookieJar instances can be configured with custom policies (e.g., DefaultCookiePolicy(rfc2965=True, hide_cookie2=True) or domain/path restrictions). Constructing a new CookieJar() would drop the custom policy attached to the caller's jar.

3. Subclass Compatibility:
   CookieJar is often subclassed for thread-safe storage, in-memory LRU caching, or database backends. Copying into CookieJar() would strip the subclass implementation.

Why dict, list, and Cookies are copied

• dict / list are plain data structures without cookie management methods (extract_cookies, set_cookie_if_ok, etc.), so httpx must create an underlying CookieJar() to manage them.
• Cookies is httpx's high-level wrapper. Constructing Cookies(existing_cookies) or client.cookies.copy() is the explicit API provided when a user wants an isolated duplicate of an existing cookie set.

How to get an isolated copy of a CookieJar

If you have an existing CookieJar and want the client to operate on an independent copy without mutating the original, you can pass a shallow copy:

import copy
import httpx

isolated_client = httpx.Client(cookies=copy.copy(jar))

Or wrap it in httpx.Cookies:

isolated_client = httpx.Client(cookies=httpx.Cookies(jar).copy())

Aliasing raw CookieJar instances is what enables external persistence and policy delegation, mirroring urllib.request.HTTPCookieProcessor.

[tritsystem]

You're right, and this should be retracted — thank you for the thorough, correct pushback.

I independently re-verified the mechanism before replying, not just taking the argument on faith. httpx.Cookies.set(), extract_cookies(), and set_cookie_header() (httpx/_models.py) all operate through self.jar's own polymorphic http.cookiejar.CookieJar API — self.jar.set_cookie(...), self.jar.extract_cookies(...), self.jar.add_cookie_header(...) — never by reaching into internals. That means if Cookies.__init__ copied a raw CookieJar into a fresh internal one (the "fix" I proposed), every cookie extracted from a Set-Cookie response during the session would land in that internal copy — and the caller's own MozillaCookieJar/LWPCookieJar would never see them, silently breaking jar.save() for exactly the persistence workflow the aliasing exists to support. I also checked urllib.request.HTTPCookieProcessor.__init__ directly against the installed stdlib: self.cookiejar = cookiejar — the same alias-not-copy pattern, confirming this isn't an httpx-specific choice but the established Python convention for this exact case.

So the asymmetry isn't an oversight: dict/list have no cookie-management methods at all, so httpx has no choice but to build an internal jar to call set_cookie() on. Cookies is httpx's own wrapper with an explicit .copy() escape hatch already provided for exactly the "I want an isolated copy" case. A raw CookieJar (or subclass) is aliased on purpose, because copying it would strip the persistence/custom-policy/subclass behavior that's the entire reason someone passes one in.

Retracting the "this is a bug" framing and the proposed fix. Real, working alternative for anyone who does want an isolated copy: httpx.Client(cookies=copy.copy(jar)) or httpx.Client(cookies=httpx.Cookies(jar).copy()), exactly as you described. Appreciate you taking the time to lay out the actual mechanism rather than just asserting it — that's what made this checkable.