Message
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 touri
.- 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 givenencoded_form
touri
viamethod
. Ifmethod
is “GET”, it will include the form data intouri
’s query field, and ifmethod
is “POST” or “PUT”, it will be set as request body.This function takes the ownership of
encoded_form
, that will be released withfree
when no longer in use. See alsoform_encode
,form_encode_hash
andform_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 sendmultipart
touri_string
via POST.- Parameters:
uri_string – the destination endpoint
multipart – a
Multipart
Methods
- class Message
- add_flags(flags: MessageFlags) None
Adds
flags
to the set ofmsg
’s flags.- Parameters:
flags – a set of
MessageFlags
values
- disable_feature(feature_type: type) None
Disables the actions of
SessionFeature
’s with the givenfeature_type
(or a subclass of that type) onmsg
.msg
is processed as though the feature(s) hadn’t been added to the session. Eg, passingSOUP_TYPE_CONTENT_SNIFFER
forfeature_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 aSessionFeature
- 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_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.
Returns if this message is set as a top level navigation.
Used for same-site policy checks.
- get_metrics() MessageMetrics | None
Get the
MessageMetrics
ofmsg
.If the flag
COLLECT_METRICS
is not enabled formsg
this will returnNone
.
- get_priority() MessagePriority
Retrieves the
MessagePriority
.If not set this value defaults to
SOUP_MESSAGE_PRIORITY_NORMAL
.
- 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 aProxyAddress
. Ifremote_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_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 withmsg
’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 ofaccept_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.
- is_feature_disabled(feature_type: type) bool
Get whether
SessionFeature
’s of the givenfeature_type
(or a subclass of that type) are disabled onmsg
.See
disable_feature
.- Parameters:
feature_type – the
Type
of aSessionFeature
- is_keepalive() bool
Determines whether or not
msg
’s connection can be kept alive for further requests after processingmsg
.The result is based on the HTTP version, Connection header, etc.
- query_flags(flags: MessageFlags) bool
Queries if
flags
are present in the set ofmsg
’s flags.- Parameters:
flags – a set of
MessageFlags
values
- remove_flags(flags: MessageFlags) None
Removes
flags
from the set ofmsg
’s flags.- Parameters:
flags – a set of
MessageFlags
values
- set_first_party(first_party: Uri) None
Sets
first_party
as the main documentUri
formsg
.For details of when and how this is used refer to the documentation for
CookieJarAcceptPolicy
.- Parameters:
first_party – the
Uri
for themsg
’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 sendOPTIONS *
to a server.When set to
True
, the path ofuri
will be ignored andmethod
set to%SOUP_METHOD_OPTIONS
.- Parameters:
is_options_ping – the value to set
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 tomethod
.- 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
isNone
andstream
is notNone
the Content-Type header will not be changed if present. The request body needs to be set again in casemsg
is restarted (in case of redirection or authentication).- Parameters:
content_type – MIME Content-Type of the body, or
None
if unknownstream – a
InputStream
to read the request body fromcontent_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
fromBytes
.If
content_type
isNone
andbytes
is notNone
the Content-Type header will not be changed if present. The request body needs to be set again in casemsg
is restarted (in case of redirection or authentication).- Parameters:
content_type – MIME Content-Type of the body, or
None
if unknownbytes – 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 formsg
.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 themsg
’s site for cookies
- set_tls_client_certificate(certificate: TlsCertificate | None = None) None
Sets the
certificate
to be used bymsg
’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. Ifcertificate
isNone
the handshake will continue without providing a GTlsCertificate. Note that theTlsCertificate
set by this function will be ignored iftls_interaction
is notNone
.- Parameters:
certificate – the
TlsCertificate
to set, orNone
- set_uri(uri: Uri) None
Sets
msg
’s URI touri
.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 notifymsg
that theTlsPassword
has already been updated.
Properties
- class Message
-
- 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 sendOPTIONS *
to a server. When set toTrue
, the path ofuri
will be ignored andmethod
set to%SOUP_METHOD_OPTIONS
.
Set when the message is navigating between top level domains.
- props.priority: MessagePriority
Sets the priority of the
Message
. Seeset_priority
for further details.
- 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.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.
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 accepttls_certificate
despitetls_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
onauth
. If these credentials fail, the signal will be emitted again, withretrying
set toTrue
, which will continue until you return without callingauthenticate
onauth
.Note that this may be emitted before
msg
’s body has been fully read.You can authenticate
auth
asynchronously by callingref
onauth
and returningTrue
. The operation will complete once eitherauthenticate
orcancel
are called.- Parameters:
auth – the
Auth
to authenticateretrying –
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
, andtype
isNone
.- Parameters:
type – the content type that we got from sniffing
params – a
HashTable
with the parameters
- 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
andadd_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, andmsg
’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 agot_body
handler rather than agot_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, andmsg
’s connection will be closed.
- hsts_enforced() None
Emitted when
HSTSEnforcer
has upgraded the protocol formsg
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 whilemsg
“owns” the connection; ifmsg
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 theNEW_CONNECTION
flag on it.)See
event
for more information on what the different values ofevent
correspond to, and whatconnection
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 whentls_connection
requests a certificate from the client.You can set the client certificate by calling
set_tls_client_certificate
and returningTrue
. It’s possible to handle the request asynchornously by returningTrue
and callset_tls_client_certificate
later once the certificate is available. Note that this signal is not emitted iftls_interaction
was set, or ifset_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 whentls_connection
requests a certificate password from the client.You can set the certificate password on
password
, then calltls_client_certificate_password_request_complete
and returnTrue
to handle the signal synchronously. It’s possible to handle the request asynchornously by callingref
onpassword
, then returningTrue
and calltls_client_certificate_password_request_complete
later after setting the password onpassword
. Note that this signal is not emitted iftls_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.