: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` :Constructors: :: CookieJar(**properties) new() -> Soup.CookieJar 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:: 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](https://tools.ietf.org/html/draft-ietf-httpbis-cookie-same-site-00) 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 policy the jar should follow to accept or reject cookies. .. attribute:: props.read_only :type: bool Whether or not the cookie jar is read-only. 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 Emitted when ``jar`` changes. If a cookie has been added, ``new_cookie`` will contain the newly-added cookie and ``old_cookie`` will be :const:`None`. If a cookie has been deleted, ``old_cookie`` will contain the to-be-deleted cookie and ``new_cookie`` will be :const:`None`. If a cookie has been changed, ``old_cookie`` will contain its old value, and ``new_cookie`` its new value. :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 :param old_cookie: :param new_cookie: .. method:: do_is_persistent() -> bool Gets whether ``jar`` stores cookies persistenly. .. method:: do_save() -> None Fields ------ .. rst-class:: interim-class .. class:: CookieJar :no-index: .. attribute:: parent_instance