Soup.Cookie¶

Fields¶

None

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¶

Implements HTTP cookies, as described by RFC 6265.

To have a [class`Session`] handle cookies for your appliction automatically, use a [class`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.

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 [method`Cookie`.set_secure] and [method`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 [method`Cookie`.set_expires].)

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

classmethod parse(header, origin)¶

Parameters:

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

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.

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

applies_to_uri(uri)¶

Parameters:: uri (GLib.Uri) – a GLib.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.)

copy()¶

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

Copies self.

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.

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

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.

free()¶: Frees self.

get_domain()¶

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

Gets self's domain.

get_expires()¶

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

Gets self's expiration time.

get_http_only()¶

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

Gets self's HttpOnly attribute.

get_name()¶

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

Gets self's name.

get_path()¶

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

Gets self's path.

get_same_site_policy()¶

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

Returns the same-site policy for this cookie.

get_secure()¶

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

Gets self's secure attribute.

get_value()¶

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

Gets self's value.

set_domain(domain)¶

Parameters:: domain (str) – the new domain

Sets self's domain to domain.

set_expires(expires)¶

Parameters:: expires (GLib.DateTime) – 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 [method`Cookie`.set_max_age].)

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.

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 [method`Cookie`.set_expires].

set_name(name)¶

Parameters:: name (str) – the new name

Sets self's name to name.

set_path(path)¶

Parameters:: path (str) – the new path

Sets self's path to path.

set_same_site_policy(policy)¶

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

When used in conjunction with [method`CookieJar`.get_cookie_list_with_same_site_info] this sets the policy of when this cookie should be exposed.

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.

set_value(value)¶

Parameters:: value (str) – the new value

Sets self's value to value.

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 [class`Session`] to a server).

to_set_cookie_header()¶

Returns:: the header
Return type:: str

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

i.e. for sending a cookie from a [class`Server`] to a client.