Soup.CookieJar¶

Subclasses:	`Soup.CookieJarDB`, `Soup.CookieJarText`

Methods¶

Inherited:	GObject.Object (37), Soup.SessionFeature (5)
Structs:	GObject.ObjectClass (5)

class	`new` ()
	`add_cookie` (cookie)
	`add_cookie_full` (cookie, uri, first_party)
	`add_cookie_with_first_party` (first_party, cookie)
	`all_cookies` ()
	`delete_cookie` (cookie)
	`get_accept_policy` ()
	`get_cookie_list` (uri, for_http)
	`get_cookie_list_with_same_site_info` (uri, top_level, site_for_cookies, for_http, is_safe_method, is_top_level_navigation)
	`get_cookies` (uri, for_http)
	`is_persistent` ()
	`save` ()
	`set_accept_policy` (policy)
	`set_cookie` (uri, cookie)
	`set_cookie_with_first_party` (uri, first_party, cookie)

Virtual Methods¶

Inherited:	GObject.Object (7), Soup.SessionFeature (8)

	`do_changed` (old_cookie, new_cookie)
	`do_is_persistent` ()
	`do_save` ()

Properties¶

Name	Type	Flags	Short Description
`accept-policy`	`Soup.CookieJarAcceptPolicy`	r/w	The policy the jar should follow to accept or reject cookies
`read-only`	`bool`	r/w/co	Whether or not the cookie jar is read-only

Signals¶

Inherited:	GObject.Object (1)

Name	Short Description
`changed`	Emitted when jar changes.

Fields¶

Inherited:	GObject.Object (1)

Name	Type	Access	Description
parent	`GObject.Object`	r

Class Details¶

class Soup.CookieJar(**kwargs)¶

Bases:	`GObject.Object`, `Soup.SessionFeature`
Abstract:	No
Structure:	`Soup.CookieJarClass`

classmethod new()¶

Returns:	a new `Soup.CookieJar`
Return type:	`Soup.CookieJar`

Creates a new Soup.CookieJar. The base Soup.CookieJar class does not support persistent storage of cookies; use a subclass for that.

New in version 2.24.

add_cookie(cookie)¶

Parameters:	cookie (`Soup.Cookie`) – a `Soup.Cookie`

Adds cookie to self, emitting the ‘changed’ signal if we are modifying an existing cookie or adding a valid new cookie (‘valid’ means that the cookie’s expire date is not in the past).

cookie will be ‘stolen’ by the jar, so don’t free it afterwards.

New in version 2.26.

add_cookie_full(cookie, uri, first_party)¶

Parameters:	cookie (`Soup.Cookie`) – a `Soup.Cookie` uri (`Soup.URI` or `None`) – the URI setting the cookie first_party (`Soup.URI` or `None`) – the URI for the main document

Adds cookie to self, emitting the ‘changed’ signal if we are modifying an existing cookie or adding a valid new cookie (‘valid’ means that the cookie’s expire date is not in the past).

first_party will be used to reject cookies coming from third party resources in case such a security policy is set in the self.

uri will be used to reject setting or overwriting secure cookies from insecure origins. None is treated as secure.

cookie will be ‘stolen’ by the jar, so don’t free it afterwards.

New in version 2.68.

add_cookie_with_first_party(first_party, cookie)¶

Parameters:	first_party (`Soup.URI`) – the URI for the main document cookie (`Soup.Cookie`) – a `Soup.Cookie`

Adds cookie to self, emitting the ‘changed’ signal if we are modifying an existing cookie or adding a valid new cookie (‘valid’ means that the cookie’s expire date is not in the past).

first_party will be used to reject cookies coming from third party resources in case such a security policy is set in the self.

cookie will be ‘stolen’ by the jar, so don’t free it afterwards.

For secure cookies to work properly you may want to use Soup.CookieJar.add_cookie_full().

New in version 2.40.

all_cookies()¶

Returns:	a `GLib.SList` with all the cookies in the self.
Return type:	[`Soup.Cookie`]

Constructs a GLib.SList with every cookie inside the self. The cookies in the list are a copy of the original, so you have to free them when you are done with them.

New in version 2.26.

delete_cookie(cookie)¶

Parameters:	cookie (`Soup.Cookie`) – a `Soup.Cookie`

Deletes cookie from self, emitting the ‘changed’ signal.

New in version 2.26.

get_accept_policy()¶

Returns:	the `Soup.CookieJarAcceptPolicy` set in the self
Return type:	`Soup.CookieJarAcceptPolicy`

Gets self’s Soup.CookieJarAcceptPolicy

New in version 2.30.

get_cookie_list(uri, for_http)¶

Parameters:	uri (`Soup.URI`) – a `Soup.URI` for_http (`bool`) – whether or not the return value is being passed directly to an HTTP operation
Returns:	a `GLib.SList` with the cookies in the self that would be sent with a request to uri.
Return type:	[`Soup.Cookie`]

Retrieves the list of cookies that would be sent with a request to uri as a GLib.SList of Soup.Cookie objects.

If for_http is True, the return value will include cookies marked “HttpOnly” (that is, cookies that the server wishes to keep hidden from client-side scripting operations such as the JavaScript document.cookies property). Since Soup.CookieJar sets the Cookie header itself when making the actual HTTP request, you should almost certainly be setting for_http to False if you are calling this.

New in version 2.40.

get_cookie_list_with_same_site_info(uri, top_level, site_for_cookies, for_http, is_safe_method, is_top_level_navigation)¶

Parameters:	uri (`Soup.URI`) – a `Soup.URI` top_level (`Soup.URI` or `None`) – a `Soup.URI` for the top level document site_for_cookies (`Soup.URI` or `None`) – a `Soup.URI` indicating the origin to get cookies for for_http (`bool`) – whether or not the return value is being passed directly to an HTTP operation is_safe_method (`bool`) – if the HTTP method is safe, as defined by RFC 7231, ignored when for_http is `False` is_top_level_navigation (`bool`) – whether or not the HTTP request is part of top level navigation
Returns:	a `GLib.SList` with the cookies in the self that would be sent with a request to uri.
Return type:	[`Soup.Cookie`]

This is an extended version of Soup.CookieJar.get_cookie_list() that provides more information required to use SameSite cookies. See the SameSite cookies spec for more detailed information.

New in version 2.70.

get_cookies(uri, for_http)¶

Parameters:	uri (`Soup.URI`) – a `Soup.URI` for_http (`bool`) – whether or not the return value is being passed directly to an HTTP operation
Returns:	the cookies, in string form, or `None` if there are no cookies for uri.
Return type:	`str` or `None`

Retrieves (in Cookie-header form) the list of cookies that would be sent with a request to uri.

If for_http is True, the return value will include cookies marked “HttpOnly” (that is, cookies that the server wishes to keep hidden from client-side scripting operations such as the JavaScript document.cookies property). Since Soup.CookieJar sets the Cookie header itself when making the actual HTTP request, you should almost certainly be setting for_http to False if you are calling this.

New in version 2.24.

is_persistent()¶

Returns:	`True` if self storage is persistent or `False` otherwise.
Return type:	`bool`

Gets whether self stores cookies persistenly.

New in version 2.40.

save()¶: This function exists for backward compatibility, but does not do anything any more; cookie jars are saved automatically when they are changed.

New in version 2.24.

Deprecated since version ???: This is a no-op.

set_accept_policy(policy)¶

Parameters:	policy (`Soup.CookieJarAcceptPolicy`) – a `Soup.CookieJarAcceptPolicy`

Sets policy as the cookie acceptance policy for self.

New in version 2.30.

set_cookie(uri, cookie)¶

Parameters:	uri (`Soup.URI`) – the URI setting the cookie cookie (`str`) – the stringified cookie to set

Adds cookie to self, exactly as though it had appeared in a Set-Cookie header returned from a request to uri.

Keep in mind that if the Soup.CookieJarAcceptPolicy set is either Soup.CookieJarAcceptPolicy.NO_THIRD_PARTY or Soup.CookieJarAcceptPolicy.GRANDFATHERED_THIRD_PARTY you’ll need to use Soup.CookieJar.set_cookie_with_first_party(), otherwise the jar will have no way of knowing if the cookie is being set by a third party or not.

New in version 2.24.

set_cookie_with_first_party(uri, first_party, cookie)¶

Parameters:	uri (`Soup.URI`) – the URI setting the cookie first_party (`Soup.URI`) – the URI for the main document cookie (`str`) – the stringified cookie to set

Adds cookie to self, exactly as though it had appeared in a Set-Cookie header returned from a request to uri. first_party will be used to reject cookies coming from third party resources in case such a security policy is set in the self.

New in version 2.30.

do_changed(old_cookie, new_cookie) virtual¶

Parameters:	old_cookie (`Soup.Cookie`) – new_cookie (`Soup.Cookie`) –

do_is_persistent() virtual¶

Returns:	`True` if jar storage is persistent or `False` otherwise.
Return type:	`bool`

Gets whether jar stores cookies persistenly.

New in version 2.40.

do_save() virtual¶: This function exists for backward compatibility, but does not do anything any more; cookie jars are saved automatically when they are changed.

New in version 2.24.

Deprecated since version ???: This is a no-op.

Signal Details¶

Soup.CookieJar.signals.changed(cookie_jar, old_cookie, new_cookie)¶

Signal Name:	`changed`
Flags:	`RUN_FIRST`
Parameters:	cookie_jar (`Soup.CookieJar`) – The object which received the signal old_cookie (`Soup.Cookie`) – the old `Soup.Cookie` value new_cookie (`Soup.Cookie`) – the new `Soup.Cookie` value

Emitted when jar changes. If a cookie has been added, new_cookie will contain the newly-added cookie and old_cookie will be None. If a cookie has been deleted, old_cookie will contain the to-be-deleted cookie and new_cookie will be None. If a cookie has been changed, old_cookie will contain its old value, and new_cookie its new value.

Property Details¶

Soup.CookieJar.props.accept_policy¶

Name:	`accept-policy`
Type:	`Soup.CookieJarAcceptPolicy`
Default Value:	`Soup.CookieJarAcceptPolicy.ALWAYS`
Flags:	`READABLE`, `WRITABLE`

The policy the jar should follow to accept or reject cookies

New in version 2.30.

Soup.CookieJar.props.read_only¶

Name:	`read-only`
Type:	`bool`
Default Value:	`False`
Flags:	`READABLE`, `WRITABLE`, `CONSTRUCT_ONLY`

Whether or not the cookie jar is read-only