:right-sidebar: True Message =================================================================== .. currentmodule:: gi.repository.Soup .. class:: Message(**properties: ~typing.Any) :no-contents-entry: Superclasses: :class:`~gi.repository.GObject.Object` Represents an HTTP message being sent or received. A :obj:`~gi.repository.Soup.Message` represents an HTTP message that is being sent or received. You would create a :obj:`~gi.repository.Soup.Message` with :obj:`~gi.repository.Message.new` or :obj:`~gi.repository.Message.new_from_uri`\, set up its fields appropriately, and send it. :obj:`~gi.repository.Soup.Message.props.status_code` will normally be a :obj:`~gi.repository.Soup.Status` value, eg, :const:`~gi.repository.Soup.Status.OK`, though of course it might actually be an unknown status code. :obj:`~gi.repository.Soup.Message.props.reason_phrase` is the actual text returned from the server, which may or may not correspond to the "standard" description of ``status_code``\. At any rate, it is almost certainly not localized, and not very descriptive even if it is in the user's language; you should not use :obj:`~gi.repository.Soup.Message.props.reason_phrase` in user-visible messages. Rather, you should look at :obj:`~gi.repository.Soup.Message.props.status_code`\, and determine an end-user-appropriate message based on that and on what you were trying to do. Note that libsoup's terminology here does not quite match the HTTP specification: in RFC 2616, an "HTTP-message" is *either* a Request, *or* a Response. In libsoup, a :obj:`~gi.repository.Soup.Message` combines both the request and the response. 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: ~gobject.GType) -> 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: ~gobject.GType) -> 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 type of the None singleton. .. attribute:: props.flags :type: ~gi.repository.Soup.MessageFlags The type of the None singleton. .. attribute:: props.http_version :type: ~gi.repository.Soup.HTTPVersion The type of the None singleton. .. attribute:: props.is_options_ping :type: bool The type of the None singleton. .. attribute:: props.is_top_level_navigation :type: bool The type of the None singleton. .. attribute:: props.method :type: str The type of the None singleton. .. attribute:: props.priority :type: ~gi.repository.Soup.MessagePriority The type of the None singleton. .. attribute:: props.reason_phrase :type: str The type of the None singleton. .. attribute:: props.remote_address :type: ~gi.repository.Gio.SocketAddress The type of the None singleton. .. attribute:: props.request_headers :type: ~gi.repository.Soup.MessageHeaders The type of the None singleton. .. attribute:: props.response_headers :type: ~gi.repository.Soup.MessageHeaders The type of the None singleton. .. attribute:: props.site_for_cookies :type: ~gi.repository.GLib.Uri The type of the None singleton. .. attribute:: props.status_code :type: int The type of the None singleton. .. attribute:: props.tls_ciphersuite_name :type: str The type of the None singleton. .. attribute:: props.tls_peer_certificate :type: ~gi.repository.Gio.TlsCertificate The type of the None singleton. .. attribute:: props.tls_peer_certificate_errors :type: ~gi.repository.Gio.TlsCertificateFlags The type of the None singleton. .. attribute:: props.tls_protocol_version :type: ~gi.repository.Gio.TlsProtocolVersion The type of the None singleton. .. attribute:: props.uri :type: ~gi.repository.GLib.Uri The type of the None singleton. 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 The type of the None singleton. :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 The type of the None singleton. :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 The type of the None singleton. :param type: the content type that we got from sniffing :param params: a :obj:`~gi.repository.GLib.HashTable` with the parameters .. method:: finished() -> None The type of the None singleton. .. method:: got_body() -> None The type of the None singleton. .. method:: got_body_data(chunk_size: int) -> None The type of the None singleton. .. versionadded:: 3.4 :param chunk_size: the number of bytes read .. method:: got_headers() -> None The type of the None singleton. .. method:: got_informational() -> None The type of the None singleton. .. method:: hsts_enforced() -> None The type of the None singleton. .. method:: network_event(event: ~gi.repository.Gio.SocketClientEvent, connection: ~gi.repository.Gio.IOStream) -> None The type of the None singleton. :param event: the network event :param connection: the current state of the network connection .. method:: request_certificate(tls_connection: ~gi.repository.Gio.TlsClientConnection) -> bool The type of the None singleton. :param tls_connection: the :obj:`~gi.repository.Gio.TlsClientConnection` .. method:: request_certificate_password(tls_password: ~gi.repository.Gio.TlsPassword) -> bool The type of the None singleton. :param tls_password: the :obj:`~gi.repository.Gio.TlsPassword` .. method:: restarted() -> None The type of the None singleton. .. method:: starting() -> None The type of the None singleton. .. method:: wrote_body() -> None The type of the None singleton. .. method:: wrote_body_data(chunk_size: int) -> None The type of the None singleton. :param chunk_size: the number of bytes written .. method:: wrote_headers() -> None The type of the None singleton.