CookieJar

class CookieJar(**properties: Any)

Superclasses: Object

Subclasses: CookieJarDB, CookieJarText

Implemented Interfaces: SessionFeature

Automatic cookie handling for SoupSession.

A CookieJar stores Cookie’s and arrange for them to be sent with the appropriate Message’s. CookieJar implements SessionFeature, so you can add a cookie jar to a session with add_feature or add_feature_by_type.

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

Constructors

class CookieJar

classmethod new() → CookieJar

Creates a new CookieJar.

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

Methods

class CookieJar

add_cookie(cookie: Cookie) → None

Adds cookie to jar.

Emits 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.

Parameters:

cookie – a Cookie

add_cookie_full(cookie: Cookie, uri: Uri | None = None, first_party: Uri | None = None) → None

Adds cookie to jar.

Emits 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 jar.

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.

Parameters:

• cookie – a Cookie

• uri – the URI setting the cookie

• first_party – the URI for the main document

add_cookie_with_first_party(first_party: Uri, cookie: Cookie) → None

Adds cookie to jar.

Emits 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 jar.

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

For secure cookies to work properly you may want to use add_cookie_full.

Parameters:

• first_party – the URI for the main document

• cookie – a Cookie

all_cookies() → list[Cookie]

Constructs a List with every cookie inside the jar.

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: Cookie) → None

Deletes cookie from jar.

Emits the changed signal.

Parameters:

cookie – a Cookie

get_accept_policy() → CookieJarAcceptPolicy

Gets jar’s CookieJarAcceptPolicy.

get_cookie_list(uri: Uri, for_http: bool) → list[Cookie]

Retrieves the list of cookies that would be sent with a request to uri as a List of 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 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.

Parameters:

• uri – a Uri

• for_http – whether or not the return value is being passed directly to an HTTP operation

get_cookie_list_with_same_site_info(uri: Uri, top_level: Uri | None, site_for_cookies: Uri | None, for_http: bool, is_safe_method: bool, is_top_level_navigation: bool) → list[Cookie]

This is an extended version of get_cookie_list that provides more information required to use SameSite cookies.

See the [SameSite cookies spec](https://tools.ietf.org/html/draft-ietf-httpbis-cookie-same-site-00) for more detailed information.

Parameters:

• uri – a Uri

• top_level – a Uri for the top level document

• site_for_cookies – a Uri indicating the origin to get cookies for

• for_http – whether or not the return value is being passed directly to an HTTP operation

• is_safe_method – if the HTTP method is safe, as defined by RFC 7231, ignored when for_http is False

• is_top_level_navigation – whether or not the HTTP request is part of top level navigation

get_cookies(uri: Uri, for_http: bool) → str | 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 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.

Parameters:

• uri – a Uri

• for_http – whether or not the return value is being passed directly to an HTTP operation

is_persistent() → bool

Gets whether jar stores cookies persistenly.

set_accept_policy(policy: CookieJarAcceptPolicy) → None

Sets policy as the cookie acceptance policy for jar.

Parameters:

policy – a CookieJarAcceptPolicy

set_cookie(uri: Uri, cookie: str) → None

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

Keep in mind that if the CookieJarAcceptPolicy set is either NO_THIRD_PARTY or GRANDFATHERED_THIRD_PARTY you’ll need to use 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.

Parameters:

• uri – the URI setting the cookie

• cookie – the stringified cookie to set

set_cookie_with_first_party(uri: Uri, first_party: Uri, cookie: str) → None

Adds cookie to jar, 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 jar.

Parameters:

• uri – the URI setting the cookie

• first_party – the URI for the main document

• cookie – the stringified cookie to set

Properties

class CookieJar

props.accept_policy: CookieJarAcceptPolicy

The policy the jar should follow to accept or reject cookies.

props.read_only: bool

Whether or not the cookie jar is read-only.

Signals

class CookieJar.signals

changed(old_cookie: Cookie, new_cookie: Cookie) → None

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.

Parameters:

• old_cookie – the old Cookie value

• new_cookie – the new Cookie value

Virtual Methods

class CookieJar

do_changed(old_cookie: Cookie, new_cookie: Cookie) → None

Parameters:

• old_cookie

• new_cookie

do_is_persistent() → bool

Gets whether jar stores cookies persistenly.

do_save() → None

Fields

class CookieJar

parent_instance