:right-sidebar: True Message =================================================================== .. currentmodule:: gi.repository.Soup .. class:: Message(**properties: ~typing.Any) :no-contents-entry: Superclasses: :class:`~gi.repository.GObject.Object` :Constructors: :: Message(**properties) new(method:str, uri_string:str) -> Soup.Message or None new_from_encoded_form(method:str, uri_string:str, encoded_form:str) -> Soup.Message or None new_from_multipart(uri_string:str, multipart:Soup.Multipart) -> Soup.Message or None new_from_uri(method:str, uri:GLib.Uri) -> Soup.Message new_options_ping(base_uri:GLib.Uri) -> Soup.Message Constructors ------------ .. rst-class:: interim-class .. class:: Message :no-index: .. classmethod:: new(method: str, uri_string: str) -> ~gi.repository.Soup.Message | None Creates a new empty :obj:`~gi.repository.Soup.Message`, which will connect to ``uri``. :param method: the HTTP method for the created request :param uri_string: the destination endpoint (as a string) .. classmethod:: new_from_encoded_form(method: str, uri_string: str, encoded_form: str) -> ~gi.repository.Soup.Message | None Creates a new :obj:`~gi.repository.Soup.Message` and sets it up to send the given ``encoded_form`` to ``uri`` via ``method``. If ``method`` is "GET", it will include the form data into ``uri``'s query field, and if ``method`` is "POST" or "PUT", it will be set as request body. This function takes the ownership of ``encoded_form``, that will be released with :obj:`~gi.repository.GLib.free` when no longer in use. See also :obj:`~gi.repository.Soup.form_encode`, :obj:`~gi.repository.Soup.form_encode_hash` and :obj:`~gi.repository.Soup.form_encode_datalist`. :param method: the HTTP method for the created request (GET, POST or PUT) :param uri_string: the destination endpoint (as a string) :param encoded_form: a encoded form .. classmethod:: new_from_multipart(uri_string: str, multipart: ~gi.repository.Soup.Multipart) -> ~gi.repository.Soup.Message | None Creates a new :obj:`~gi.repository.Soup.Message` and sets it up to send ``multipart`` to ``uri_string`` via POST. :param uri_string: the destination endpoint :param multipart: a :obj:`~gi.repository.Soup.Multipart` .. classmethod:: new_from_uri(method: str, uri: ~gi.repository.GLib.Uri) -> ~gi.repository.Soup.Message Creates a new empty :obj:`~gi.repository.Soup.Message`, which will connect to ``uri``. :param method: the HTTP method for the created request :param uri: the destination endpoint .. classmethod:: new_options_ping(base_uri: ~gi.repository.GLib.Uri) -> ~gi.repository.Soup.Message Creates a new :obj:`~gi.repository.Soup.Message` to send `OPTIONS *` to a server. The path of ``base_uri`` will be ignored. :param base_uri: the destination endpoint Methods ------- .. rst-class:: interim-class .. class:: Message :no-index: .. method:: add_flags(flags: ~gi.repository.Soup.MessageFlags) -> None Adds ``flags`` to the set of ``msg``'s flags. :param flags: a set of :obj:`~gi.repository.Soup.MessageFlags` values .. method:: disable_feature(feature_type: type) -> None Disables the actions of :obj:`~gi.repository.Soup.SessionFeature`'s with the given ``feature_type`` (or a subclass of that type) on ``msg``. ``msg`` is processed as though the feature(s) hadn't been added to the session. Eg, passing ``SOUP_TYPE_CONTENT_SNIFFER`` for ``feature_type`` will disable Content-Type sniffing on the message. You must call this before queueing ``msg`` on a session; calling it on a message that has already been queued is undefined. In particular, you cannot call this on a message that is being requeued after a redirect or authentication. :param feature_type: the :obj:`~gi.repository.GObject.Type` of a :obj:`~gi.repository.Soup.SessionFeature` .. method:: get_connection_id() -> int Returns the unique idenfier for the last connection used. This may be 0 if it was a cached resource or it has not gotten a connection yet. .. method:: get_first_party() -> ~gi.repository.GLib.Uri Gets ``msg``'s first-party :obj:`~gi.repository.GLib.Uri`. .. method:: get_flags() -> ~gi.repository.Soup.MessageFlags Gets the flags on ``msg``. .. method:: get_force_http1() -> bool Returns whether HTTP/1 version is currently demanded for the ``msg`` send. .. versionadded:: 3.4 .. method:: get_http_version() -> ~gi.repository.Soup.HTTPVersion Gets the HTTP version of ``msg``. This is the minimum of the version from the request and the version from the response. .. method:: get_is_options_ping() -> bool Gets whether ``msg`` is intended to be used to send `OPTIONS *` to a server. .. method:: get_is_top_level_navigation() -> bool Returns if this message is set as a top level navigation. Used for same-site policy checks. .. method:: get_method() -> str Returns the method of this message. .. method:: get_metrics() -> ~gi.repository.Soup.MessageMetrics | None Get the :obj:`~gi.repository.Soup.MessageMetrics` of ``msg``. If the flag :const:`~gi.repository.Soup.MessageFlags.COLLECT_METRICS` is not enabled for ``msg`` this will return :const:`None`. .. method:: get_priority() -> ~gi.repository.Soup.MessagePriority Retrieves the :obj:`~gi.repository.Soup.MessagePriority`. If not set this value defaults to ``SOUP_MESSAGE_PRIORITY_NORMAL``. .. method:: get_reason_phrase() -> str | None Returns the reason phrase for the status of this message. .. method:: get_remote_address() -> ~gi.repository.Gio.SocketAddress | None Get the remote :obj:`~gi.repository.Gio.SocketAddress` of the connection associated with the message. The returned address can be :const:`None` if the connection hasn't been established yet, or the resource was loaded from the disk cache. In case of proxy connections, the remote address returned is a :obj:`~gi.repository.Gio.ProxyAddress`. If :obj:`~gi.repository.Soup.Session.props.remote_connectable` is set the returned address id for the connection to the session's remote connectable. .. method:: get_request_headers() -> ~gi.repository.Soup.MessageHeaders Returns the headers sent with the request. .. method:: get_response_headers() -> ~gi.repository.Soup.MessageHeaders Returns the headers recieved with the response. .. method:: get_site_for_cookies() -> ~gi.repository.GLib.Uri Gets ``msg``'s site for cookies :obj:`~gi.repository.GLib.Uri`. .. method:: get_status() -> ~gi.repository.Soup.Status Returns the set status of this message. .. method:: get_tls_ciphersuite_name() -> str Gets the name of the TLS ciphersuite negotiated for ``msg``'s connection. .. method:: get_tls_peer_certificate() -> ~gi.repository.Gio.TlsCertificate | None Gets the peer's :obj:`~gi.repository.Gio.TlsCertificate` associated with ``msg``'s connection. Note that this is not set yet during the emission of :obj:`~gi.repository.Soup.Message.signals.accept_certificate` signal. .. method:: get_tls_peer_certificate_errors() -> ~gi.repository.Gio.TlsCertificateFlags Gets the errors associated with validating ``msg``'s TLS peer certificate. Note that this is not set yet during the emission of :obj:`~gi.repository.Soup.Message.signals.accept_certificate` signal. .. method:: get_tls_protocol_version() -> ~gi.repository.Gio.TlsProtocolVersion Gets the TLS protocol version negotiated for ``msg``'s connection. If the message connection is not SSL, ``%G_TLS_PROTOCOL_VERSION_UNKNOWN`` is returned. .. method:: get_uri() -> ~gi.repository.GLib.Uri Gets ``msg``'s URI. .. method:: is_feature_disabled(feature_type: type) -> bool Get whether :obj:`~gi.repository.Soup.SessionFeature`'s of the given ``feature_type`` (or a subclass of that type) are disabled on ``msg``. See :obj:`~gi.repository.Message.disable_feature`. :param feature_type: the :obj:`~gi.repository.GObject.Type` of a :obj:`~gi.repository.Soup.SessionFeature` .. method:: is_keepalive() -> bool Determines whether or not ``msg``'s connection can be kept alive for further requests after processing ``msg``. The result is based on the HTTP version, Connection header, etc. .. method:: query_flags(flags: ~gi.repository.Soup.MessageFlags) -> bool Queries if ``flags`` are present in the set of ``msg``'s flags. :param flags: a set of :obj:`~gi.repository.Soup.MessageFlags` values .. method:: remove_flags(flags: ~gi.repository.Soup.MessageFlags) -> None Removes ``flags`` from the set of ``msg``'s flags. :param flags: a set of :obj:`~gi.repository.Soup.MessageFlags` values .. method:: set_first_party(first_party: ~gi.repository.GLib.Uri) -> None Sets ``first_party`` as the main document :obj:`~gi.repository.GLib.Uri` for ``msg``. For details of when and how this is used refer to the documentation for :obj:`~gi.repository.Soup.CookieJarAcceptPolicy`. :param first_party: the :obj:`~gi.repository.GLib.Uri` for the ``msg``'s first party .. method:: set_flags(flags: ~gi.repository.Soup.MessageFlags) -> None Sets the specified flags on ``msg``. :param flags: a set of :obj:`~gi.repository.Soup.MessageFlags` values .. method:: set_force_http1(value: bool) -> None Sets whether HTTP/1 version should be used when sending this message. Some connections can still override it, if needed. Note the value is unset after the message send is finished. .. versionadded:: 3.4 :param value: value to set .. method:: set_is_options_ping(is_options_ping: bool) -> None Set whether ``msg`` is intended to be used to send `OPTIONS *` to a server. When set to :const:`True`, the path of :obj:`~gi.repository.Soup.Message.props.uri` will be ignored and :obj:`~gi.repository.Soup.Message.props.method` set to ``%SOUP_METHOD_OPTIONS``. :param is_options_ping: the value to set .. method:: set_is_top_level_navigation(is_top_level_navigation: bool) -> None Sets whether the current request is a top-level navitation. See the `same-site spec `_ for more information. :param is_top_level_navigation: if :const:`True` indicate the current request is a top-level navigation .. method:: set_method(method: str) -> None Set ``msg``'s HTTP method to ``method``. :param method: the value to set .. method:: set_priority(priority: ~gi.repository.Soup.MessagePriority) -> None Sets the priority of a message. Note that this won't have any effect unless used before the message is added to the session's message processing queue. The message will be placed just before any other previously added message with lower priority (messages with the same priority are processed on a FIFO basis). Setting priorities does not currently work with synchronous messages because in the synchronous/blocking case, priority ends up being determined semi-randomly by thread scheduling. :param priority: the :obj:`~gi.repository.Soup.MessagePriority` .. method:: set_request_body(content_type: str | None, stream: ~gi.repository.Gio.InputStream | None, content_length: int) -> None Set the request body of a :obj:`~gi.repository.Soup.Message`. If ``content_type`` is :const:`None` and ``stream`` is not :const:`None` the Content-Type header will not be changed if present. The request body needs to be set again in case ``msg`` is restarted (in case of redirection or authentication). :param content_type: MIME Content-Type of the body, or :const:`None` if unknown :param stream: a :obj:`~gi.repository.Gio.InputStream` to read the request body from :param content_length: the byte length of ``stream`` or -1 if unknown .. method:: set_request_body_from_bytes(content_type: str | None = None, bytes: ~gi.repository.GLib.Bytes | None = None) -> None Set the request body of a :obj:`~gi.repository.Soup.Message` from :obj:`~gi.repository.GLib.Bytes`. If ``content_type`` is :const:`None` and ``bytes`` is not :const:`None` the Content-Type header will not be changed if present. The request body needs to be set again in case ``msg`` is restarted (in case of redirection or authentication). :param content_type: MIME Content-Type of the body, or :const:`None` if unknown :param bytes: a :obj:`~gi.repository.GLib.Bytes` with the request body data .. method:: set_site_for_cookies(site_for_cookies: ~gi.repository.GLib.Uri | None = None) -> None Sets ``site_for_cookies`` as the policy URL for same-site cookies for ``msg``. It is either the URL of the top-level document or :const:`None` depending on whether the registrable domain of this document's URL matches the registrable domain of its parent's/opener's URL. For the top-level document it is set to the document's URL. See the `same-site spec `_ for more information. :param site_for_cookies: the :obj:`~gi.repository.GLib.Uri` for the ``msg``'s site for cookies .. method:: set_tls_client_certificate(certificate: ~gi.repository.Gio.TlsCertificate | None = None) -> None Sets the ``certificate`` to be used by ``msg``'s connection when a client certificate is requested during the TLS handshake. You can call this as a response to :obj:`~gi.repository.Soup.Message.signals.request_certificate` signal, or before the connection is started. If ``certificate`` is :const:`None` the handshake will continue without providing a GTlsCertificate. Note that the :obj:`~gi.repository.Gio.TlsCertificate` set by this function will be ignored if :obj:`~gi.repository.Soup.Session.props.tls_interaction` is not :const:`None`. :param certificate: the :obj:`~gi.repository.Gio.TlsCertificate` to set, or :const:`None` .. method:: set_uri(uri: ~gi.repository.GLib.Uri) -> None Sets ``msg``'s URI to ``uri``. If ``msg`` has already been sent and you want to re-send it with the new URI, you need to send it again. :param uri: the new :obj:`~gi.repository.GLib.Uri` .. method:: tls_client_certificate_password_request_complete() -> None Completes a certificate password request. You must call this as a response to :obj:`~gi.repository.Soup.Message.signals.request_certificate_password` signal, to notify ``msg`` that the :obj:`~gi.repository.Gio.TlsPassword` has already been updated. Properties ---------- .. rst-class:: interim-class .. class:: Message :no-index: .. attribute:: props.first_party :type: ~gi.repository.GLib.Uri The :obj:`~gi.repository.GLib.Uri` loaded in the application when the message was queued. .. attribute:: props.flags :type: ~gi.repository.Soup.MessageFlags Various message options. .. attribute:: props.http_version :type: ~gi.repository.Soup.HTTPVersion The HTTP protocol version to use. .. attribute:: props.is_options_ping :type: bool Whether the message is an OPTIONS ping. The :obj:`~gi.repository.Soup.Message` is intended to be used to send `OPTIONS *` to a server. When set to :const:`True`, the path of :obj:`~gi.repository.Soup.Message.props.uri` will be ignored and :obj:`~gi.repository.Soup.Message.props.method` set to ``%SOUP_METHOD_OPTIONS``. .. attribute:: props.is_top_level_navigation :type: bool Set when the message is navigating between top level domains. .. attribute:: props.method :type: str The message's HTTP method. .. attribute:: props.priority :type: ~gi.repository.Soup.MessagePriority Sets the priority of the :obj:`~gi.repository.Soup.Message`. See :obj:`~gi.repository.Message.set_priority` for further details. .. attribute:: props.reason_phrase :type: str The HTTP response reason phrase. .. attribute:: props.remote_address :type: ~gi.repository.Gio.SocketAddress The remote :obj:`~gi.repository.Gio.SocketAddress` of the connection associated with the message. .. attribute:: props.request_headers :type: ~gi.repository.Soup.MessageHeaders The HTTP request headers. .. attribute:: props.response_headers :type: ~gi.repository.Soup.MessageHeaders The HTTP response headers. .. attribute:: props.site_for_cookies :type: ~gi.repository.GLib.Uri Site used to compare cookies against. Used for SameSite cookie support. .. attribute:: props.status_code :type: int The HTTP response status code. .. attribute:: props.tls_ciphersuite_name :type: str The Name of TLS ciphersuite negotiated for this message connection. .. attribute:: props.tls_peer_certificate :type: ~gi.repository.Gio.TlsCertificate The peer's :obj:`~gi.repository.Gio.TlsCertificate` associated with the message. .. attribute:: props.tls_peer_certificate_errors :type: ~gi.repository.Gio.TlsCertificateFlags The verification errors on :obj:`~gi.repository.Soup.Message.props.tls_peer_certificate`. .. attribute:: props.tls_protocol_version :type: ~gi.repository.Gio.TlsProtocolVersion The TLS protocol version negotiated for the message connection. .. attribute:: props.uri :type: ~gi.repository.GLib.Uri The message's Request-URI. Signals ------- .. rst-class:: interim-class .. class:: Message.signals :no-index: .. method:: accept_certificate(tls_peer_certificate: ~gi.repository.Gio.TlsCertificate, tls_peer_errors: ~gi.repository.Gio.TlsCertificateFlags) -> bool Emitted during the ``msg``'s connection TLS handshake after an unacceptable TLS certificate has been received. You can return :const:`True` to accept ``tls_certificate`` despite ``tls_errors``. :param tls_peer_certificate: the peer's :obj:`~gi.repository.Gio.TlsCertificate` :param tls_peer_errors: the tls errors of ``tls_certificate`` .. method:: authenticate(auth: ~gi.repository.Soup.Auth, retrying: bool) -> bool Emitted when the message requires authentication. If credentials are available call :obj:`~gi.repository.Auth.authenticate` on ``auth``. If these credentials fail, the signal will be emitted again, with ``retrying`` set to :const:`True`, which will continue until you return without calling :obj:`~gi.repository.Auth.authenticate` on ``auth``. Note that this may be emitted before ``msg``'s body has been fully read. You can authenticate ``auth`` asynchronously by calling :obj:`~gi.repository.GObject.Object.ref` on ``auth`` and returning :const:`True`. The operation will complete once either :obj:`~gi.repository.Auth.authenticate` or :obj:`~gi.repository.Auth.cancel` are called. :param auth: the :obj:`~gi.repository.Soup.Auth` to authenticate :param retrying: :const:`True` if this is the second (or later) attempt .. method:: content_sniffed(type: str, params: dict[str, str]) -> None This signal is emitted after :obj:`~gi.repository.Soup.Message.signals.got_headers`. If content sniffing is disabled, or no content sniffing will be performed, due to the sniffer deciding to trust the Content-Type sent by the server, this signal is emitted immediately after :obj:`~gi.repository.Soup.Message.signals.got_headers`, and ``type`` is :const:`None`. :param type: the content type that we got from sniffing :param params: a :obj:`~gi.repository.GLib.HashTable` with the parameters .. method:: finished() -> None Emitted when all HTTP processing is finished for a message. (After :obj:`~gi.repository.Soup.Message.signals.got_body`). .. method:: got_body() -> None Emitted after receiving the complete message response body. .. method:: got_body_data(chunk_size: int) -> None Emitted after reading a portion of the message body from the network. .. versionadded:: 3.4 :param chunk_size: the number of bytes read .. method:: got_headers() -> None Emitted after receiving the Status-Line and response headers. See also :obj:`~gi.repository.Message.add_header_handler` and :obj:`~gi.repository.Message.add_status_code_handler`, which can be used to connect to a subset of emissions of this signal. If you cancel or requeue ``msg`` while processing this signal, then the current HTTP I/O will be stopped after this signal emission finished, and ``msg``'s connection will be closed. (If you need to requeue a message--eg, after handling authentication or redirection--it is usually better to requeue it from a :obj:`~gi.repository.Soup.Message.signals.got_body` handler rather than a :obj:`~gi.repository.Soup.Message.signals.got_headers` handler, so that the existing HTTP connection can be reused.) .. method:: got_informational() -> None Emitted after receiving a 1xx (Informational) response for a (client-side) message. The response_headers will be filled in with the headers associated with the informational response; however, those header values will be erased after this signal is done. If you cancel or requeue ``msg`` while processing this signal, then the current HTTP I/O will be stopped after this signal emission finished, and ``msg``'s connection will be closed. .. method:: hsts_enforced() -> None Emitted when :obj:`~gi.repository.Soup.HSTSEnforcer` has upgraded the protocol for ``msg`` to HTTPS as a result of matching its domain with a HSTS policy. .. method:: network_event(event: ~gi.repository.Gio.SocketClientEvent, connection: ~gi.repository.Gio.IOStream) -> None Emitted to indicate that some network-related event related to ``msg`` has occurred. This essentially proxies the :obj:`~gi.repository.Gio.SocketClient.signals.event` signal, but only for events that occur while ``msg`` "owns" the connection; if ``msg`` is sent on an existing persistent connection, then this signal will not be emitted. (If you want to force the message to be sent on a new connection, set the :const:`~gi.repository.Soup.MessageFlags.NEW_CONNECTION` flag on it.) See :obj:`~gi.repository.Gio.SocketClient.signals.event` for more information on what the different values of ``event`` correspond to, and what ``connection`` will be in each case. :param event: the network event :param connection: the current state of the network connection .. method:: request_certificate(tls_connection: ~gi.repository.Gio.TlsClientConnection) -> bool Emitted during the ``msg``'s connection TLS handshake when ``tls_connection`` requests a certificate from the client. You can set the client certificate by calling :obj:`~gi.repository.Message.set_tls_client_certificate` and returning :const:`True`. It's possible to handle the request asynchornously by returning :const:`True` and call :obj:`~gi.repository.Message.set_tls_client_certificate` later once the certificate is available. Note that this signal is not emitted if :obj:`~gi.repository.Soup.Session.props.tls_interaction` was set, or if :obj:`~gi.repository.Message.set_tls_client_certificate` was called before the connection TLS handshake started. :param tls_connection: the :obj:`~gi.repository.Gio.TlsClientConnection` .. method:: request_certificate_password(tls_password: ~gi.repository.Gio.TlsPassword) -> bool Emitted during the ``msg``'s connection TLS handshake when ``tls_connection`` requests a certificate password from the client. You can set the certificate password on ``password``, then call :obj:`~gi.repository.Message.tls_client_certificate_password_request_complete` and return :const:`True` to handle the signal synchronously. It's possible to handle the request asynchornously by calling :obj:`~gi.repository.GObject.Object.ref` on ``password``, then returning :const:`True` and call :obj:`~gi.repository.Message.tls_client_certificate_password_request_complete` later after setting the password on ``password``. Note that this signal is not emitted if :obj:`~gi.repository.Soup.Session.props.tls_interaction` was set. :param tls_password: the :obj:`~gi.repository.Gio.TlsPassword` .. method:: restarted() -> None Emitted when a request that was already sent once is now being sent again. e.g. because the first attempt received a redirection response, or because we needed to use authentication. .. method:: starting() -> None Emitted just before a message is sent. .. method:: wrote_body() -> None Emitted immediately after writing the complete body for a message. .. method:: wrote_body_data(chunk_size: int) -> None Emitted immediately after writing a portion of the message body to the network. :param chunk_size: the number of bytes written .. method:: wrote_headers() -> None Emitted immediately after writing the request headers for a message.