:right-sidebar: True CookieJar =================================================================== .. currentmodule:: gi.repository.Soup .. class:: CookieJar(**properties: ~typing.Any) :no-contents-entry: Superclasses: :class:`~gi.repository.GObject.Object` Subclasses: :class:`~gi.repository.Soup.CookieJarDB`, :class:`~gi.repository.Soup.CookieJarText` Implemented Interfaces: :class:`~gi.repository.Soup.SessionFeature` Automatic cookie handling for SoupSession. A :obj:`~gi.repository.Soup.CookieJar` stores :obj:`~gi.repository.Soup.Cookie`\s and arrange for them to be sent with the appropriate :obj:`~gi.repository.Soup.Message`\s. :obj:`~gi.repository.Soup.CookieJar` implements :obj:`~gi.repository.Soup.SessionFeature`\, so you can add a cookie jar to a session with :obj:`~gi.repository.Session.add_feature` or :obj:`~gi.repository.Session.add_feature_by_type`\. Note that the base :obj:`~gi.repository.Soup.CookieJar` class does not support any form of long-term cookie persistence. Constructors ------------ .. rst-class:: interim-class .. class:: CookieJar :no-index: .. classmethod:: new() -> ~gi.repository.Soup.CookieJar Creates a new :obj:`~gi.repository.Soup.CookieJar`\. The base :obj:`~gi.repository.Soup.CookieJar` class does not support persistent storage of cookies; use a subclass for that. Methods ------- .. rst-class:: interim-class .. class:: CookieJar :no-index: .. method:: add_cookie(cookie: ~gi.repository.Soup.Cookie) -> None Adds ``cookie`` to ``jar``\. Emits the :obj:`~gi.repository.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. :param cookie: a :obj:`~gi.repository.Soup.Cookie` .. method:: add_cookie_full(cookie: ~gi.repository.Soup.Cookie, uri: ~gi.repository.GLib.Uri | None = None, first_party: ~gi.repository.GLib.Uri | None = None) -> None Adds ``cookie`` to ``jar``\. Emits the :obj:`~gi.repository.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 ``jar``\. ``uri`` will be used to reject setting or overwriting secure cookies from insecure origins. :const:`None` is treated as secure. ``cookie`` will be 'stolen' by the jar, so don't free it afterwards. :param cookie: a :obj:`~gi.repository.Soup.Cookie` :param uri: the URI setting the cookie :param first_party: the URI for the main document .. method:: add_cookie_with_first_party(first_party: ~gi.repository.GLib.Uri, cookie: ~gi.repository.Soup.Cookie) -> None Adds ``cookie`` to ``jar``\. Emits the :obj:`~gi.repository.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 ``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 :obj:`~gi.repository.CookieJar.add_cookie_full`\. :param first_party: the URI for the main document :param cookie: a :obj:`~gi.repository.Soup.Cookie` .. method:: all_cookies() -> list[~gi.repository.Soup.Cookie] Constructs a :obj:`~gi.repository.GLib.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. .. method:: delete_cookie(cookie: ~gi.repository.Soup.Cookie) -> None Deletes ``cookie`` from ``jar``\. Emits the :obj:`~gi.repository.Soup.CookieJar.signals.changed` signal. :param cookie: a :obj:`~gi.repository.Soup.Cookie` .. method:: do_changed(self, old_cookie: ~gi.repository.Soup.Cookie, new_cookie: ~gi.repository.Soup.Cookie) -> None :param old_cookie: :param new_cookie: .. method:: do_is_persistent(self) -> bool .. method:: do_save(self) -> None .. method:: get_accept_policy() -> ~gi.repository.Soup.CookieJarAcceptPolicy Gets ``jar``\'s :obj:`~gi.repository.Soup.CookieJarAcceptPolicy`\. .. method:: get_cookie_list(uri: ~gi.repository.GLib.Uri, for_http: bool) -> list[~gi.repository.Soup.Cookie] Retrieves the list of cookies that would be sent with a request to ``uri`` as a :obj:`~gi.repository.GLib.List` of :obj:`~gi.repository.Soup.Cookie` objects. If ``for_http`` is :const:`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 :obj:`~gi.repository.Soup.CookieJar` sets the Cookie header itself when making the actual HTTP request, you should almost certainly be setting ``for_http`` to :const:`False` if you are calling this. :param uri: a :obj:`~gi.repository.GLib.Uri` :param for_http: whether or not the return value is being passed directly to an HTTP operation .. method:: get_cookie_list_with_same_site_info(uri: ~gi.repository.GLib.Uri, top_level: ~gi.repository.GLib.Uri | None, site_for_cookies: ~gi.repository.GLib.Uri | None, for_http: bool, is_safe_method: bool, is_top_level_navigation: bool) -> list[~gi.repository.Soup.Cookie] This is an extended version of :obj:`~gi.repository.CookieJar.get_cookie_list` that provides more information required to use SameSite cookies. See the `SameSite cookies spec `__ for more detailed information. :param uri: a :obj:`~gi.repository.GLib.Uri` :param top_level: a :obj:`~gi.repository.GLib.Uri` for the top level document :param site_for_cookies: a :obj:`~gi.repository.GLib.Uri` indicating the origin to get cookies for :param for_http: whether or not the return value is being passed directly to an HTTP operation :param is_safe_method: if the HTTP method is safe, as defined by RFC 7231, ignored when ``for_http`` is :const:`False` :param is_top_level_navigation: whether or not the HTTP request is part of top level navigation .. method:: get_cookies(uri: ~gi.repository.GLib.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 :const:`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 :obj:`~gi.repository.Soup.CookieJar` sets the Cookie header itself when making the actual HTTP request, you should almost certainly be setting ``for_http`` to :const:`False` if you are calling this. :param uri: a :obj:`~gi.repository.GLib.Uri` :param for_http: whether or not the return value is being passed directly to an HTTP operation .. method:: is_persistent() -> bool Gets whether ``jar`` stores cookies persistenly. .. method:: set_accept_policy(policy: ~gi.repository.Soup.CookieJarAcceptPolicy) -> None Sets ``policy`` as the cookie acceptance policy for ``jar``\. :param policy: a :obj:`~gi.repository.Soup.CookieJarAcceptPolicy` .. method:: set_cookie(uri: ~gi.repository.GLib.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 :obj:`~gi.repository.Soup.CookieJarAcceptPolicy` set is either :const:`~gi.repository.Soup.CookieJarAcceptPolicy.NO_THIRD_PARTY` or :const:`~gi.repository.Soup.CookieJarAcceptPolicy.GRANDFATHERED_THIRD_PARTY` you'll need to use :obj:`~gi.repository.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. :param uri: the URI setting the cookie :param cookie: the stringified cookie to set .. method:: set_cookie_with_first_party(uri: ~gi.repository.GLib.Uri, first_party: ~gi.repository.GLib.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``\. :param uri: the URI setting the cookie :param first_party: the URI for the main document :param cookie: the stringified cookie to set Properties ---------- .. rst-class:: interim-class .. class:: CookieJar :no-index: .. attribute:: props.accept_policy :type: ~gi.repository.Soup.CookieJarAcceptPolicy The type of the None singleton. .. attribute:: props.read_only :type: bool The type of the None singleton. Signals ------- .. rst-class:: interim-class .. class:: CookieJar.signals :no-index: .. method:: changed(old_cookie: ~gi.repository.Soup.Cookie, new_cookie: ~gi.repository.Soup.Cookie) -> None The type of the None singleton. :param old_cookie: the old :obj:`~gi.repository.Soup.Cookie` value :param new_cookie: the new :obj:`~gi.repository.Soup.Cookie` value Virtual Methods --------------- .. rst-class:: interim-class .. class:: CookieJar :no-index: .. method:: do_changed(old_cookie: ~gi.repository.Soup.Cookie, new_cookie: ~gi.repository.Soup.Cookie) -> None The type of the None singleton. :param old_cookie: :param new_cookie: .. method:: do_is_persistent() -> bool Gets whether ``jar`` stores cookies persistenly. .. method:: do_save() -> None The type of the None singleton. Fields ------ .. rst-class:: interim-class .. class:: CookieJar :no-index: .. attribute:: parent_instance