Cookie

class Cookie(**kwargs)

Implements HTTP cookies, as described by RFC 6265.

To have a Session handle cookies for your appliction automatically, use a CookieJar.

name and value will be set for all cookies. If the cookie is generated from a string that appears to have no name, then name will be the empty string.

domain and path give the host or domain, and path within that host/domain, to restrict this cookie to. If domain starts with “.”, that indicates a domain (which matches the string after the “.”, or any hostname that has domain as a suffix). Otherwise, it is a hostname and must match exactly.

expires will be non-None if the cookie uses either the original “expires” attribute, or the newer “max-age” attribute. If expires is None, it indicates that neither “expires” nor “max-age” was specified, and the cookie expires at the end of the session.

If http_only is set, the cookie should not be exposed to untrusted code (eg, javascript), so as to minimize the danger posed by cross-site scripting attacks.

Constructors

class Cookie

classmethod new(name: str, value: str, domain: str, path: str, max_age: int) → Cookie

Creates a new Cookie with the given attributes.

Use set_secure and set_http_only if you need to set those attributes on the returned cookie.

If domain starts with “.”, that indicates a domain (which matches the string after the “.”, or any hostname that has domain as a suffix). Otherwise, it is a hostname and must match exactly.

max_age is used to set the “expires” attribute on the cookie; pass

-1 to not include the attribute (indicating that the cookie expires with the current session), 0 for an already-expired cookie, or a lifetime in seconds. You can use the constants COOKIE_MAX_AGE_ONE_HOUR, COOKIE_MAX_AGE_ONE_DAY, COOKIE_MAX_AGE_ONE_WEEK and COOKIE_MAX_AGE_ONE_YEAR (or multiples thereof) to calculate this value. (If you really care about setting the exact time that the cookie will expire, use set_expires.)

As of version 3.4.0 the default value of a cookie’s same-site-policy is LAX.

Parameters:

• name – cookie name

• value – cookie value

• domain – cookie domain or hostname

• path – cookie path, or None

• max_age – max age of the cookie, or -1 for a session cookie

Methods

class Cookie

applies_to_uri(uri: Uri) → bool

Tests if cookie should be sent to uri.

(At the moment, this does not check that cookie’s domain matches uri, because it assumes that the caller has already done that. But don’t rely on that; it may change in the future.)

Parameters:

uri – a Uri

domain_matches(host: str) → bool

Checks if the cookie’s domain and host match.

The domains match if cookie should be sent when making a request to host, or that cookie should be accepted when receiving a response from host.

Parameters:

host – a URI

equal(cookie2: Cookie) → bool

Tests if cookie1 and cookie2 are equal.

Note that currently, this does not check that the cookie domains match. This may change in the future.

Parameters:

cookie2 – a Cookie

free() → None

Frees cookie.

get_domain() → str

Gets cookie’s domain.

get_expires() → DateTime | None

Gets cookie’s expiration time.

get_http_only() → bool

Gets cookie’s HttpOnly attribute.

get_name() → str

Gets cookie’s name.

get_path() → str

Gets cookie’s path.

get_same_site_policy() → SameSitePolicy

Returns the same-site policy for this cookie.

get_secure() → bool

Gets cookie’s secure attribute.

get_value() → str

Gets cookie’s value.

parse(header: str, origin: Uri | None = None) → Cookie | None

Parses header and returns a Cookie.

If header contains multiple cookies, only the first one will be parsed.

If header does not have “path” or “domain” attributes, they will be defaulted from origin. If origin is None, path will default to “/”, but domain will be left as None. Note that this is not a valid state for a Cookie, and you will need to fill in some appropriate string for the domain if you want to actually make use of the cookie.

As of version 3.4.0 the default value of a cookie’s same-site-policy is LAX.

Parameters:

• header – a cookie string (eg, the value of a Set-Cookie header)

• origin – origin of the cookie

set_domain(domain: str) → None

Sets cookie’s domain to domain.

Parameters:

domain – the new domain

set_expires(expires: DateTime) → None

Sets cookie’s expiration time to expires.

If expires is None, cookie will be a session cookie and will expire at the end of the client’s session.

(This sets the same property as set_max_age.)

Parameters:

expires – the new expiration time, or None

set_http_only(http_only: bool) → None

Sets cookie’s HttpOnly attribute to http_only.

If True, cookie will be marked as “http only”, meaning it should not be exposed to web page scripts or other untrusted code.

Parameters:

http_only – the new value for the HttpOnly attribute

set_max_age(max_age: int) → None

Sets cookie’s max age to max_age.

If max_age is -1, the cookie is a session cookie, and will expire at the end of the client’s session. Otherwise, it is the number of seconds until the cookie expires. You can use the constants COOKIE_MAX_AGE_ONE_HOUR, COOKIE_MAX_AGE_ONE_DAY, COOKIE_MAX_AGE_ONE_WEEK and COOKIE_MAX_AGE_ONE_YEAR (or multiples thereof) to calculate this value. (A value of 0 indicates that the cookie should be considered already-expired.)

This sets the same property as set_expires.

Parameters:

max_age – the new max age

set_name(name: str) → None

Sets cookie’s name to name.

Parameters:

name – the new name

set_path(path: str) → None

Sets cookie’s path to path.

Parameters:

path – the new path

set_same_site_policy(policy: SameSitePolicy) → None

When used in conjunction with get_cookie_list_with_same_site_info this sets the policy of when this cookie should be exposed.

Parameters:

policy – a SameSitePolicy

set_secure(secure: bool) → None

Sets cookie’s secure attribute to secure.

If True, cookie will only be transmitted from the client to the server over secure (https) connections.

Parameters:

secure – the new value for the secure attribute

set_value(value: str) → None

Sets cookie’s value to value.

Parameters:

value – the new value

to_cookie_header() → str

Serializes cookie in the format used by the Cookie header (ie, for returning a cookie from a Session to a server).

to_set_cookie_header() → str

Serializes cookie in the format used by the Set-Cookie header.

i.e. for sending a cookie from a Server to a client.