Message

class Message(**properties: Any)

Superclasses: Object

Represents an HTTP message being sent or received.

A Message represents an HTTP message that is being sent or received.

You would create a Message with new or new_from_uri, set up its fields appropriately, and send it.

status_code will normally be a Status value, eg, OK, though of course it might actually be an unknown status code. 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 reason_phrase in user-visible messages. Rather, you should look at 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 Message combines both the request and the response.

Constructors

class Message

classmethod new(method: str, uri_string: str) → Message | None

Creates a new empty Message, which will connect to uri.

Parameters:

• method – the HTTP method for the created request

• uri_string – the destination endpoint (as a string)

classmethod new_from_encoded_form(method: str, uri_string: str, encoded_form: str) → Message | None

Creates a new 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 free when no longer in use. See also form_encode, form_encode_hash and form_encode_datalist.

Parameters:

• method – the HTTP method for the created request (GET, POST or PUT)

• uri_string – the destination endpoint (as a string)

• encoded_form – a encoded form

classmethod new_from_multipart(uri_string: str, multipart: Multipart) → Message | None

Creates a new Message and sets it up to send multipart to uri_string via POST.

Parameters:

• uri_string – the destination endpoint

• multipart – a Multipart

classmethod new_from_uri(method: str, uri: Uri) → Message

Creates a new empty Message, which will connect to uri.

Parameters:

• method – the HTTP method for the created request

• uri – the destination endpoint

classmethod new_options_ping(base_uri: Uri) → Message

Creates a new Message to send OPTIONS * to a server. The path of base_uri will be ignored.

Parameters:

base_uri – the destination endpoint

Methods

class Message

add_flags(flags: MessageFlags) → None

Adds flags to the set of msg's flags.

Parameters:

flags – a set of MessageFlags values

disable_feature(feature_type: GType) → None

Disables the actions of SessionFeatures 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.

Parameters:

feature_type – the Type of a SessionFeature

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.

get_first_party() → Uri

Gets msg's first-party Uri.

get_flags() → MessageFlags

Gets the flags on msg.

get_force_http1() → bool

Returns whether HTTP/1 version is currently demanded for the msg send.

Added in version 3.4.

get_http_version() → HTTPVersion

Gets the HTTP version of msg.

This is the minimum of the version from the request and the version from the response.

get_is_options_ping() → bool

Gets whether msg is intended to be used to send OPTIONS * to a server.

get_is_top_level_navigation() → bool

Returns if this message is set as a top level navigation.

Used for same-site policy checks.

get_method() → str

Returns the method of this message.

get_metrics() → MessageMetrics | None

Get the MessageMetrics of msg.

If the flag COLLECT_METRICS is not enabled for msg this will return None.

get_priority() → MessagePriority

Retrieves the MessagePriority.

If not set this value defaults to SOUP_MESSAGE_PRIORITY_NORMAL.

get_reason_phrase() → str | None

Returns the reason phrase for the status of this message.

get_remote_address() → SocketAddress | None

Get the remote SocketAddress of the connection associated with the message.

The returned address can be 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 ProxyAddress. If remote_connectable is set the returned address id for the connection to the session’s remote connectable.

get_request_headers() → MessageHeaders

Returns the headers sent with the request.

get_response_headers() → MessageHeaders

Returns the headers recieved with the response.

get_site_for_cookies() → Uri

Gets msg's site for cookies Uri.

get_status() → Status

Returns the set status of this message.

get_tls_ciphersuite_name() → str

Gets the name of the TLS ciphersuite negotiated for msg's connection.

get_tls_peer_certificate() → TlsCertificate | None

Gets the peer’s TlsCertificate associated with msg's connection.

Note that this is not set yet during the emission of accept_certificate signal.

get_tls_peer_certificate_errors() → TlsCertificateFlags

Gets the errors associated with validating msg's TLS peer certificate. Note that this is not set yet during the emission of accept_certificate signal.

get_tls_protocol_version() → 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.

get_uri() → Uri

Gets msg's URI.

is_feature_disabled(feature_type: GType) → bool

Get whether SessionFeatures of the given feature_type (or a subclass of that type) are disabled on msg.

See disable_feature.

Parameters:

feature_type – the Type of a SessionFeature

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.

query_flags(flags: MessageFlags) → bool

Queries if flags are present in the set of msg's flags.

Parameters:

flags – a set of MessageFlags values

remove_flags(flags: MessageFlags) → None

Removes flags from the set of msg's flags.

Parameters:

flags – a set of MessageFlags values

set_first_party(first_party: Uri) → None

Sets first_party as the main document Uri for msg.

For details of when and how this is used refer to the documentation for CookieJarAcceptPolicy.

Parameters:

first_party – the Uri for the msg's first party

set_flags(flags: MessageFlags) → None

Sets the specified flags on msg.

Parameters:

flags – a set of MessageFlags values

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.

Added in version 3.4.

Parameters:

value – value to set

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 True, the path of uri will be ignored and method set to %SOUP_METHOD_OPTIONS.

Parameters:

is_options_ping – the value to set

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.

Parameters:

is_top_level_navigation – if True indicate the current request is a top-level navigation

set_method(method: str) → None

Set msg's HTTP method to method.

Parameters:

method – the value to set

set_priority(priority: 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.

Parameters:

priority – the MessagePriority

set_request_body(content_type: str | None, stream: InputStream | None, content_length: int) → None

Set the request body of a Message.

If content_type is None and stream is not 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).

Parameters:

• content_type – MIME Content-Type of the body, or None if unknown

• stream – a InputStream to read the request body from

• content_length – the byte length of stream or -1 if unknown

set_request_body_from_bytes(content_type: str | None = None, bytes: Bytes | None = None) → None

Set the request body of a Message from Bytes.

If content_type is None and bytes is not 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).

Parameters:

• content_type – MIME Content-Type of the body, or None if unknown

• bytes – a Bytes with the request body data

set_site_for_cookies(site_for_cookies: 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 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.

Parameters:

site_for_cookies – the Uri for the msg's site for cookies

set_tls_client_certificate(certificate: 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 request_certificate signal, or before the connection is started. If certificate is None the handshake will continue without providing a GTlsCertificate. Note that the TlsCertificate set by this function will be ignored if tls_interaction is not None.

Parameters:

certificate – the TlsCertificate to set, or None

set_uri(uri: 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.

Parameters:

uri – the new Uri

tls_client_certificate_password_request_complete() → None

Completes a certificate password request.

You must call this as a response to request_certificate_password signal, to notify msg that the TlsPassword has already been updated.

Properties

class Message

props.first_party: Uri

The Uri loaded in the application when the message was queued.

props.flags: MessageFlags

Various message options.

props.http_version: HTTPVersion

The HTTP protocol version to use.

props.is_options_ping: bool

Whether the message is an OPTIONS ping.

The Message is intended to be used to send OPTIONS * to a server. When set to True, the path of uri will be ignored and method set to %SOUP_METHOD_OPTIONS.

props.is_top_level_navigation: bool

Set when the message is navigating between top level domains.

props.method: str

The message’s HTTP method.

props.priority: MessagePriority

Sets the priority of the Message. See set_priority for further details.

props.reason_phrase: str

The HTTP response reason phrase.

props.remote_address: SocketAddress

The remote SocketAddress of the connection associated with the message.

props.request_headers: MessageHeaders

The HTTP request headers.

props.response_headers: MessageHeaders

The HTTP response headers.

props.site_for_cookies: Uri

Site used to compare cookies against. Used for SameSite cookie support.

props.status_code: int

The HTTP response status code.

props.tls_ciphersuite_name: str

The Name of TLS ciphersuite negotiated for this message connection.

props.tls_peer_certificate: TlsCertificate

The peer’s TlsCertificate associated with the message.

props.tls_peer_certificate_errors: TlsCertificateFlags

The verification errors on tls_peer_certificate.

props.tls_protocol_version: TlsProtocolVersion

The TLS protocol version negotiated for the message connection.

props.uri: Uri

The message’s Request-URI.

Signals

class Message.signals

accept_certificate(tls_peer_certificate: TlsCertificate, tls_peer_errors: TlsCertificateFlags) → bool

Emitted during the msg's connection TLS handshake after an unacceptable TLS certificate has been received.

You can return True to accept tls_certificate despite tls_errors.

Parameters:

• tls_peer_certificate – the peer’s TlsCertificate

• tls_peer_errors – the tls errors of tls_certificate

authenticate(auth: Auth, retrying: bool) → bool

Emitted when the message requires authentication.

If credentials are available call authenticate on auth. If these credentials fail, the signal will be emitted again, with retrying set to True, which will continue until you return without calling authenticate on auth.

Note that this may be emitted before msg's body has been fully read.

You can authenticate auth asynchronously by calling ref on auth and returning True. The operation will complete once either authenticate or cancel are called.

Parameters:

• auth – the Auth to authenticate

• retrying – True if this is the second (or later) attempt

content_sniffed(type: str, params: dict[str, str]) → None

This signal is emitted after 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 got_headers, and type is None.

Parameters:

• type – the content type that we got from sniffing

• params – a HashTable with the parameters

finished() → None

Emitted when all HTTP processing is finished for a message.

(After got_body).

got_body() → None

Emitted after receiving the complete message response body.

got_body_data(chunk_size: int) → None

Emitted after reading a portion of the message body from the network.

Added in version 3.4.

Parameters:

chunk_size – the number of bytes read

got_headers() → None

Emitted after receiving the Status-Line and response headers.

See also add_header_handler and 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 got_body handler rather than a got_headers handler, so that the existing HTTP connection can be reused.)

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.

hsts_enforced() → None

Emitted when HSTSEnforcer has upgraded the protocol for msg to HTTPS as a result of matching its domain with a HSTS policy.

network_event(event: SocketClientEvent, connection: IOStream) → None

Emitted to indicate that some network-related event related to msg has occurred.

This essentially proxies the 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 NEW_CONNECTION flag on it.)

See event for more information on what the different values of event correspond to, and what connection will be in each case.

Parameters:

• event – the network event

• connection – the current state of the network connection

request_certificate(tls_connection: 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 set_tls_client_certificate and returning True. It’s possible to handle the request asynchornously by returning True and call set_tls_client_certificate later once the certificate is available. Note that this signal is not emitted if tls_interaction was set, or if set_tls_client_certificate was called before the connection TLS handshake started.

Parameters:

tls_connection – the TlsClientConnection

request_certificate_password(tls_password: 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 tls_client_certificate_password_request_complete and return True to handle the signal synchronously. It’s possible to handle the request asynchornously by calling ref on password, then returning True and call tls_client_certificate_password_request_complete later after setting the password on password. Note that this signal is not emitted if tls_interaction was set.

Parameters:

tls_password – the TlsPassword

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.

starting() → None

Emitted just before a message is sent.

wrote_body() → None

Emitted immediately after writing the complete body for a message.

wrote_body_data(chunk_size: int) → None

Emitted immediately after writing a portion of the message body to the network.

Parameters:

chunk_size – the number of bytes written

wrote_headers() → None

Emitted immediately after writing the request headers for a message.