Soup.Session¶

Subclasses:: None

Methods¶

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

class	`new` ()
	`abort` ()
	`add_feature` (feature)
	`add_feature_by_type` (feature_type)
	`get_accept_language` ()
	`get_accept_language_auto` ()
	`get_async_result_message` (result)
	`get_feature` (feature_type)
	`get_feature_for_message` (feature_type, msg)
	`get_idle_timeout` ()
	`get_local_address` ()
	`get_max_conns` ()
	`get_max_conns_per_host` ()
	`get_proxy_resolver` ()
	`get_remote_connectable` ()
	`get_timeout` ()
	`get_tls_database` ()
	`get_tls_interaction` ()
	`get_user_agent` ()
	`has_feature` (feature_type)
	`preconnect_async` (msg, io_priority, cancellable, callback, *user_data)
	`preconnect_finish` (result)
	`remove_feature` (feature)
	`remove_feature_by_type` (feature_type)
	`send` (msg, cancellable)
	`send_and_read` (msg, cancellable)
	`send_and_read_async` (msg, io_priority, cancellable, callback, *user_data)
	`send_and_read_finish` (result)
	`send_and_splice` (msg, out_stream, flags, cancellable)
	`send_and_splice_async` (msg, out_stream, flags, io_priority, cancellable, callback, *user_data)
	`send_and_splice_finish` (result)
	`send_async` (msg, io_priority, cancellable, callback, *user_data)
	`send_finish` (result)
	`set_accept_language` (accept_language)
	`set_accept_language_auto` (accept_language_auto)
	`set_idle_timeout` (timeout)
	`set_proxy_resolver` (proxy_resolver)
	`set_timeout` (timeout)
	`set_tls_database` (tls_database)
	`set_tls_interaction` (tls_interaction)
	`set_user_agent` (user_agent)
	`websocket_connect_async` (msg, origin, protocols, io_priority, cancellable, callback, *user_data)
	`websocket_connect_finish` (result)

Virtual Methods¶

Inherited:: GObject.Object (7)

	`do_request_queued` (msg)
	`do_request_unqueued` (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
`idle-timeout`	`int`	r/w	Connection lifetime when idle
`local-address`	`Gio.InetSocketAddress`	r/w/co	Address of local end of socket
`max-conns`	`int`	r/w/co	The maximum number of connections that the session can open at once
`max-conns-per-host`	`int`	r/w/co	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
`remote-connectable`	`Gio.SocketConnectable`	r/w/co	Socket to connect to make outgoing connections on
`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
`user-agent`	`str`	r/w	User-Agent string

Signals¶

Inherited:: GObject.Object (1)

Name	Short Description
`request-queued`	Emitted when a request is queued on session.
`request-unqueued`	Emitted when a request is removed from session's queue, indicating that session is done with it.

Fields¶

Inherited:: GObject.Object (1)

Name	Type	Access	Description
parent_instance	`GObject.Object`	r

Class Details¶

class Soup.Session(**kwargs)¶

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

Soup session state object.

Soup.Session is the object that controls client-side HTTP. A Soup.Session encapsulates all of the state that libsoup is keeping on behalf of your program; cached HTTP connections, authentication information, etc. It also keeps track of various global options and features that you are using.

Most applications will only need a single Soup.Session; the primary reason you might need multiple sessions is if you need to have multiple independent authentication contexts. (Eg, you are connecting to a server and authenticating as two different users at different times; the easiest way to ensure that each [class`Message`] is sent with the authentication information you intended is to use one session for the first user, and a second session for the other user.)

Additional Soup.Session functionality is provided by [iface`SessionFeature`] objects, which can be added to a session with [method`Session`.add_feature] or [method`Session`.add_feature_by_type] For example, [class`Logger`] provides support for logging HTTP traffic, [class`ContentDecoder`] provides support for compressed response handling, and [class`ContentSniffer`] provides support for HTML5-style response body content sniffing. Additionally, subtypes of [class`Auth`] can be added as features, to add support for additional authentication types.

All ``SoupSession``s are created with a [class`AuthManager`], and support for %SOUP_TYPE_AUTH_BASIC and %SOUP_TYPE_AUTH_DIGEST. Additionally, sessions using the plain Soup.Session class (rather than one of its deprecated subtypes) have a [class`ContentDecoder`] by default.

Note that all async methods will invoke their callbacks on the thread-default context at the time of the function call.

classmethod new()¶

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

Creates a Soup.Session with the default options.

abort()¶: Cancels all pending requests in self and closes all idle persistent connections.

add_feature(feature)¶

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

Adds feature's functionality to self. You cannot add multiple features of the same [alias`GLib`.Type] to a session.

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

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 [iface`SessionFeature`], this creates a new feature of that type and adds it to self as with [method`Session`.add_feature]. You can use this when you don’t need to customize the new feature in any way. Adding multiple features of the same feature_type is not allowed.

If feature_type is not a [iface`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 [class`Auth`] types, for instance.

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

get_accept_language()¶

Returns:: the accept language string
Return type:: str or None

Get the value used by self for the “Accept-Language” header on new requests.

get_accept_language_auto()¶

Returns:: True if self sets “Accept-Language” header automatically, or False otherwise.
Return type:: bool

Gets whether self automatically sets the “Accept-Language” header on new requests.

get_async_result_message(result)¶

Parameters:: result (Gio.AsyncResult) – the Gio.AsyncResult passed to your callback
Returns:: a Soup.Message or None if result is not a valid self async operation result.
Return type:: Soup.Message or None

Gets the [class`Message`] of the result asynchronous operation This is useful to get the [class`Message`] of an asynchronous operation started by self from its [callback`Gio`.AsyncReadyCallback].

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 feature in self of type feature_type.

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. The feature is owned by self.

Return type:

Soup.SessionFeature or None

Gets the feature in self of type feature_type, provided that it is not disabled for msg.

get_idle_timeout()¶

Returns:: the timeout in seconds
Return type:: int

Get the timeout in seconds for idle connection lifetime currently used by self.

get_local_address()¶

Returns:: a Gio.InetSocketAddress
Return type:: Gio.InetSocketAddress or None

Get the [class`Gio`.InetSocketAddress] to use for the client side of connections in self.

get_max_conns()¶

Returns:: the maximum number of connections
Return type:: int

Get the maximum number of connections that self can open at once.

get_max_conns_per_host()¶

Returns:: the maximum number of connections per host
Return type:: int

Get the maximum number of connections that self can open at once to a given host.

get_proxy_resolver()¶

Returns:: a Gio.ProxyResolver or None if proxies are disabled in self
Return type:: Gio.ProxyResolver or None

Get the [iface`Gio`.ProxyResolver] currently used by self.

get_remote_connectable()¶

Returns:: the Gio.SocketConnectable
Return type:: Gio.SocketConnectable or None

Gets the remote connectable if one set.

get_timeout()¶

Returns:: the timeout in seconds
Return type:: int

Get the timeout in seconds for socket I/O operations currently used by self.

get_tls_database()¶

Returns:: a Gio.TlsDatabase
Return type:: Gio.TlsDatabase or None

Get the [class`Gio`.TlsDatabase] currently used by self.

get_tls_interaction()¶

Returns:: a Gio.TlsInteraction
Return type:: Gio.TlsInteraction or None

Get the [class`Gio`.TlsInteraction] currently used by self.

get_user_agent()¶

Returns:: the user agent string
Return type:: str or None

Get the value used by self for the “User-Agent” header on new requests.

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 [iface`SessionFeature`], or else a subtype of some class managed by another feature, such as [class`Auth`]).

preconnect_async(msg, io_priority, cancellable, callback, *user_data)¶

Parameters:

msg (Soup.Message) – a Soup.Message
io_priority (int) – the I/O priority of the request
cancellable (Gio.Cancellable or None) – a Gio.Cancellable
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 preconnection to msg.

Once the connection is done, it will remain in idle state so that it can be reused by future requests. If there’s already an idle connection for the given msg host, the operation finishes successfully without creating a new connection. If a new request for the given msg host is made while the preconnect is still ongoing, the request will take the ownership of the connection and the preconnect operation will finish successfully (if there’s a connection error it will be handled by the request).

The operation finishes when the connection is done or an error occurred.

preconnect_finish(result)¶

Parameters:: result (Gio.AsyncResult) – the Gio.AsyncResult passed to your callback
Raises:: GLib.Error
Returns:: True if the preconnect succeeded, or False in case of error.
Return type:: bool

Complete a preconnect async operation started with [method`Session`.preconnect_async].

remove_feature(feature)¶

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

Removes feature's functionality from self.

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.

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 [class`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; [method`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 [method`Session`.send] will only return once a final response has been received.

send_and_read(msg, cancellable)¶

Parameters:

msg (Soup.Message) – a Soup.Message
cancellable (Gio.Cancellable or None) – a Gio.Cancellable

Raises:

GLib.Error

Returns:

a GLib.Bytes, or None on error.

Return type:

GLib.Bytes

Synchronously sends msg and reads the response body.

On success, a [struct`GLib`.Bytes] will be returned with the response body. This function should only be used when the resource to be retrieved is not too long and can be stored in memory.

See [method`Session`.send] for more details on the general semantics.

send_and_read_async(msg, io_priority, cancellable, callback, *user_data)¶

Parameters:

msg (Soup.Message) – a Soup.Message
io_priority (int) – the I/O priority of the request
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 reads the response body.

When callback is called, then either msg has been sent, and its response body read, or else an error has occurred. This function should only be used when the resource to be retrieved is not too long and can be stored in memory. Call [method`Session`.send_and_read_finish] to get a [struct`GLib`.Bytes] with the response body.

See [method`Session`.send] for more details on the general semantics.

send_and_read_finish(result)¶

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

Gets the response to a [method`Session`.send_and_read_async].

If successful, returns a [struct`GLib`.Bytes] with the response body.

send_and_splice(msg, out_stream, flags, cancellable)¶

Parameters:

msg (Soup.Message) – a Soup.Message
out_stream (Gio.OutputStream) – a Gio.OutputStream
flags (Gio.OutputStreamSpliceFlags) – a set of Gio.OutputStreamSpliceFlags
cancellable (Gio.Cancellable or None) – a Gio.Cancellable

Raises:

GLib.Error

Returns:

a #gssize containing the size of the data spliced, or -1 if an error occurred.

Return type:

int

Synchronously sends msg and splices the response body stream into out_stream.

See [method`Session`.send] for more details on the general semantics.

New in version 3.4.

send_and_splice_async(msg, out_stream, flags, io_priority, cancellable, callback, *user_data)¶

Parameters:

msg (Soup.Message) – a Soup.Message
out_stream (Gio.OutputStream) – a Gio.OutputStream
flags (Gio.OutputStreamSpliceFlags) – a set of Gio.OutputStreamSpliceFlags
io_priority (int) – the I/O priority of the request
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 splices the response body stream into out_stream. When callback is called, then either msg has been sent and its response body spliced, or else an error has occurred.

See [method`Session`.send] for more details on the general semantics.

New in version 3.4.

send_and_splice_finish(result)¶

Parameters:: result (Gio.AsyncResult) – the Gio.AsyncResult passed to your callback
Raises:: GLib.Error
Returns:: a #gssize containing the size of the data spliced, or -1 if an error occurred.
Return type:: int

Gets the response to a [method`Session`.send_and_splice_async].

New in version 3.4.

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

Parameters:

msg (Soup.Message) – a Soup.Message
io_priority (int) – the I/O priority of the request
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 [method`Session`.send_finish] to get a [class`Gio`.InputStream] for reading the response body.

See [method`Session`.send] for more details on the general semantics.

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 [method`Session`.send_async] call.

If successful returns a [class`Gio`.InputStream] that can be used to read the response body.

set_accept_language(accept_language)¶

Parameters:: accept_language (str) – the languages string

Set the value to use for the “Accept-Language” header on [class`Message`]s sent from self.

If accept_language is None then no “Accept-Language” will be included in requests. See [property`Session`:py:data::accept-language<Soup.Session.props.accept_language>] for more information.

set_accept_language_auto(accept_language_auto)¶

Parameters:: accept_language_auto (bool) – the value to set

Set whether self will automatically set the “Accept-Language” header on requests using a value generated from system languages based on [func`GLib`.get_language_names].

See [property`Session`:py:data::accept-language-auto<Soup.Session.props.accept_language_auto>] for more information.

set_idle_timeout(timeout)¶

Parameters:: timeout (int) – a timeout in seconds

Set a timeout in seconds for idle connection lifetime to be used by self on new connections.

See [property`Session`:py:data::idle-timeout<Soup.Session.props.idle_timeout>] for more information.

set_proxy_resolver(proxy_resolver)¶

Parameters:: proxy_resolver (Gio.ProxyResolver or None) – a Gio.ProxyResolver or None

Set a [iface`Gio`.ProxyResolver] to be used by self on new connections.

If proxy_resolver is None then no proxies will be used. See [property`Session`:py:data::proxy-resolver<Soup.Session.props.proxy_resolver>] for more information.

set_timeout(timeout)¶

Parameters:: timeout (int) – a timeout in seconds

Set a timeout in seconds for socket I/O operations to be used by self on new connections.

See [property`Session`:py:data::timeout<Soup.Session.props.timeout>] for more information.

set_tls_database(tls_database)¶

Parameters:: tls_database (Gio.TlsDatabase or None) – a Gio.TlsDatabase

Set a [class`GIo`.TlsDatabase] to be used by self on new connections.

If tls_database is None then certificate validation will always fail. See [property`Session`:py:data::tls-database<Soup.Session.props.tls_database>] for more information.

set_tls_interaction(tls_interaction)¶

Parameters:: tls_interaction (Gio.TlsInteraction or None) – a Gio.TlsInteraction

Set a [class`Gio`.TlsInteraction] to be used by self on new connections.

If tls_interaction is None then client certificate validation will always fail.

See [property`Session`:py:data::tls-interaction<Soup.Session.props.tls_interaction>] for more information.

set_user_agent(user_agent)¶

Parameters:: user_agent (str) – the user agent string

Set the value to use for the “User-Agent” header on [class`Message`]s sent from self.

If user_agent has trailing whitespace, self will append its own product token (eg, libsoup/3.0.0) to the end of the header for you. If user_agent is None then no “User-Agent” will be included in requests. See [property`Session`:py:data::user-agent<Soup.Session.props.user_agent>] for more information.

websocket_connect_async(msg, origin, protocols, io_priority, 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
io_priority (int) – the I/O priority of the request
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 [class`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, [method`Session`.websocket_connect_finish] will return a new [class`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 [method`Session`.websocket_connect_finish] will return Soup.WebsocketError.NOT_WEBSOCKET.

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 [class`WebsocketConnection`] response to a [method`Session`.websocket_connect_async] call.

If successful, returns a [class`WebsocketConnection`] that can be used to communicate with the server.

do_request_queued(msg) virtual¶

Parameters:: msg (Soup.Message) –

do_request_unqueued(msg) virtual¶

Parameters:: msg (Soup.Message) –

Signal Details¶

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

Signal Name:

request-queued

Flags:

RUN_LAST

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.

When sending a request, first [signal`Session`:py:func:::request-queued<Soup.Session.signals.request_queued>] is emitted, indicating that the session has become aware of the request.

After a connection is available to send the request various [class`Message`] signals are emitted as the message is processed. If the message is requeued, it will emit [signal`Message`:py:func:::restarted<Soup.Session.signals.restarted>], which will then be followed by other [class`Message`] signals when the message is re-sent.

Eventually, the message will emit [signal`Message`:py:func:::finished<Soup.Session.signals.finished>]. Normally, this signals the completion of message processing. However, it is possible that the application will requeue the message from the “finished” handler. In that case the process will loop back.

Eventually, a message will reach “finished” and not be requeued. At that point, the session will emit [signal`Session`:py:func:::request-unqueued<Soup.Session.signals.request_unqueued>] to indicate that it is done with the message.

To sum up: [signal`Session`:py:func:::request-queued<Soup.Session.signals.request_queued>] and [signal`Session`:py:func:::request-unqueued<Soup.Session.signals.request_unqueued>] are guaranteed to be emitted exactly once, but [signal`Message`:py:func:::finished<Soup.Session.signals.finished>] (and all of the other [class`Message`] signals) may be invoked multiple times for a given message.

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

Signal Name:

request-unqueued

Flags:

RUN_LAST

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 [signal`Session`:py:func:::request-queued<Soup.Session.signals.request_queued>] for a detailed description of the message lifecycle within a session.

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 [class`Message`]s sent from this session.

Setting this will disable [property`Session`:py:data::accept-language-auto<Soup.Session.props.accept_language_auto>].

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 [class`Message`] sent, based on the return value of [func`GLib`.get_language_names].

Setting this will override any previous value of [property`Session`:py:data::accept-language<Soup.Session.props.accept_language>].

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 [method`Session`.abort] after setting this if you want to ensure that all future connections will have this timeout value.

Soup.Session.props.local_address¶

Name:: local-address
Type:: Gio.InetSocketAddress
Default Value:: None
Flags:: READABLE, WRITABLE, CONSTRUCT_ONLY

Sets the [class`Gio`.InetSocketAddress] 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.

Soup.Session.props.max_conns¶

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

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, CONSTRUCT_ONLY

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 [iface`Gio`.ProxyResolver] to use with this session.

If no proxy resolver is set, then the default proxy resolver will be used. See [func`Gio`.ProxyResolver.get_default]. You can set it to None if you don’t want to use proxies, or set it to your own [iface`Gio`.ProxyResolver] if you want to control what proxies get used.

Soup.Session.props.remote_connectable¶

Name:: remote-connectable
Type:: Gio.SocketConnectable
Default Value:: None
Flags:: READABLE, WRITABLE, CONSTRUCT_ONLY

Sets a socket to make outgoing connections on. This will override the default behaviour of opening TCP/IP sockets to the hosts specified in the URIs.

This function is not required for common HTTP usage, but only when connecting to a HTTP service that is not using standard TCP/IP sockets. An example of this is a local service that uses HTTP over UNIX-domain sockets, in that case a [class`Gio`.UnixSocketAddress] can be passed to this function.

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 [method`Session`.abort] after setting this if you want to ensure that all future connections will have this timeout value.

Not to be confused with [property`Session`:py:data::idle-timeout<Soup.Session.props.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 [class`Gio`.TlsDatabase] to use for validating SSL/TLS certificates.

If no certificate database is set, then the default database will be used. See [method`Gio`.TlsBackend.get_default_database].

Soup.Session.props.tls_interaction¶

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

A [class`Gio`.TlsInteraction] object that will be passed on to any [class`Gio`.TlsConnection]s created by the session.

This can be used to provide client-side certificates, for example.

Soup.Session.props.user_agent¶

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

User-Agent string.

If non-None, the value to use for the “User-Agent” header on [class`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 [property`Session`:py:data::user-agent<Soup.Session.props.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.