Skip to content

Cookies

Use cookies= for values you want to send with one request. Enable a cookie jar when the server should maintain a session across requests. Cookie storage is disabled by default. These options also work with the blocking client.

Sending cookies

The cookies argument accepts a dictionary of strings or a raw Cookie header value such as "session=abc123; lang=en".

import asyncio
from wreq import Client


async def main():
    async with Client() as client:
        async with client.get(
            "https://httpbin.org/cookies",
            cookies={"session": "abc123", "lang": "en"},
        ) as response:
            print(await response.json())


asyncio.run(main())

Passing cookies= does not add those values to a jar. If a jar is enabled, an explicit Cookie header takes precedence over the jar's outgoing cookies; the server's response cookies can still be stored.

Reading response cookies

response.cookies contains the cookies from that response's Set-Cookie headers. It does not list the client's stored cookies or cookies from earlier responses in a redirect chain.

import asyncio
from wreq import Client


async def main():
    async with Client() as client:
        async with client.get(
            "https://httpbin.org/cookies/set?session=abc123"
        ) as response:
            for cookie in response.cookies:
                print(cookie.name, cookie.value, cookie.domain, cookie.path)
            await response.bytes()


asyncio.run(main())

This endpoint returns a redirect with a Set-Cookie header. The example reads that response directly; wreq does not follow redirects by default.

Keeping a session

cookie_store=True creates a jar for the client. Cookies received from the server are stored and sent on later requests when their domain, path, expiry, and secure attributes allow it.

import asyncio
from wreq import Client


async def main():
    async with Client(cookie_store=True) as client:
        async with client.get(
            "https://httpbin.org/cookies/set?token=abc"
        ) as response:
            await response.bytes()

        async with client.get("https://httpbin.org/cookies") as response:
            print(await response.json())


asyncio.run(main())

Access the store through client.cookie_jar. It is None when cookie handling is disabled.

Supplying a jar

Create a Jar to load cookies before the first request or share stored cookies between clients. The jar is safe to share across threads and tasks.

import asyncio
from wreq import Client, Cookie, Jar


async def main():
    jar = Jar()
    jar.add(
        Cookie("session", "abc123", domain="httpbin.org", path="/"),
        "https://httpbin.org/",
    )

    async with Client(cookie_provider=jar) as client:
        async with client.get("https://httpbin.org/cookies") as response:
            print(await response.json())

        for cookie in client.cookie_jar.get_all():
            print(cookie.name, cookie.value)


asyncio.run(main())

client.cookie_jar shares the supplied jar's storage. If both cookie_provider and cookie_store=True are set, the supplied jar is used. A request can also use cookie_provider=jar to select a store for that request.

Managing stored cookies

Jar.add accepts a Cookie or a raw Set-Cookie value. The URL is the cookie's origin and is used to validate its domain and determine its default path.

from wreq import Cookie, Jar

jar = Jar()
url = "https://example.com/"
jar.add(Cookie("session", "abc123", domain="example.com", path="/"), url)
jar.add("language=en; Path=/; Secure", url)

cookie = jar.get("session", url)
if cookie is not None:
    print(cookie.name, cookie.value)

jar.add(Cookie("session", "new-value", domain="example.com", path="/"), url)

for cookie in jar.get_all():
    print(cookie.name, cookie.value, cookie.domain, cookie.path)

jar.remove("session", url)
jar.clear()

Adding a cookie with the same name, domain, path, and host-only scope replaces the stored value. get and remove use an exact host and path lookup: a cookie stored at / should be looked up with https://example.com/, even if it is also sent on requests to /account. A subdomain URL does not look up a cookie stored under its parent domain.

wreq formats outgoing cookie headers for the negotiated HTTP version; you can use the same jar with HTTP/1.1 and HTTP/2.