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