http.cookies

import http.cookies

http lifts part of this module out to its own top level; each name below is shown with the path that reaches it. Anything still spelled http.cookies.* needs import http.cookies.

Cookies, both halves of them: Cookie is one cookie with its attributes, CookieJar is a store that applies the domain, path and expiry rules when deciding what to send.

The parsing and formatting functions handle the two header formats, which are not symmetric: a request sends many cookies in one Cookie header, a response sets one per Set-Cookie.

Functions

is_valid_value()

http.cookies.is_valid_value(value) -> bool

Whether value can be sent as a cookie value without quoting.

Parameters

• value (string)

Returns bool

parse_cookie_header()

http.cookies.parse_cookie_header(header) -> dict

Parses a request’s Cookie header into a dictionary of name to value.

A cookie header is a flat a=1; b=2 list with no attributes - everything the server set is gone by the time it comes back, which is why a server that needs to know a cookie’s path or expiry has to have stored that itself.

Malformed pairs are skipped rather than raising: a browser will cheerfully send whatever junk any script on the page stored, and refusing the whole request over one bad pair loses the good ones too.

Parameters

• header (string)

Returns dict

parse_set_cookie()

http.cookies.parse_set_cookie(header)

Parses one Set-Cookie field value into a Cookie.

Parameters

• header (string)

Returns — ?Cookie: nil when the field carries no usable name/value pair

format_cookie_header()

http.cookies.format_cookie_header(cookies: dict) -> string

Renders a dictionary of name to value as a request Cookie header value.

Parameters

• cookies (dict)

Returns string

Classes

Cookie

class http.Cookie

A single cookie, in either direction: the name/value pair a client sends back in a Cookie header, or the full attribute set a server sends in Set-Cookie.

The attributes follow RFC 6265bis, including SameSite and the __Host-/__Secure- name prefixes, whose rules are enforced by to_header() rather than left to the caller to remember.

• printable — has a @to_string(), so echo and print() show something useful

Fields

Constructor

http.Cookie(name: string, value: string, attributes: ?dict)

Parameters

• name (string)
• value (string)
• attributes (?dict) — any of domain, path, expires, max_age, secure, http_only, same_site, partitioned

Raises ProtocolError if the name is not a token, or the value contains a character that cannot appear in a cookie

Cookie.to_header()

http.Cookie.to_header() -> string

Renders the cookie as a Set-Cookie field value.

The name prefixes defined in RFC 6265bis §4.1.3 are honoured here: a __Secure- cookie is forced Secure, and a __Host- cookie is forced Secure, pinned to Path=/, and stripped of any Domain. Browsers reject cookies that carry a prefix without meeting its conditions, so fixing them up beats silently emitting a cookie that never gets stored.

SameSite=None likewise implies Secure, without which the cookie is dropped.

Returns string

Cookie.is_expired()

http.Cookie.is_expired(now) -> bool

Whether the cookie’s own attributes say it has already expired, as of now (default: the current time). A session cookie - one with neither expires nor max_age - is never expired by this test.

Parameters

• now (?number)

Returns bool

Cookie.to_string()

http.Cookie.to_string()

CookieJar

class http.CookieJar

A client-side cookie store: keeps the cookies a server set, decides which of them a later request is entitled to see, and forgets the ones that have expired.

The matching rules are RFC 6265 §5.4’s: domain-match (an exact host match, or a suffix match when the cookie carried a Domain), path-match, and the Secure flag against the request’s scheme. Getting this wrong in either direction is a real problem - too strict and sessions break, too loose and a cookie leaks to a host that never should have seen it.

Constructor

http.CookieJar()

CookieJar.store()

http.CookieJar.store(cookie, host: string, request_path: ?string)

Records a cookie as having been set by host.

A cookie whose Domain is not a suffix of host is rejected outright - that is a server trying to set a cookie for a domain it does not control.

Parameters

• cookie (Cookie)
• host (string) — the host of the response that set it
• request_path (?string) — used to derive a default path

Returns — bool: whether the cookie was accepted

CookieJar.cookies_for()

http.CookieJar.cookies_for(host: string, path: string, secure: ?bool) -> dict

The cookies that should be sent with a request to host and path, as a dictionary of name to value.

Parameters

• host (string)
• path (string)
• secure (?bool) — whether the request is over HTTPS

Returns dict

CookieJar.all()

http.CookieJar.all() -> list

Every cookie currently held, expired ones included.

Returns list

CookieJar.clear()

http.CookieJar.clear()

Drops every stored cookie.

CookieJar.length()

http.CookieJar.length() -> number

How many cookies are held.

Returns number

2026, Richard Ore and Zuri contributors