:right-sidebar: True Cookie =================================================================== .. currentmodule:: gi.repository.Soup .. class:: Cookie(**kwargs) :no-contents-entry: Implements HTTP cookies, as described by `RFC 6265 `__\. To have a :obj:`~gi.repository.Soup.Session` handle cookies for your appliction automatically, use a :obj:`~gi.repository.Soup.CookieJar`\. ``name`` and ``value`` will be set for all cookies. If the cookie is generated from a string that appears to have no name, then ``name`` will be the empty string. ``domain`` and ``path`` give the host or domain, and path within that host/domain, to restrict this cookie to. If ``domain`` starts with ".", that indicates a domain (which matches the string after the ".", or any hostname that has ``domain`` as a suffix). Otherwise, it is a hostname and must match exactly. ``expires`` will be non-:const:`None` if the cookie uses either the original "expires" attribute, or the newer "max-age" attribute. If ``expires`` is :const:`None`, it indicates that neither "expires" nor "max-age" was specified, and the cookie expires at the end of the session. If ``http_only`` is set, the cookie should not be exposed to untrusted code (eg, javascript), so as to minimize the danger posed by cross-site scripting attacks. Constructors ------------ .. rst-class:: interim-class .. class:: Cookie :no-index: .. classmethod:: new(name: str, value: str, domain: str, path: str, max_age: int) -> ~gi.repository.Soup.Cookie Creates a new :obj:`~gi.repository.Soup.Cookie` with the given attributes. Use :obj:`~gi.repository.Cookie.set_secure` and :obj:`~gi.repository.Cookie.set_http_only` if you need to set those attributes on the returned cookie. If ``domain`` starts with ".", that indicates a domain (which matches the string after the ".", or any hostname that has ``domain`` as a suffix). Otherwise, it is a hostname and must match exactly. ``max_age`` is used to set the "expires" attribute on the cookie; pass -1 to not include the attribute (indicating that the cookie expires with the current session), 0 for an already-expired cookie, or a lifetime in seconds. You can use the constants :const:`~gi.repository.Soup.COOKIE_MAX_AGE_ONE_HOUR`, :const:`~gi.repository.Soup.COOKIE_MAX_AGE_ONE_DAY`, :const:`~gi.repository.Soup.COOKIE_MAX_AGE_ONE_WEEK` and :const:`~gi.repository.Soup.COOKIE_MAX_AGE_ONE_YEAR` (or multiples thereof) to calculate this value. (If you really care about setting the exact time that the cookie will expire, use :obj:`~gi.repository.Cookie.set_expires`\.) As of version 3.4.0 the default value of a cookie's same-site-policy is :const:`~gi.repository.Soup.SameSitePolicy.LAX`. :param name: cookie name :param value: cookie value :param domain: cookie domain or hostname :param path: cookie path, or :const:`None` :param max_age: max age of the cookie, or -1 for a session cookie Methods ------- .. rst-class:: interim-class .. class:: Cookie :no-index: .. method:: applies_to_uri(uri: ~gi.repository.GLib.Uri) -> bool Tests if ``cookie`` should be sent to ``uri``\. (At the moment, this does not check that ``cookie``\'s domain matches ``uri``\, because it assumes that the caller has already done that. But don't rely on that; it may change in the future.) :param uri: a :obj:`~gi.repository.GLib.Uri` .. method:: domain_matches(host: str) -> bool Checks if the ``cookie``\'s domain and ``host`` match. The domains match if ``cookie`` should be sent when making a request to ``host``\, or that ``cookie`` should be accepted when receiving a response from ``host``\. :param host: a URI .. method:: equal(cookie2: ~gi.repository.Soup.Cookie) -> bool Tests if ``cookie1`` and ``cookie2`` are equal. Note that currently, this does not check that the cookie domains match. This may change in the future. :param cookie2: a :obj:`~gi.repository.Soup.Cookie` .. method:: free() -> None Frees ``cookie``\. .. method:: get_domain() -> str Gets ``cookie``\'s domain. .. method:: get_expires() -> ~gi.repository.GLib.DateTime | None Gets ``cookie``\'s expiration time. .. method:: get_http_only() -> bool Gets ``cookie``\'s HttpOnly attribute. .. method:: get_name() -> str Gets ``cookie``\'s name. .. method:: get_path() -> str Gets ``cookie``\'s path. .. method:: get_same_site_policy() -> ~gi.repository.Soup.SameSitePolicy Returns the same-site policy for this cookie. .. method:: get_secure() -> bool Gets ``cookie``\'s secure attribute. .. method:: get_value() -> str Gets ``cookie``\'s value. .. classmethod:: parse(origin: ~gi.repository.GLib.Uri | None = None) -> ~gi.repository.Soup.Cookie | None Parses ``header`` and returns a :obj:`~gi.repository.Soup.Cookie`\. If ``header`` contains multiple cookies, only the first one will be parsed. If ``header`` does not have "path" or "domain" attributes, they will be defaulted from ``origin``\. If ``origin`` is :const:`None`, path will default to "/", but domain will be left as :const:`None`. Note that this is not a valid state for a :obj:`~gi.repository.Soup.Cookie`\, and you will need to fill in some appropriate string for the domain if you want to actually make use of the cookie. As of version 3.4.0 the default value of a cookie's same-site-policy is :const:`~gi.repository.Soup.SameSitePolicy.LAX`. :param origin: origin of the cookie .. method:: set_domain(domain: str) -> None Sets ``cookie``\'s domain to ``domain``\. :param domain: the new domain .. method:: set_expires(expires: ~gi.repository.GLib.DateTime) -> None Sets ``cookie``\'s expiration time to ``expires``\. If ``expires`` is :const:`None`, ``cookie`` will be a session cookie and will expire at the end of the client's session. (This sets the same property as :obj:`~gi.repository.Cookie.set_max_age`\.) :param expires: the new expiration time, or :const:`None` .. method:: set_http_only(http_only: bool) -> None Sets ``cookie``\'s HttpOnly attribute to ``http_only``\. If :const:`True`, ``cookie`` will be marked as "http only", meaning it should not be exposed to web page scripts or other untrusted code. :param http_only: the new value for the HttpOnly attribute .. method:: set_max_age(max_age: int) -> None Sets ``cookie``\'s max age to ``max_age``\. If ``max_age`` is -1, the cookie is a session cookie, and will expire at the end of the client's session. Otherwise, it is the number of seconds until the cookie expires. You can use the constants :const:`~gi.repository.Soup.COOKIE_MAX_AGE_ONE_HOUR`, :const:`~gi.repository.Soup.COOKIE_MAX_AGE_ONE_DAY`, :const:`~gi.repository.Soup.COOKIE_MAX_AGE_ONE_WEEK` and :const:`~gi.repository.Soup.COOKIE_MAX_AGE_ONE_YEAR` (or multiples thereof) to calculate this value. (A value of 0 indicates that the cookie should be considered already-expired.) This sets the same property as :obj:`~gi.repository.Cookie.set_expires`\. :param max_age: the new max age .. method:: set_name(name: str) -> None Sets ``cookie``\'s name to ``name``\. :param name: the new name .. method:: set_path(path: str) -> None Sets ``cookie``\'s path to ``path``\. :param path: the new path .. method:: set_same_site_policy(policy: ~gi.repository.Soup.SameSitePolicy) -> None When used in conjunction with :obj:`~gi.repository.CookieJar.get_cookie_list_with_same_site_info` this sets the policy of when this cookie should be exposed. :param policy: a :obj:`~gi.repository.Soup.SameSitePolicy` .. method:: set_secure(secure: bool) -> None Sets ``cookie``\'s secure attribute to ``secure``\. If :const:`True`, ``cookie`` will only be transmitted from the client to the server over secure (https) connections. :param secure: the new value for the secure attribute .. method:: set_value(value: str) -> None Sets ``cookie``\'s value to ``value``\. :param value: the new value .. method:: to_cookie_header() -> str Serializes ``cookie`` in the format used by the Cookie header (ie, for returning a cookie from a :obj:`~gi.repository.Soup.Session` to a server). .. method:: to_set_cookie_header() -> str Serializes ``cookie`` in the format used by the Set-Cookie header. i.e. for sending a cookie from a :obj:`~gi.repository.Soup.Server` to a client.