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 type of the None singleton.

props.flags: MessageFlags

The type of the None singleton.

props.http_version: HTTPVersion

The type of the None singleton.

props.is_options_ping: bool

The type of the None singleton.

props.is_top_level_navigation: bool

The type of the None singleton.

props.method: str

The type of the None singleton.

props.priority: MessagePriority

The type of the None singleton.

props.reason_phrase: str

The type of the None singleton.

props.remote_address: SocketAddress

The type of the None singleton.

props.request_headers: MessageHeaders

The type of the None singleton.

props.response_headers: MessageHeaders

The type of the None singleton.

props.site_for_cookies: Uri

The type of the None singleton.

props.status_code: int

The type of the None singleton.

props.tls_ciphersuite_name: str

The type of the None singleton.

props.tls_peer_certificate: TlsCertificate

The type of the None singleton.

props.tls_peer_certificate_errors: TlsCertificateFlags

The type of the None singleton.

props.tls_protocol_version: TlsProtocolVersion

The type of the None singleton.

props.uri: Uri

The type of the None singleton.

Signals

class Message.signals

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

The type of the None singleton.

Parameters:

• tls_peer_certificate – the peer’s TlsCertificate

• tls_peer_errors – the tls errors of tls_certificate

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

The type of the None singleton.

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

The type of the None singleton.

Parameters:

• type – the content type that we got from sniffing

• params – a HashTable with the parameters

finished() → None

The type of the None singleton.

got_body() → None

The type of the None singleton.

got_body_data(chunk_size: int) → None

The type of the None singleton.

Added in version 3.4.

Parameters:

chunk_size – the number of bytes read

got_headers() → None

The type of the None singleton.

got_informational() → None

The type of the None singleton.

hsts_enforced() → None

The type of the None singleton.

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

The type of the None singleton.

Parameters:

• event – the network event

• connection – the current state of the network connection

request_certificate(tls_connection: TlsClientConnection) → bool

The type of the None singleton.

Parameters:

tls_connection – the TlsClientConnection

request_certificate_password(tls_password: TlsPassword) → bool

The type of the None singleton.

Parameters:

tls_password – the TlsPassword

restarted() → None

The type of the None singleton.

starting() → None

The type of the None singleton.

wrote_body() → None

The type of the None singleton.

wrote_body_data(chunk_size: int) → None

The type of the None singleton.

Parameters:

chunk_size – the number of bytes written

wrote_headers() → None

The type of the None singleton.