Soup.CookieJar¶

Subclasses:: Soup.CookieJarDB, Soup.CookieJarText

Methods¶

Inherited:: GObject.Object (37)
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` ()
	`set_accept_policy` (policy)
	`set_cookie` (uri, cookie)
	`set_cookie_with_first_party` (uri, first_party, cookie)

Virtual Methods¶

Inherited:: GObject.Object (7)

	`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_instance	`GObject.Object`	r

Class Details¶

class Soup.CookieJar(**kwargs)¶

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

Automatic cookie handling for Soup.Session.

A Soup.CookieJar stores [struct`Cookie`]s and arrange for them to be sent with the appropriate [class`Message`]s. Soup.CookieJar implements [iface`SessionFeature`], so you can add a cookie jar to a session with [method`Session`.add_feature] or [method`Session`.add_feature_by_type].

Note that the base Soup.CookieJar class does not support any form of long-term cookie persistence.

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.

add_cookie(cookie)¶

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

Adds cookie to self.

Emits the [signal`CookieJar`:py:func:::changed<Soup.CookieJar.signals.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.

add_cookie_full(cookie, uri, first_party)¶

Parameters:

cookie (Soup.Cookie) – a Soup.Cookie
uri (GLib.Uri or None) – the URI setting the cookie
first_party (GLib.Uri or None) – the URI for the main document

Adds cookie to self.

Emits the [signal`CookieJar`:py:func:::changed<Soup.CookieJar.signals.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.

add_cookie_with_first_party(first_party, cookie)¶

Parameters:

first_party (GLib.Uri) – the URI for the main document
cookie (Soup.Cookie) – a Soup.Cookie

Adds cookie to self.

Emits the [signal`CookieJar`:py:func:::changed<Soup.CookieJar.signals.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 [method`CookieJar`.add_cookie_full].

all_cookies()¶

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

Constructs a [struct`GLib`.List] 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.

delete_cookie(cookie)¶

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

Deletes cookie from self.

Emits the [signal`CookieJar`:py:func:::changed<Soup.CookieJar.signals.changed>] signal.

get_accept_policy()¶

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

Gets self's [enum`CookieJarAcceptPolicy`].

get_cookie_list(uri, for_http)¶

Parameters:

uri (GLib.Uri) – a GLib.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 [struct`GLib`.List] 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.

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

Parameters:

uri (GLib.Uri) – a GLib.Uri
top_level (GLib.Uri or None) – a GLib.Uri for the top level document
site_for_cookies (GLib.Uri or None) – a GLib.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 [method`CookieJar`.get_cookie_list] that provides more information required to use SameSite cookies.

See the SameSite cookies spec for more detailed information.

get_cookies(uri, for_http)¶

Parameters:

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

is_persistent()¶

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

Gets whether self stores cookies persistenly.

set_accept_policy(policy)¶

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

Sets policy as the cookie acceptance policy for self.

set_cookie(uri, cookie)¶

Parameters:

uri (GLib.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 [enum`CookieJarAcceptPolicy`] set is either Soup.CookieJarAcceptPolicy.NO_THIRD_PARTY or Soup.CookieJarAcceptPolicy.GRANDFATHERED_THIRD_PARTY you’ll need to use [method`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.

set_cookie_with_first_party(uri, first_party, cookie)¶

Parameters:

uri (GLib.Uri) – the URI setting the cookie
first_party (GLib.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.

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.

do_save() virtual¶

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.

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.