Soup.Session¶

Subclasses:	`Soup.SessionAsync`, `Soup.SessionSync`

Methods¶

Inherited:	GObject.Object (37)
Structs:	GObject.ObjectClass (5)

class	`new` ()
	`abort` ()
	`add_feature` (feature)
	`add_feature_by_type` (feature_type)
	`cancel_message` (msg, status_code)
	`connect_async` (uri, cancellable, progress_callback, callback, *user_data)
	`connect_finish` (result)
	`get_async_context` ()
	`get_feature` (feature_type)
	`get_feature_for_message` (feature_type, msg)
	`get_features` (feature_type)
	`has_feature` (feature_type)
	`pause_message` (msg)
	`prefetch_dns` (hostname, cancellable, callback, *user_data)
	`prepare_for_uri` (uri)
	`queue_message` (msg, callback, *user_data)
	`redirect_message` (msg)
	`remove_feature` (feature)
	`remove_feature_by_type` (feature_type)
	`request` (uri_string)
	`request_http` (method, uri_string)
	`request_http_uri` (method, uri)
	`request_uri` (uri)
	`requeue_message` (msg)
	`send` (msg, cancellable)
	`send_async` (msg, cancellable, callback, *user_data)
	`send_finish` (result)
	`send_message` (msg)
	`steal_connection` (msg)
	`unpause_message` (msg)
	`websocket_connect_async` (msg, origin, protocols, cancellable, callback, *user_data)
	`websocket_connect_finish` (result)
	`would_redirect` (msg)

Virtual Methods¶

Inherited:	GObject.Object (7)

	`do_auth_required` (msg, auth, retrying)
	`do_authenticate` (msg, auth, retrying)
	`do_cancel_message` (msg, status_code)
	`do_flush_queue` ()
	`do_kick` ()
	`do_queue_message` (msg, callback, *user_data)
	`do_request_started` (msg, socket)
	`do_requeue_message` (msg)
	`do_send_message` (msg)

Properties¶

Name	Type	Flags	Short Description
`accept-language`	`str`	r/w	Accept-Language string
`accept-language-auto`	`bool`	r/w	Accept-Language automatic mode
`async-context`	`int`	r/w/co	The `GLib.MainContext` to dispatch async I/O in
`http-aliases`	[`str`]	r/w	URI schemes that are considered aliases for ‘http’
`https-aliases`	[`str`]	r/w	URI schemes that are considered aliases for ‘https’
`idle-timeout`	`int`	r/w	Connection lifetime when idle
`local-address`	`Soup.Address`	r/w/co	Address of local end of socket
`max-conns`	`int`	r/w	The maximum number of connections that the session can open at once
`max-conns-per-host`	`int`	r/w	The maximum number of connections that the session can open at once to a given host
`proxy-resolver`	`Gio.ProxyResolver`	r/w	The `Gio.ProxyResolver` to use for this session
`proxy-uri`	`Soup.URI`	d/r/w	The HTTP Proxy to use for this session `deprecated`
`ssl-ca-file`	`str`	d/r/w	File containing SSL CA certificates `deprecated`
`ssl-strict`	`bool`	r/w	Whether certificate errors should be considered a connection error
`ssl-use-system-ca-file`	`bool`	r/w	Use the system certificate database
`timeout`	`int`	r/w	Value in seconds to timeout a blocking I/O
`tls-database`	`Gio.TlsDatabase`	r/w	TLS database to use
`tls-interaction`	`Gio.TlsInteraction`	r/w	TLS interaction to use
`use-ntlm`	`bool`	d/r/w	Whether or not to use NTLM authentication `deprecated`
`use-thread-context`	`bool`	r/w	Whether to use thread-default main contexts
`user-agent`	`str`	r/w	User-Agent string

Signals¶

Inherited:	GObject.Object (1)

Name	Short Description
`authenticate`	Emitted when the session requires authentication.
`connection-created`	Emitted when a new connection is created.
`request-queued`	Emitted when a request is queued on session.
`request-started`	Emitted just before a request is sent. `deprecated`
`request-unqueued`	Emitted when a request is removed from session’s queue, indicating that session is done with it.
`tunneling`	Emitted when an SSL tunnel is being created on a proxy connection.

Fields¶

Inherited:	GObject.Object (1)

Name	Type	Access	Description
parent	`GObject.Object`	r

Class Details¶

class Soup.Session(**kwargs)¶

Bases:	`GObject.Object`
Abstract:	No
Structure:	`Soup.SessionClass`

classmethod new()¶

Returns:	the new session.
Return type:	`Soup.Session`

Creates a Soup.Session with the default options.

New in version 2.42.

abort()¶

Cancels all pending requests in self and closes all idle persistent connections.

The message cancellation has the same semantics as with Soup.Session.cancel_message(); asynchronous requests on a Soup.SessionAsync will have their callback called before Soup.Session.abort() returns. Requests on a plain Soup.Session will not.

add_feature(feature)¶

Parameters:	feature (`Soup.SessionFeature`) – an object that implements `Soup.SessionFeature`

Adds feature’s functionality to self. You can also add a feature to the session at construct time by using the Soup.SESSION_ADD_FEATURE property.

See the main Soup.Session documentation for information on what features are present in sessions by default.

New in version 2.24.

add_feature_by_type(feature_type)¶

Parameters:	feature_type (`GObject.GType`) – a `GObject.GType`

If feature_type is the type of a class that implements Soup.SessionFeature, this creates a new feature of that type and adds it to self as with Soup.Session.add_feature(). You can use this when you don’t need to customize the new feature in any way.

If feature_type is not a Soup.SessionFeature type, this gives each existing feature on self the chance to accept feature_type as a “subfeature”. This can be used to add new Soup.Auth or Soup.Request types, for instance.

You can also add a feature to the session at construct time by using the Soup.SESSION_ADD_FEATURE_BY_TYPE property.

See the main Soup.Session documentation for information on what features are present in sessions by default.

New in version 2.24.

cancel_message(msg, status_code)¶

Parameters:	msg (`Soup.Message`) – the message to cancel status_code (`int`) – status code to set on msg (generally `Soup.Status.CANCELLED`)

Causes self to immediately finish processing msg (regardless of its current state) with a final status_code of status_code. You may call this at any time after handing msg off to self; if self has started sending the request but has not yet received the complete response, then it will close the request’s connection. Note that with requests that have side effects (eg, POST, PUT, DELETE) it is possible that you might cancel the request after the server acts on it, but before it returns a response, leaving the remote resource in an unknown state.

If the message is cancelled while its response body is being read, then the response body in msg will be left partially-filled-in. The response headers, on the other hand, will always be either empty or complete.

Beware that with the deprecated Soup.SessionAsync, messages queued with Soup.Session.queue_message() will have their callbacks invoked before Soup.Session.cancel_message() returns. The plain Soup.Session does not have this behavior; cancelling an asynchronous message will merely queue its callback to be run after returning to the main loop.

connect_async(uri, cancellable, progress_callback, callback, *user_data)¶

Parameters:

uri (Soup.URI) – a Soup.URI to connect to
cancellable (Gio.Cancellable or None) – a Gio.Cancellable
progress_callback (Soup.SessionConnectProgressCallback or None) – a Soup.SessionConnectProgressCallback which will be called for every network event that occurs during the connection.
callback (Gio.AsyncReadyCallback or None) – the callback to invoke when the operation finishes
user_data (object or None) – data for progress_callback and callback

Start a connection to uri. The operation can be monitored by providing a progress_callback and finishes when the connection is done or an error ocurred.

Call Soup.Session.connect_finish() to get the Gio.IOStream to communicate with the server.

New in version 2.62.

connect_finish(result)¶

Parameters:	result (`Gio.AsyncResult`) – the `Gio.AsyncResult` passed to your callback
Raises:	`GLib.Error`
Returns:	a new `Gio.IOStream`, or `None` on error.
Return type:	`Gio.IOStream`

Gets the Gio.IOStream created for the connection to communicate with the server.

New in version 2.62.

get_async_context()¶

Returns:	self’s `GLib.MainContext`, which may be `None`
Return type:	`GLib.MainContext` or `None`

Gets self’s Soup.Session :async-context. This does not add a ref to the context, so you will need to ref it yourself if you want it to outlive its session.

For a modern Soup.Session, this will always just return the thread-default GLib.MainContext, and so is not especially useful.

get_feature(feature_type)¶

Parameters:	feature_type (`GObject.GType`) – the `GObject.GType` of the feature to get
Returns:	a `Soup.SessionFeature`, or `None`. The feature is owned by self.
Return type:	`Soup.SessionFeature` or `None`

Gets the first feature in self of type feature_type. For features where there may be more than one feature of a given type, use Soup.Session.get_features().

New in version 2.26.

get_feature_for_message(feature_type, msg)¶

Parameters:	feature_type (`GObject.GType`) – the `GObject.GType` of the feature to get msg (`Soup.Message`) – a `Soup.Message`
Returns:	a `Soup.SessionFeature`, or `None`. The feature is owned by self.
Return type:	`Soup.SessionFeature` or `None`

Gets the first feature in self of type feature_type, provided that it is not disabled for msg. As with Soup.Session.get_feature(), this should only be used for features where feature_type is only expected to match a single feature. In particular, if there are two matching features, and the first is disabled on msg, and the second is not, then this will return None, not the second feature.

New in version 2.28.

get_features(feature_type)¶

Parameters:	feature_type (`GObject.GType`) – the `GObject.GType` of the class of features to get
Returns:	a list of features. You must free the list, but not its contents
Return type:	[`Soup.SessionFeature`]

Generates a list of self’s features of type feature_type. (If you want to see all features, you can pass %SOUP_TYPE_SESSION_FEATURE for feature_type.)

New in version 2.26.

has_feature(feature_type)¶

Parameters:	feature_type (`GObject.GType`) – the `GObject.GType` of the class of features to check for
Returns:	`True` or `False`
Return type:	`bool`

Tests if self has at a feature of type feature_type (which can be the type of either a Soup.SessionFeature, or else a subtype of some class managed by another feature, such as Soup.Auth or Soup.Request).

New in version 2.42.

pause_message(msg)¶

Parameters:	msg (`Soup.Message`) – a `Soup.Message` currently running on self

Pauses HTTP I/O on msg. Call Soup.Session.unpause_message() to resume I/O.

This may only be called for asynchronous messages (those sent on a Soup.SessionAsync or using Soup.Session.queue_message()).

prefetch_dns(hostname, cancellable, callback, *user_data)¶

Parameters:	hostname (`str`) – a hostname to be resolved cancellable (`Gio.Cancellable` or `None`) – a `Gio.Cancellable` object, or `None` callback (`Soup.AddressCallback` or `None`) – callback to call with the result, or `None` user_data (`object` or `None`) – data for callback

Tells self that an URI from the given hostname may be requested shortly, and so the session can try to prepare by resolving the domain name in advance, in order to work more quickly once the URI is actually requested.

If cancellable is non-None, it can be used to cancel the resolution. callback will still be invoked in this case, with a status of Soup.Status.CANCELLED.

New in version 2.38.

prepare_for_uri(uri)¶

Parameters:	uri (`Soup.URI`) – a `Soup.URI` which may be required

Tells self that uri may be requested shortly, and so the session can try to prepare (resolving the domain name, obtaining proxy address, etc.) in order to work more quickly once the URI is actually requested.

New in version 2.30.

Deprecated since version 2.38: use Soup.Session.prefetch_dns() instead

queue_message(msg, callback, *user_data)¶

Parameters:	msg (`Soup.Message`) – the message to queue callback (`Soup.SessionCallback` or `None`) – a `Soup.SessionCallback` which will be called after the message completes or when an unrecoverable error occurs. user_data (`object` or `None`) – a pointer passed to callback.

Queues the message msg for asynchronously sending the request and receiving a response in the current thread-default GLib.MainContext. If msg has been processed before, any resources related to the time it was last sent are freed.

Upon message completion, the callback specified in callback will be invoked. If after returning from this callback the message has not been requeued, msg will be unreffed.

(The behavior above applies to a plain Soup.Session; if you are using Soup.SessionAsync or Soup.SessionSync, then the GLib.MainContext that is used depends on the settings of Soup.Session :async-context and Soup.Session :use-thread-context, and for Soup.SessionSync, the message will actually be sent and processed in another thread, with only the final callback occurring in the indicated GLib.MainContext.)

Contrast this method with Soup.Session.send_async(), which also asynchronously sends a message, but returns before reading the response body, and allows you to read the response via a Gio.InputStream.

redirect_message(msg)¶

Parameters:	msg (`Soup.Message`) – a `Soup.Message` that has received a 3xx response
Returns:	`True` if a redirection was applied, `False` if not (eg, because there was no Location header, or it could not be parsed).
Return type:	`bool`

Updates msg’s URI according to its status code and “Location” header, and requeues it on self. Use this when you have set Soup.MessageFlags.NO_REDIRECT on a message, but have decided to allow a particular redirection to occur, or if you want to allow a redirection that Soup.Session will not perform automatically (eg, redirecting a non-safe method such as DELETE).

If msg’s status code indicates that it should be retried as a GET request, then msg will be modified accordingly.

If msg has already been redirected too many times, this will cause it to fail with Soup.Status.TOO_MANY_REDIRECTS.

New in version 2.38.

remove_feature(feature)¶

Parameters:	feature (`Soup.SessionFeature`) – a feature that has previously been added to self

Removes feature’s functionality from self.

New in version 2.24.

remove_feature_by_type(feature_type)¶

Parameters:	feature_type (`GObject.GType`) – a `GObject.GType`

Removes all features of type feature_type (or any subclass of feature_type) from self. You can also remove standard features from the session at construct time by using the Soup.SESSION_REMOVE_FEATURE_BY_TYPE property.

New in version 2.24.

request(uri_string)¶

Parameters:	uri_string (`str`) – a URI, in string form
Raises:	`GLib.Error`
Returns:	a new `Soup.Request`, or `None` on error.
Return type:	`Soup.Request`

Creates a Soup.Request for retrieving uri_string.

New in version 2.42.

request_http(method, uri_string)¶

Parameters:	method (`str`) – an HTTP method uri_string (`str`) – a URI, in string form
Raises:	`GLib.Error`
Returns:	a new `Soup.RequestHTTP`, or `None` on error.
Return type:	`Soup.RequestHTTP`

Creates a Soup.Request for retrieving uri_string, which must be an “http” or “https” URI (or another protocol listed in self’s Soup.Session :http-aliases or Soup.Session :https-aliases).

New in version 2.42.

request_http_uri(method, uri)¶

Parameters:	method (`str`) – an HTTP method uri (`Soup.URI`) – a `Soup.URI` representing the URI to retrieve
Raises:	`GLib.Error`
Returns:	a new `Soup.RequestHTTP`, or `None` on error.
Return type:	`Soup.RequestHTTP`

Creates a Soup.Request for retrieving uri, which must be an “http” or “https” URI (or another protocol listed in self’s Soup.Session :http-aliases or Soup.Session :https-aliases).

New in version 2.42.

request_uri(uri)¶

Parameters:	uri (`Soup.URI`) – a `Soup.URI` representing the URI to retrieve
Raises:	`GLib.Error`
Returns:	a new `Soup.Request`, or `None` on error.
Return type:	`Soup.Request`

Creates a Soup.Request for retrieving uri.

New in version 2.42.

requeue_message(msg)¶

Parameters:	msg (`Soup.Message`) – the message to requeue

This causes msg to be placed back on the queue to be attempted again.

send(msg, cancellable)¶

Parameters:	msg (`Soup.Message`) – a `Soup.Message` cancellable (`Gio.Cancellable` or `None`) – a `Gio.Cancellable`
Raises:	`GLib.Error`
Returns:	a `Gio.InputStream` for reading the response body, or `None` on error.
Return type:	`Gio.InputStream`

Synchronously sends msg and waits for the beginning of a response. On success, a Gio.InputStream will be returned which you can use to read the response body. (“Success” here means only that an HTTP response was received and understood; it does not necessarily mean that a 2xx class status code was received.)

If non-None, cancellable can be used to cancel the request; Soup.Session.send() will return a Gio.IOErrorEnum.CANCELLED error. Note that with requests that have side effects (eg, POST, PUT, DELETE) it is possible that you might cancel the request after the server acts on it, but before it returns a response, leaving the remote resource in an unknown state.

If msg is requeued due to a redirect or authentication, the initial (3xx/401/407) response body will be suppressed, and Soup.Session.send() will only return once a final response has been received.

Contrast this method with Soup.Session.send_message(), which also synchronously sends a Soup.Message, but doesn’t return until the response has been completely read.

(Note that this method cannot be called on the deprecated Soup.SessionAsync subclass.)

New in version 2.42.

send_async(msg, cancellable, callback, *user_data)¶

Parameters:	msg (`Soup.Message`) – a `Soup.Message` cancellable (`Gio.Cancellable` or `None`) – a `Gio.Cancellable` callback (`Gio.AsyncReadyCallback` or `None`) – the callback to invoke user_data (`object` or `None`) – data for callback

Asynchronously sends msg and waits for the beginning of a response. When callback is called, then either msg has been sent, and its response headers received, or else an error has occurred. Call Soup.Session.send_finish() to get a Gio.InputStream for reading the response body.

See Soup.Session.send() for more details on the general semantics.

Contrast this method with Soup.Session.queue_message(), which also asynchronously sends a Soup.Message, but doesn’t invoke its callback until the response has been completely read.

(Note that this method cannot be called on the deprecated Soup.SessionSync subclass, and can only be called on Soup.SessionAsync if you have set the Soup.Session :use-thread-context property.)

New in version 2.42.

send_finish(result)¶

Parameters:	result (`Gio.AsyncResult`) – the `Gio.AsyncResult` passed to your callback
Raises:	`GLib.Error`
Returns:	a `Gio.InputStream` for reading the response body, or `None` on error.
Return type:	`Gio.InputStream`

Gets the response to a Soup.Session.send_async() call and (if successful), returns a Gio.InputStream that can be used to read the response body.

New in version 2.42.

send_message(msg)¶

Parameters:	msg (`Soup.Message`) – the message to send
Returns:	the HTTP status code of the response
Return type:	`int`

Synchronously send msg. This call will not return until the transfer is finished successfully or there is an unrecoverable error.

Unlike with Soup.Session.queue_message(), msg is not freed upon return.

(Note that if you call this method on a Soup.SessionAsync, it will still use asynchronous I/O internally, running the glib main loop to process the message, which may also cause other events to be processed.)

Contrast this method with Soup.Session.send(), which also synchronously sends a message, but returns before reading the response body, and allows you to read the response via a Gio.InputStream.

steal_connection(msg)¶

Parameters:	msg (`Soup.Message`) – the message whose connection is to be stolen
Returns:	the `Gio.IOStream` formerly associated with msg (or `None` if msg was no longer associated with a connection). No guarantees are made about what kind of `Gio.IOStream` is returned.
Return type:	`Gio.IOStream`

“Steals” the HTTP connection associated with msg from self. This happens immediately, regardless of the current state of the connection, and msg’s callback will not be called. You can steal the connection from a Soup.Message signal handler if you need to wait for part or all of the response to be received first.

Calling this function may cause msg to be freed if you are not holding any other reference to it.

New in version 2.50.

unpause_message(msg)¶

Parameters:	msg (`Soup.Message`) – a `Soup.Message` currently running on self

Resumes HTTP I/O on msg. Use this to resume after calling Soup.Session.pause_message().

If msg is being sent via blocking I/O, this will resume reading or writing immediately. If msg is using non-blocking I/O, then reading or writing won’t resume until you return to the main loop.

This may only be called for asynchronous messages (those sent on a Soup.SessionAsync or using Soup.Session.queue_message()).

websocket_connect_async(msg, origin, protocols, cancellable, callback, *user_data)¶

Parameters:

msg (Soup.Message) – Soup.Message indicating the WebSocket server to connect to
origin (str or None) – origin of the connection
protocols ([str] or None) – a None-terminated array of protocols supported
cancellable (Gio.Cancellable or None) – a Gio.Cancellable
callback (Gio.AsyncReadyCallback or None) – the callback to invoke
user_data (object or None) – data for callback

Asynchronously creates a Soup.WebsocketConnection to communicate with a remote server.

All necessary WebSocket-related headers will be added to msg, and it will then be sent and asynchronously processed normally (including handling of redirection and HTTP authentication).

If the server returns “101 Switching Protocols”, then msg’s status code and response headers will be updated, and then the WebSocket handshake will be completed. On success, Soup.Session.websocket_connect_finish() will return a new Soup.WebsocketConnection. On failure it will return a GLib.Error.

If the server returns a status other than “101 Switching Protocols”, then msg will contain the complete response headers and body from the server’s response, and Soup.Session.websocket_connect_finish() will return Soup.WebsocketError.NOT_WEBSOCKET.

New in version 2.50.

websocket_connect_finish(result)¶

Parameters:	result (`Gio.AsyncResult`) – the `Gio.AsyncResult` passed to your callback
Raises:	`GLib.Error`
Returns:	a new `Soup.WebsocketConnection`, or `None` on error.
Return type:	`Soup.WebsocketConnection`

Gets the Soup.WebsocketConnection response to a Soup.Session.websocket_connect_async() call and (if successful), returns a Soup.WebsocketConnection that can be used to communicate with the server.

New in version 2.50.

would_redirect(msg)¶

Parameters:	msg (`Soup.Message`) – a `Soup.Message` that has response headers
Returns:	whether msg would be redirected
Return type:	`bool`

Checks if msg contains a response that would cause self to redirect it to a new URL (ignoring msg’s Soup.MessageFlags.NO_REDIRECT flag, and the number of times it has already been redirected).

New in version 2.38.

do_auth_required(msg, auth, retrying) virtual¶

Parameters:	msg (`Soup.Message`) – auth (`Soup.Auth`) – retrying (`bool`) –

do_authenticate(msg, auth, retrying) virtual¶

Parameters:	msg (`Soup.Message`) – auth (`Soup.Auth`) – retrying (`bool`) –

do_cancel_message(msg, status_code) virtual¶

Parameters:	msg (`Soup.Message`) – the message to cancel status_code (`int`) – status code to set on msg (generally `Soup.Status.CANCELLED`)

Causes session to immediately finish processing msg (regardless of its current state) with a final status_code of status_code. You may call this at any time after handing msg off to session; if session has started sending the request but has not yet received the complete response, then it will close the request’s connection. Note that with requests that have side effects (eg, POST, PUT, DELETE) it is possible that you might cancel the request after the server acts on it, but before it returns a response, leaving the remote resource in an unknown state.

If the message is cancelled while its response body is being read, then the response body in msg will be left partially-filled-in. The response headers, on the other hand, will always be either empty or complete.

Beware that with the deprecated Soup.SessionAsync, messages queued with Soup.Session.queue_message() will have their callbacks invoked before Soup.Session.cancel_message() returns. The plain Soup.Session does not have this behavior; cancelling an asynchronous message will merely queue its callback to be run after returning to the main loop.

do_flush_queue() virtual¶

do_kick() virtual¶

do_queue_message(msg, callback, *user_data) virtual¶

Parameters:	msg (`Soup.Message`) – the message to queue callback (`Soup.SessionCallback` or `None`) – a `Soup.SessionCallback` which will be called after the message completes or when an unrecoverable error occurs. user_data (`object` or `None`) – a pointer passed to callback.

Queues the message msg for asynchronously sending the request and receiving a response in the current thread-default GLib.MainContext. If msg has been processed before, any resources related to the time it was last sent are freed.

Upon message completion, the callback specified in callback will be invoked. If after returning from this callback the message has not been requeued, msg will be unreffed.

(The behavior above applies to a plain Soup.Session; if you are using Soup.SessionAsync or Soup.SessionSync, then the GLib.MainContext that is used depends on the settings of Soup.Session :async-context and Soup.Session :use-thread-context, and for Soup.SessionSync, the message will actually be sent and processed in another thread, with only the final callback occurring in the indicated GLib.MainContext.)

Contrast this method with Soup.Session.send_async(), which also asynchronously sends a message, but returns before reading the response body, and allows you to read the response via a Gio.InputStream.

do_request_started(msg, socket) virtual¶

Parameters:	msg (`Soup.Message`) – socket (`Soup.Socket`) –

do_requeue_message(msg) virtual¶

Parameters:	msg (`Soup.Message`) – the message to requeue

This causes msg to be placed back on the queue to be attempted again.

do_send_message(msg) virtual¶

Parameters:	msg (`Soup.Message`) – the message to send
Returns:	the HTTP status code of the response
Return type:	`int`

Synchronously send msg. This call will not return until the transfer is finished successfully or there is an unrecoverable error.

Unlike with Soup.Session.queue_message(), msg is not freed upon return.

(Note that if you call this method on a Soup.SessionAsync, it will still use asynchronous I/O internally, running the glib main loop to process the message, which may also cause other events to be processed.)

Contrast this method with Soup.Session.send(), which also synchronously sends a message, but returns before reading the response body, and allows you to read the response via a Gio.InputStream.

Signal Details¶

Soup.Session.signals.authenticate(session, msg, auth, retrying)¶

Signal Name:	`authenticate`
Flags:	`RUN_FIRST`
Parameters:	session (`Soup.Session`) – The object which received the signal msg (`Soup.Message`) – the `Soup.Message` being sent auth (`Soup.Auth`) – the `Soup.Auth` to authenticate retrying (`bool`) – `True` if this is the second (or later) attempt

Emitted when the session requires authentication. If credentials are available call Soup.Auth.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 Soup.Auth.authenticate() on auth.

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

If you call Soup.Session.pause_message() on msg before returning, then you can authenticate auth asynchronously (as long as you GObject.Object.ref() it to make sure it doesn’t get destroyed), and then unpause msg when you are ready for it to continue.

Soup.Session.signals.connection_created(session, connection)¶

Signal Name:	`connection-created`
Flags:	`RUN_FIRST`
Parameters:	session (`Soup.Session`) – The object which received the signal connection (`GObject.Object`) – the connection

Emitted when a new connection is created. This is an internal signal intended only to be used for debugging purposes, and may go away in the future.

New in version 2.30.

Soup.Session.signals.request_queued(session, msg)¶

Signal Name:	`request-queued`
Flags:	`RUN_FIRST`
Parameters:	session (`Soup.Session`) – The object which received the signal msg (`Soup.Message`) – the request that was queued

Emitted when a request is queued on session. (Note that “queued” doesn’t just mean Soup.Session.queue_message(); Soup.Session.send_message() implicitly queues the message as well.)

When sending a request, first #SoupSession::request_queued is emitted, indicating that the session has become aware of the request.

Once a connection is available to send the request on, the session emits #SoupSession::request_started. Then, various Soup.Message signals are emitted as the message is processed. If the message is requeued, it will emit Soup.Message ::restarted, which will then be followed by another #SoupSession::request_started and another set of Soup.Message signals when the message is re-sent.

Eventually, the message will emit Soup.Message ::finished. Normally, this signals the completion of message processing. However, it is possible that the application will requeue the message from the “finished” handler (or equivalently, from the Soup.Session.queue_message() callback). In that case, the process will loop back to #SoupSession::request_started.

Eventually, a message will reach “finished” and not be requeued. At that point, the session will emit #SoupSession::request_unqueued to indicate that it is done with the message.

To sum up: #SoupSession::request_queued and #SoupSession::request_unqueued are guaranteed to be emitted exactly once, but #SoupSession::request_started and Soup.Message ::finished (and all of the other Soup.Message signals) may be invoked multiple times for a given message.

New in version 2.24.

Soup.Session.signals.request_started(session, msg, socket)¶

Signal Name:	`request-started`
Flags:	`RUN_FIRST`
Parameters:	session (`Soup.Session`) – The object which received the signal msg (`Soup.Message`) – the request being sent socket (`Soup.Socket`) – the socket the request is being sent on

Emitted just before a request is sent. See #SoupSession::request_queued for a detailed description of the message lifecycle within a session.

Deprecated since version 2.50.: Use Soup.Message ::starting instead.

Soup.Session.signals.request_unqueued(session, msg)¶

Signal Name:	`request-unqueued`
Flags:	`RUN_FIRST`
Parameters:	session (`Soup.Session`) – The object which received the signal msg (`Soup.Message`) – the request that was unqueued

Emitted when a request is removed from session’s queue, indicating that session is done with it. See #SoupSession::request_queued for a detailed description of the message lifecycle within a session.

New in version 2.24.

Soup.Session.signals.tunneling(session, connection)¶

Signal Name:	`tunneling`
Flags:	`RUN_FIRST`
Parameters:	session (`Soup.Session`) – The object which received the signal connection (`GObject.Object`) – the connection

Emitted when an SSL tunnel is being created on a proxy connection. This is an internal signal intended only to be used for debugging purposes, and may go away in the future.

New in version 2.30.

Property Details¶

Soup.Session.props.accept_language¶

Name:	`accept-language`
Type:	`str`
Default Value:	`None`
Flags:	`READABLE`, `WRITABLE`

If non-None, the value to use for the “Accept-Language” header on Soup.Message s sent from this session.

Setting this will disable Soup.Session :accept-language-auto.

New in version 2.30.

Soup.Session.props.accept_language_auto¶

Name:	`accept-language-auto`
Type:	`bool`
Default Value:	`False`
Flags:	`READABLE`, `WRITABLE`

If True, Soup.Session will automatically set the string for the “Accept-Language” header on every Soup.Message sent, based on the return value of GLib.get_language_names().

Setting this will override any previous value of Soup.Session :accept-language.

New in version 2.30.

Soup.Session.props.async_context¶

Name:	`async-context`
Type:	`int`
Default Value:	`None`
Flags:	`READABLE`, `WRITABLE`, `CONSTRUCT_ONLY`

The GLib.MainContext that miscellaneous session-related asynchronous callbacks are invoked on. (Eg, setting Soup.Session :idle-timeout will add a timeout source on this context.)

For a plain Soup.Session, this property is always set to the GLib.MainContext that is the thread-default at the time the session was created, and cannot be overridden. For the deprecated Soup.Session subclasses, the default value is None, meaning to use the global default GLib.MainContext.

If Soup.Session :use-thread-context is False, this context will also be used for asynchronous HTTP I/O.

Soup.Session.props.http_aliases¶

Name:	`http-aliases`
Type:	[`str`]
Default Value:	`[]`
Flags:	`READABLE`, `WRITABLE`

A None-terminated array of URI schemes that should be considered to be aliases for “http”. Eg, if this included "dav", than a URI of dav://example.com/path would be treated identically to http://example.com/path.

In a plain Soup.Session, the default value is None, meaning that only “http” is recognized as meaning “http”. In Soup.SessionAsync and Soup.SessionSync, for backward compatibility, the default value is an array containing the single element "*", a special value which means that any scheme except “https” is considered to be an alias for “http”.

New in version 2.38.

Soup.Session.props.https_aliases¶

Name:	`https-aliases`
Type:	[`str`]
Default Value:	`[]`
Flags:	`READABLE`, `WRITABLE`

A comma-delimited list of URI schemes that should be considered to be aliases for “https”. See Soup.Session :http-aliases for more information.

The default value is None, meaning that no URI schemes are considered aliases for “https”.

New in version 2.38.

Soup.Session.props.idle_timeout¶

Name:	`idle-timeout`
Type:	`int`
Default Value:	`60`
Flags:	`READABLE`, `WRITABLE`

Connection lifetime (in seconds) when idle. Any connection left idle longer than this will be closed.

Although you can change this property at any time, it will only affect newly-created connections, not currently-open ones. You can call Soup.Session.abort() after setting this if you want to ensure that all future connections will have this timeout value.

Note that the default value of 60 seconds only applies to plain Soup.Sessions. If you are using Soup.SessionAsync or Soup.SessionSync, the default value is 0 (meaning idle connections will never time out).

New in version 2.24.

Soup.Session.props.local_address¶

Name:	`local-address`
Type:	`Soup.Address`
Default Value:	`None`
Flags:	`READABLE`, `WRITABLE`, `CONSTRUCT_ONLY`

Sets the Soup.Address to use for the client side of the connection.

Use this property if you want for instance to bind the local socket to a specific IP address.

New in version 2.42.

Soup.Session.props.max_conns¶

Name:	`max-conns`
Type:	`int`
Default Value:	`10`
Flags:	`READABLE`, `WRITABLE`

The maximum number of connections that the session can open at once

Soup.Session.props.max_conns_per_host¶

Name:	`max-conns-per-host`
Type:	`int`
Default Value:	`2`
Flags:	`READABLE`, `WRITABLE`

The maximum number of connections that the session can open at once to a given host

Soup.Session.props.proxy_resolver¶

Name:	`proxy-resolver`
Type:	`Gio.ProxyResolver`
Default Value:	`None`
Flags:	`READABLE`, `WRITABLE`

A Gio.ProxyResolver to use with this session. Setting this will clear the Soup.Session :proxy-uri property, and remove any SoupProxyURIResolver features that have been added to the session.

By default, in a plain Soup.Session, this is set to the default Gio.ProxyResolver, but you can set it to None if you don’t want to use proxies, or set it to your own Gio.ProxyResolver if you want to control what proxies get used.

New in version 2.42.

Soup.Session.props.proxy_uri¶

Name:	`proxy-uri`
Type:	`Soup.URI`
Default Value:	`None`
Flags:	`DEPRECATED`, `READABLE`, `WRITABLE`

A proxy to use for all http and https requests in this session. Setting this will clear the Soup.Session :proxy-resolver property, and remove any

SoupProxyURIResolver features that have been added to the session. Setting this property will also cancel all currently pending messages.

Note that Soup.Session will normally handle looking up the user’s proxy settings for you; you should only use Soup.Session :proxy-uri if you need to override the user’s normal proxy settings.

Also note that this proxy will be used for all requests; even requests to localhost. If you need more control over proxies, you can create a Gio.SimpleProxyResolver and set the Soup.Session :proxy-resolver property.

Deprecated since version 2.70: Use Soup.Session :proxy-resolver along with Gio.SimpleProxyResolver.

Soup.Session.props.ssl_ca_file¶

Name:	`ssl-ca-file`
Type:	`str`
Default Value:	`None`
Flags:	`DEPRECATED`, `READABLE`, `WRITABLE`

File containing SSL CA certificates.

If the specified file does not exist or cannot be read, then libsoup will print a warning, and then behave as though it had read in a empty CA file, meaning that all SSL certificates will be considered invalid.

Deprecated since version ???: use Soup.Session :ssl-use-system-ca-file, or else Soup.Session :tls-database with a Gio.TlsFileDatabase (which allows you to do explicit error handling).

Soup.Session.props.ssl_strict¶

Name:	`ssl-strict`
Type:	`bool`
Default Value:	`True`
Flags:	`READABLE`, `WRITABLE`

Normally, if Soup.Session :tls-database is set (including if it was set via Soup.Session :ssl-use-system-ca-file or Soup.Session :ssl-ca-file), then libsoup will reject any certificate that is invalid (ie, expired) or that is not signed by one of the given CA certificates, and the Soup.Message will fail with the status Soup.Status.SSL_FAILED.

If you set Soup.Session :ssl-strict to False, then all certificates will be accepted, and you will need to call Soup.Message.get_https_status() to distinguish valid from invalid certificates. (This can be used, eg, if you want to accept invalid certificates after giving some sort of warning.)

For a plain Soup.Session, if the session has no CA file or TLS database, and this property is True, then all certificates will be rejected. However, beware that the deprecated Soup.Session subclasses (Soup.SessionAsync and Soup.SessionSync) have the opposite behavior: if there is no CA file or TLS database, then all certificates are always accepted, and this property has no effect.

New in version 2.30.

Soup.Session.props.ssl_use_system_ca_file¶

Name:	`ssl-use-system-ca-file`
Type:	`bool`
Default Value:	`True`
Flags:	`READABLE`, `WRITABLE`

Setting this to True is equivalent to setting Soup.Session :tls-database to the default system CA database. (and likewise, setting Soup.Session :tls-database to the default database by hand will cause this property to become True).

Setting this to False (when it was previously True) will clear the Soup.Session :tls-database field.

See Soup.Session :ssl-strict for more information on how https certificate validation is handled.

Note that the default value of True only applies to plain Soup.Sessions. If you are using Soup.SessionAsync or Soup.SessionSync, the default value is False, for backward compatibility.

New in version 2.38.

Soup.Session.props.timeout¶

Name:	`timeout`
Type:	`int`
Default Value:	`0`
Flags:	`READABLE`, `WRITABLE`

The timeout (in seconds) for socket I/O operations (including connecting to a server, and waiting for a reply to an HTTP request).

Although you can change this property at any time, it will only affect newly-created connections, not currently-open ones. You can call Soup.Session.abort() after setting this if you want to ensure that all future connections will have this timeout value.

Note that the default value of 60 seconds only applies to plain Soup.Sessions. If you are using Soup.SessionAsync or Soup.SessionSync, the default value is 0 (meaning socket I/O will not time out).

Not to be confused with Soup.Session :idle-timeout (which is the length of time that idle persistent connections will be kept open).

Soup.Session.props.tls_database¶

Name:	`tls-database`
Type:	`Gio.TlsDatabase`
Default Value:	`None`
Flags:	`READABLE`, `WRITABLE`

Sets the Gio.TlsDatabase to use for validating SSL/TLS certificates.

Note that setting the Soup.Session :ssl-ca-file or Soup.Session :ssl-use-system-ca-file property will cause this property to be set to a Gio.TlsDatabase corresponding to the indicated file or system default.

See Soup.Session :ssl-strict for more information on how https certificate validation is handled.

If you are using a plain Soup.Session then Soup.Session :ssl-use-system-ca-file will be True by default, and so this property will be a copy of the system CA database. If you are using Soup.SessionAsync or Soup.SessionSync, this property will be None by default.

New in version 2.38.

Soup.Session.props.tls_interaction¶

Name:	`tls-interaction`
Type:	`Gio.TlsInteraction`
Default Value:	`None`
Flags:	`READABLE`, `WRITABLE`

A Gio.TlsInteraction object that will be passed on to any Gio.TlsConnections created by the session. (This can be used to provide client-side certificates, for example.)

New in version 2.48.

Soup.Session.props.use_ntlm¶

Name:	`use-ntlm`
Type:	`bool`
Default Value:	`False`
Flags:	`DEPRECATED`, `READABLE`, `WRITABLE`

Whether or not to use NTLM authentication.

Deprecated since version ???: use Soup.Session.add_feature_by_type() with #SOUP_TYPE_AUTH_NTLM.

Soup.Session.props.use_thread_context¶

Name:	`use-thread-context`
Type:	`bool`
Default Value:	`False`
Flags:	`READABLE`, `WRITABLE`

If True (which it always is on a plain Soup.Session), asynchronous HTTP requests in this session will run in whatever the thread-default GLib.MainContext is at the time they are started, rather than always occurring in Soup.Session :async-context.

New in version 2.38.

Soup.Session.props.user_agent¶

Name:	`user-agent`
Type:	`str`
Default Value:	`None`
Flags:	`READABLE`, `WRITABLE`

If non-None, the value to use for the “User-Agent” header on Soup.Message s sent from this session.

RFC 2616 says: “The User-Agent request-header field contains information about the user agent originating the request. This is for statistical purposes, the tracing of protocol violations, and automated recognition of user agents for the sake of tailoring responses to avoid particular user agent limitations. User agents SHOULD include this field with requests.”

The User-Agent header contains a list of one or more product tokens, separated by whitespace, with the most significant product token coming first. The tokens must be brief, ASCII, and mostly alphanumeric (although “-”, “_”, and “.” are also allowed), and may optionally include a “/” followed by a version string. You may also put comments, enclosed in parentheses, between or after the tokens.

If you set a #SoupSession:user_agent property that has trailing whitespace, Soup.Session will append its own product token (eg, “libsoup/2.3.2”) to the end of the header for you.