Soup.Cookie¶

Fields¶

Name	Type	Access	Description
domain	`str`	r/w	the “domain” attribute, or else the hostname that the cookie came from.
expires	`Soup.Date`	r/w	the cookie expiration time, or `None` for a session cookie
http_only	`bool`	r/w	`True` if the cookie should not be exposed to scripts
name	`str`	r/w	the cookie name
path	`str`	r/w	the “path” attribute, or `None`
secure	`bool`	r/w	`True` if the cookie should only be tranferred over SSL
value	`str`	r/w	the cookie value

Methods¶

class	`new` (name, value, domain, path, max_age)
class	`parse` (header, origin)
	`applies_to_uri` (uri)
	`copy` ()
	`domain_matches` (host)
	`equal` (cookie2)
	`free` ()
	`get_domain` ()
	`get_expires` ()
	`get_http_only` ()
	`get_name` ()
	`get_path` ()
	`get_same_site_policy` ()
	`get_secure` ()
	`get_value` ()
	`set_domain` (domain)
	`set_expires` (expires)
	`set_http_only` (http_only)
	`set_max_age` (max_age)
	`set_name` (name)
	`set_path` (path)
	`set_same_site_policy` (policy)
	`set_secure` (secure)
	`set_value` (value)
	`to_cookie_header` ()
	`to_set_cookie_header` ()

Details¶

class Soup.Cookie¶

An HTTP cookie.

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.

New in version 2.24.

classmethod new(name, value, domain, path, max_age)¶

Parameters:

name (str) – cookie name
value (str) – cookie value
domain (str) – cookie domain or hostname
path (str) – cookie path, or None
max_age (int) – max age of the cookie, or -1 for a session cookie

Returns:

a new Soup.Cookie.

Return type:

Soup.Cookie

Creates a new Soup.Cookie with the given attributes. (Use Soup.Cookie.set_secure() and Soup.Cookie.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 Soup.COOKIE_MAX_AGE_ONE_HOUR, Soup.COOKIE_MAX_AGE_ONE_DAY, Soup.COOKIE_MAX_AGE_ONE_WEEK and Soup.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 Soup.Cookie.set_expires().)

New in version 2.24.

classmethod parse(header, origin)¶

Parameters:

header (str) – a cookie string (eg, the value of a Set-Cookie header)
origin (Soup.URI) – origin of the cookie, or None

Returns:

a new Soup.Cookie, or None if it could not be parsed, or contained an illegal “domain” attribute for a cookie originating from origin.

Return type:

Soup.Cookie or None

Parses header and returns a Soup.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 Soup.Cookie, and you will need to fill in some appropriate string for the domain if you want to actually make use of the cookie.

New in version 2.24.

applies_to_uri(uri)¶

Parameters:: uri (Soup.URI) – a Soup.URI
Returns:: True if self should be sent to uri, False if not
Return type:: bool

Tests if self should be sent to uri.

(At the moment, this does not check that self'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.)

New in version 2.24.

copy()¶

Returns:: a copy of self
Return type:: Soup.Cookie

Copies self.

New in version 2.24.

domain_matches(host)¶

Parameters:: host (str) – a URI
Returns:: True if the domains match, False otherwise
Return type:: bool

Checks if the self's domain and host match in the sense that self should be sent when making a request to host, or that self should be accepted when receiving a response from host.

New in version 2.30.

equal(cookie2)¶

Parameters:: cookie2 (Soup.Cookie) – a Soup.Cookie
Returns:: whether the cookies are equal.
Return type:: bool

Tests if self and cookie2 are equal.

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

New in version 2.24.

free()¶: Frees self

New in version 2.24.

get_domain()¶

Returns:: self's domain
Return type:: str

Gets self's domain

New in version 2.32.

get_expires()¶

Returns:: self's expiration time, which is owned by self and should not be modified or freed.
Return type:: Soup.Date or None

Gets self's expiration time.

New in version 2.32.

get_http_only()¶

Returns:: self's HttpOnly attribute
Return type:: bool

Gets self's HttpOnly attribute

New in version 2.32.

get_name()¶

Returns:: self's name
Return type:: str

Gets self's name

New in version 2.32.

get_path()¶

Returns:: self's path
Return type:: str

Gets self's path

New in version 2.32.

get_same_site_policy()¶

Returns:: a Soup.SameSitePolicy
Return type:: Soup.SameSitePolicy

New in version 2.70.

get_secure()¶

Returns:: self's secure attribute
Return type:: bool

Gets self's secure attribute

New in version 2.32.

get_value()¶

Returns:: self's value
Return type:: str

Gets self's value

New in version 2.32.

set_domain(domain)¶

Parameters:: domain (str) – the new domain

Sets self's domain to domain

New in version 2.24.

set_expires(expires)¶

Parameters:: expires (Soup.Date) – the new expiration time, or None

Sets self's expiration time to expires. If expires is None, self will be a session cookie and will expire at the end of the client’s session.

(This sets the same property as Soup.Cookie.set_max_age().)

New in version 2.24.

set_http_only(http_only)¶

Parameters:: http_only (bool) – the new value for the HttpOnly attribute

Sets self's HttpOnly attribute to http_only. If True, self will be marked as “http only”, meaning it should not be exposed to web page scripts or other untrusted code.

New in version 2.24.

set_max_age(max_age)¶

Parameters:: max_age (int) – the new max age

Sets self'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 Soup.COOKIE_MAX_AGE_ONE_HOUR, Soup.COOKIE_MAX_AGE_ONE_DAY, Soup.COOKIE_MAX_AGE_ONE_WEEK and Soup.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 Soup.Cookie.set_expires().)

New in version 2.24.

set_name(name)¶

Parameters:: name (str) – the new name

Sets self's name to name

New in version 2.24.

set_path(path)¶

Parameters:: path (str) – the new path

Sets self's path to path

New in version 2.24.

set_same_site_policy(policy)¶

Parameters:: policy (Soup.SameSitePolicy) – a Soup.SameSitePolicy

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

New in version 2.70.

set_secure(secure)¶

Parameters:: secure (bool) – the new value for the secure attribute

Sets self's secure attribute to secure. If True, self will only be transmitted from the client to the server over secure (https) connections.

New in version 2.24.

set_value(value)¶

Parameters:: value (str) – the new value

Sets self's value to value

New in version 2.24.

to_cookie_header()¶

Returns:: the header
Return type:: str

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

New in version 2.24.

to_set_cookie_header()¶

Returns:: the header
Return type:: str

Serializes self in the format used by the Set-Cookie header (ie, for sending a cookie from a Soup.Server to a client).

New in version 2.24.