:right-sidebar: True Session =================================================================== .. currentmodule:: gi.repository.Soup .. class:: Session(**properties: ~typing.Any) :no-contents-entry: Superclasses: :class:`~gi.repository.GObject.Object` Soup session state object. :obj:`~gi.repository.Soup.Session` is the object that controls client-side HTTP. A :obj:`~gi.repository.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 :obj:`~gi.repository.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 :obj:`~gi.repository.Soup.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 :obj:`~gi.repository.Soup.Session` functionality is provided by :obj:`~gi.repository.Soup.SessionFeature` objects, which can be added to a session with :obj:`~gi.repository.Session.add_feature` or :obj:`~gi.repository.Session.add_feature_by_type` For example, :obj:`~gi.repository.Soup.Logger` provides support for logging HTTP traffic, :obj:`~gi.repository.Soup.ContentDecoder` provides support for compressed response handling, and :obj:`~gi.repository.Soup.ContentSniffer` provides support for HTML5-style response body content sniffing. Additionally, subtypes of :obj:`~gi.repository.Soup.Auth` can be added as features, to add support for additional authentication types. All ``SoupSession``\s are created with a :obj:`~gi.repository.Soup.AuthManager`\, and support for %SOUP_TYPE_AUTH_BASIC and %SOUP_TYPE_AUTH_DIGEST. Additionally, sessions using the plain :obj:`~gi.repository.Soup.Session` class (rather than one of its deprecated subtypes) have a :obj:`~gi.repository.Soup.ContentDecoder` by default. Note that all async methods will invoke their callbacks on the thread-default context at the time of the function call. Constructors ------------ .. rst-class:: interim-class .. class:: Session :no-index: .. classmethod:: new() -> ~gi.repository.Soup.Session Creates a :obj:`~gi.repository.Soup.Session` with the default options. Methods ------- .. rst-class:: interim-class .. class:: Session :no-index: .. method:: abort() -> None Cancels all pending requests in ``session`` and closes all idle persistent connections. .. method:: add_feature(feature: ~gi.repository.Soup.SessionFeature) -> None Adds ``feature``\'s functionality to ``session``\. You cannot add multiple features of the same [alias``GObject``\.Type] to a session. See the main :obj:`~gi.repository.Soup.Session` documentation for information on what features are present in sessions by default. :param feature: an object that implements :obj:`~gi.repository.Soup.SessionFeature` .. method:: add_feature_by_type(feature_type: ~gobject.GType) -> None If ``feature_type`` is the type of a class that implements :obj:`~gi.repository.Soup.SessionFeature`\, this creates a new feature of that type and adds it to ``session`` as with :obj:`~gi.repository.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 :obj:`~gi.repository.Soup.SessionFeature` type, this gives each existing feature on ``session`` the chance to accept ``feature_type`` as a "subfeature". This can be used to add new :obj:`~gi.repository.Soup.Auth` types, for instance. See the main :obj:`~gi.repository.Soup.Session` documentation for information on what features are present in sessions by default. :param feature_type: a :obj:`~gi.repository.GObject.Type` .. method:: do_request_queued(self, msg: ~gi.repository.Soup.Message) -> None :param msg: .. method:: do_request_unqueued(self, msg: ~gi.repository.Soup.Message) -> None :param msg: .. method:: get_accept_language() -> str | None Get the value used by ``session`` for the "Accept-Language" header on new requests. .. method:: get_accept_language_auto() -> bool Gets whether ``session`` automatically sets the "Accept-Language" header on new requests. .. method:: get_async_result_message(result: ~gi.repository.Gio.AsyncResult) -> ~gi.repository.Soup.Message | None Gets the :obj:`~gi.repository.Soup.Message` of the ``result`` asynchronous operation This is useful to get the :obj:`~gi.repository.Soup.Message` of an asynchronous operation started by ``session`` from its [callback``Gio``\.AsyncReadyCallback]. :param result: the :obj:`~gi.repository.Gio.AsyncResult` passed to your callback .. method:: get_feature(feature_type: ~gobject.GType) -> ~gi.repository.Soup.SessionFeature | None Gets the feature in ``session`` of type ``feature_type``\. :param feature_type: the :obj:`~gi.repository.GObject.Type` of the feature to get .. method:: get_feature_for_message(feature_type: ~gobject.GType, msg: ~gi.repository.Soup.Message) -> ~gi.repository.Soup.SessionFeature | None Gets the feature in ``session`` of type ``feature_type``\, provided that it is not disabled for ``msg``\. :param feature_type: the :obj:`~gi.repository.GObject.Type` of the feature to get :param msg: a :obj:`~gi.repository.Soup.Message` .. method:: get_idle_timeout() -> int Get the timeout in seconds for idle connection lifetime currently used by ``session``\. .. method:: get_local_address() -> ~gi.repository.Gio.InetSocketAddress | None Get the :obj:`~gi.repository.Gio.InetSocketAddress` to use for the client side of connections in ``session``\. .. method:: get_max_conns() -> int Get the maximum number of connections that ``session`` can open at once. .. method:: get_max_conns_per_host() -> int Get the maximum number of connections that ``session`` can open at once to a given host. .. method:: get_proxy_resolver() -> ~gi.repository.Gio.ProxyResolver | None Get the :obj:`~gi.repository.Gio.ProxyResolver` currently used by ``session``\. .. method:: get_remote_connectable() -> ~gi.repository.Gio.SocketConnectable | None Gets the remote connectable if one set. .. method:: get_timeout() -> int Get the timeout in seconds for socket I/O operations currently used by ``session``\. .. method:: get_tls_database() -> ~gi.repository.Gio.TlsDatabase | None Get the :obj:`~gi.repository.Gio.TlsDatabase` currently used by ``session``\. .. method:: get_tls_interaction() -> ~gi.repository.Gio.TlsInteraction | None Get the :obj:`~gi.repository.Gio.TlsInteraction` currently used by ``session``\. .. method:: get_user_agent() -> str | None Get the value used by ``session`` for the "User-Agent" header on new requests. .. method:: has_feature(feature_type: ~gobject.GType) -> bool Tests if ``session`` has at a feature of type ``feature_type`` (which can be the type of either a :obj:`~gi.repository.Soup.SessionFeature`\, or else a subtype of some class managed by another feature, such as :obj:`~gi.repository.Soup.Auth`\). :param feature_type: the :obj:`~gi.repository.GObject.Type` of the class of features to check for .. method:: preconnect_async(msg: ~gi.repository.Soup.Message, io_priority: int, cancellable: ~gi.repository.Gio.Cancellable | None = None, callback: ~typing.Callable[[~gi.repository.GObject.Object | None, ~gi.repository.Gio.AsyncResult, ~typing.Any], None] | None = None, user_data: ~typing.Any = None) -> None 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. :param msg: a :obj:`~gi.repository.Soup.Message` :param io_priority: the I/O priority of the request :param cancellable: a :obj:`~gi.repository.Gio.Cancellable` :param callback: the callback to invoke when the operation finishes :param user_data: data for ``progress_callback`` and ``callback`` .. method:: preconnect_finish(result: ~gi.repository.Gio.AsyncResult) -> bool Complete a preconnect async operation started with :obj:`~gi.repository.Session.preconnect_async`\. :param result: the :obj:`~gi.repository.Gio.AsyncResult` passed to your callback .. method:: remove_feature(feature: ~gi.repository.Soup.SessionFeature) -> None Removes ``feature``\'s functionality from ``session``\. :param feature: a feature that has previously been added to ``session`` .. method:: remove_feature_by_type(feature_type: ~gobject.GType) -> None Removes all features of type ``feature_type`` (or any subclass of ``feature_type``\) from ``session``\. :param feature_type: a :obj:`~gi.repository.GObject.Type` .. method:: send(msg: ~gi.repository.Soup.Message, cancellable: ~gi.repository.Gio.Cancellable | None = None) -> ~gi.repository.Gio.InputStream Synchronously sends ``msg`` and waits for the beginning of a response. On success, a :obj:`~gi.repository.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-:const:`None`, ``cancellable`` can be used to cancel the request; :obj:`~gi.repository.Session.send` will return a %G_IO_ERROR_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 :obj:`~gi.repository.Session.send` will only return once a final response has been received. :param msg: a :obj:`~gi.repository.Soup.Message` :param cancellable: a :obj:`~gi.repository.Gio.Cancellable` .. method:: send_and_read(msg: ~gi.repository.Soup.Message, cancellable: ~gi.repository.Gio.Cancellable | None = None) -> ~gi.repository.GLib.Bytes Synchronously sends ``msg`` and reads the response body. On success, a :obj:`~gi.repository.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 :obj:`~gi.repository.Session.send` for more details on the general semantics. :param msg: a :obj:`~gi.repository.Soup.Message` :param cancellable: a :obj:`~gi.repository.Gio.Cancellable` .. method:: send_and_read_async(msg: ~gi.repository.Soup.Message, io_priority: int, cancellable: ~gi.repository.Gio.Cancellable | None = None, callback: ~typing.Callable[[~gi.repository.GObject.Object | None, ~gi.repository.Gio.AsyncResult, ~typing.Any], None] | None = None, user_data: ~typing.Any = None) -> None 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 :obj:`~gi.repository.Session.send_and_read_finish` to get a :obj:`~gi.repository.GLib.Bytes` with the response body. See :obj:`~gi.repository.Session.send` for more details on the general semantics. :param msg: a :obj:`~gi.repository.Soup.Message` :param io_priority: the I/O priority of the request :param cancellable: a :obj:`~gi.repository.Gio.Cancellable` :param callback: the callback to invoke :param user_data: data for ``callback`` .. method:: send_and_read_finish(result: ~gi.repository.Gio.AsyncResult) -> ~gi.repository.GLib.Bytes Gets the response to a :obj:`~gi.repository.Session.send_and_read_async`\. If successful, returns a :obj:`~gi.repository.GLib.Bytes` with the response body. :param result: the :obj:`~gi.repository.Gio.AsyncResult` passed to your callback .. method:: send_and_splice(msg: ~gi.repository.Soup.Message, out_stream: ~gi.repository.Gio.OutputStream, flags: ~gi.repository.Gio.OutputStreamSpliceFlags, cancellable: ~gi.repository.Gio.Cancellable | None = None) -> int Synchronously sends ``msg`` and splices the response body stream into ``out_stream``\. See :obj:`~gi.repository.Session.send` for more details on the general semantics. .. versionadded:: 3.4 :param msg: a :obj:`~gi.repository.Soup.Message` :param out_stream: a :obj:`~gi.repository.Gio.OutputStream` :param flags: a set of :obj:`~gi.repository.Gio.OutputStreamSpliceFlags` :param cancellable: a :obj:`~gi.repository.Gio.Cancellable` .. method:: send_and_splice_async(msg: ~gi.repository.Soup.Message, out_stream: ~gi.repository.Gio.OutputStream, flags: ~gi.repository.Gio.OutputStreamSpliceFlags, io_priority: int, cancellable: ~gi.repository.Gio.Cancellable | None = None, callback: ~typing.Callable[[~gi.repository.GObject.Object | None, ~gi.repository.Gio.AsyncResult, ~typing.Any], None] | None = None, user_data: ~typing.Any = None) -> None 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 :obj:`~gi.repository.Session.send` for more details on the general semantics. .. versionadded:: 3.4 :param msg: a :obj:`~gi.repository.Soup.Message` :param out_stream: a :obj:`~gi.repository.Gio.OutputStream` :param flags: a set of :obj:`~gi.repository.Gio.OutputStreamSpliceFlags` :param io_priority: the I/O priority of the request :param cancellable: a :obj:`~gi.repository.Gio.Cancellable` :param callback: the callback to invoke :param user_data: data for ``callback`` .. method:: send_and_splice_finish(result: ~gi.repository.Gio.AsyncResult) -> int Gets the response to a :obj:`~gi.repository.Session.send_and_splice_async`\. .. versionadded:: 3.4 :param result: the :obj:`~gi.repository.Gio.AsyncResult` passed to your callback .. method:: send_async(msg: ~gi.repository.Soup.Message, io_priority: int, cancellable: ~gi.repository.Gio.Cancellable | None = None, callback: ~typing.Callable[[~gi.repository.GObject.Object | None, ~gi.repository.Gio.AsyncResult, ~typing.Any], None] | None = None, user_data: ~typing.Any = None) -> None 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 :obj:`~gi.repository.Session.send_finish` to get a :obj:`~gi.repository.Gio.InputStream` for reading the response body. See :obj:`~gi.repository.Session.send` for more details on the general semantics. :param msg: a :obj:`~gi.repository.Soup.Message` :param io_priority: the I/O priority of the request :param cancellable: a :obj:`~gi.repository.Gio.Cancellable` :param callback: the callback to invoke :param user_data: data for ``callback`` .. method:: send_finish(result: ~gi.repository.Gio.AsyncResult) -> ~gi.repository.Gio.InputStream Gets the response to a :obj:`~gi.repository.Session.send_async` call. If successful returns a :obj:`~gi.repository.Gio.InputStream` that can be used to read the response body. :param result: the :obj:`~gi.repository.Gio.AsyncResult` passed to your callback .. method:: set_accept_language(accept_language: str) -> None Set the value to use for the "Accept-Language" header on :obj:`~gi.repository.Soup.Message`\s sent from ``session``\. If ``accept_language`` is :const:`None` then no "Accept-Language" will be included in requests. See :obj:`~gi.repository.Soup.Session.props.accept_language` for more information. :param accept_language: the languages string .. method:: set_accept_language_auto(accept_language_auto: bool) -> None Set whether ``session`` will automatically set the "Accept-Language" header on requests using a value generated from system languages based on :obj:`~gi.repository.GLib.get_language_names`\. See :obj:`~gi.repository.Soup.Session.props.accept_language_auto` for more information. :param accept_language_auto: the value to set .. method:: set_idle_timeout(timeout: int) -> None Set a timeout in seconds for idle connection lifetime to be used by ``session`` on new connections. See :obj:`~gi.repository.Soup.Session.props.idle_timeout` for more information. :param timeout: a timeout in seconds .. method:: set_proxy_resolver(proxy_resolver: ~gi.repository.Gio.ProxyResolver | None = None) -> None Set a :obj:`~gi.repository.Gio.ProxyResolver` to be used by ``session`` on new connections. If ``proxy_resolver`` is :const:`None` then no proxies will be used. See :obj:`~gi.repository.Soup.Session.props.proxy_resolver` for more information. :param proxy_resolver: a :obj:`~gi.repository.Gio.ProxyResolver` or :const:`None` .. method:: set_timeout(timeout: int) -> None Set a timeout in seconds for socket I/O operations to be used by ``session`` on new connections. See :obj:`~gi.repository.Soup.Session.props.timeout` for more information. :param timeout: a timeout in seconds .. method:: set_tls_database(tls_database: ~gi.repository.Gio.TlsDatabase | None = None) -> None Set a :obj:`~gi.repository.Gio.TlsDatabase` to be used by ``session`` on new connections. If ``tls_database`` is :const:`None` then certificate validation will always fail. See :obj:`~gi.repository.Soup.Session.props.tls_database` for more information. :param tls_database: a :obj:`~gi.repository.Gio.TlsDatabase` .. method:: set_tls_interaction(tls_interaction: ~gi.repository.Gio.TlsInteraction | None = None) -> None Set a :obj:`~gi.repository.Gio.TlsInteraction` to be used by ``session`` on new connections. If ``tls_interaction`` is :const:`None` then client certificate validation will always fail. See :obj:`~gi.repository.Soup.Session.props.tls_interaction` for more information. :param tls_interaction: a :obj:`~gi.repository.Gio.TlsInteraction` .. method:: set_user_agent(user_agent: str) -> None Set the value to use for the "User-Agent" header on :obj:`~gi.repository.Soup.Message`\s sent from ``session``\. If ``user_agent`` has trailing whitespace, ``session`` will append its own product token (eg, ``libsoup/3.0.0``\) to the end of the header for you. If ``user_agent`` is :const:`None` then no "User-Agent" will be included in requests. See :obj:`~gi.repository.Soup.Session.props.user_agent` for more information. :param user_agent: the user agent string .. method:: websocket_connect_async(msg: ~gi.repository.Soup.Message, origin: str | None, protocols: list[str] | None, io_priority: int, cancellable: ~gi.repository.Gio.Cancellable | None = None, callback: ~typing.Callable[[~gi.repository.GObject.Object | None, ~gi.repository.Gio.AsyncResult, ~typing.Any], None] | None = None, user_data: ~typing.Any = None) -> None Asynchronously creates a :obj:`~gi.repository.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, :obj:`~gi.repository.Session.websocket_connect_finish` will return a new :obj:`~gi.repository.Soup.WebsocketConnection`\. On failure it will return a :obj:`~gi.repository.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 :obj:`~gi.repository.Session.websocket_connect_finish` will return :const:`~gi.repository.Soup.WebsocketError.NOT_WEBSOCKET`. :param msg: :obj:`~gi.repository.Soup.Message` indicating the WebSocket server to connect to :param origin: origin of the connection :param protocols: a :const:`None`-terminated array of protocols supported :param io_priority: the I/O priority of the request :param cancellable: a :obj:`~gi.repository.Gio.Cancellable` :param callback: the callback to invoke :param user_data: data for ``callback`` .. method:: websocket_connect_finish(result: ~gi.repository.Gio.AsyncResult) -> ~gi.repository.Soup.WebsocketConnection Gets the :obj:`~gi.repository.Soup.WebsocketConnection` response to a :obj:`~gi.repository.Session.websocket_connect_async` call. If successful, returns a :obj:`~gi.repository.Soup.WebsocketConnection` that can be used to communicate with the server. :param result: the :obj:`~gi.repository.Gio.AsyncResult` passed to your callback Properties ---------- .. rst-class:: interim-class .. class:: Session :no-index: .. attribute:: props.accept_language :type: str The type of the None singleton. .. attribute:: props.accept_language_auto :type: bool The type of the None singleton. .. attribute:: props.idle_timeout :type: int The type of the None singleton. .. attribute:: props.local_address :type: ~gi.repository.Gio.InetSocketAddress The type of the None singleton. .. attribute:: props.max_conns :type: int The type of the None singleton. .. attribute:: props.max_conns_per_host :type: int The type of the None singleton. .. attribute:: props.proxy_resolver :type: ~gi.repository.Gio.ProxyResolver The type of the None singleton. .. attribute:: props.remote_connectable :type: ~gi.repository.Gio.SocketConnectable The type of the None singleton. .. attribute:: props.timeout :type: int The type of the None singleton. .. attribute:: props.tls_database :type: ~gi.repository.Gio.TlsDatabase The type of the None singleton. .. attribute:: props.tls_interaction :type: ~gi.repository.Gio.TlsInteraction The type of the None singleton. .. attribute:: props.user_agent :type: str The type of the None singleton. Signals ------- .. rst-class:: interim-class .. class:: Session.signals :no-index: .. method:: request_queued(msg: ~gi.repository.Soup.Message) -> None The type of the None singleton. :param msg: the request that was queued .. method:: request_unqueued(msg: ~gi.repository.Soup.Message) -> None The type of the None singleton. :param msg: the request that was unqueued Virtual Methods --------------- .. rst-class:: interim-class .. class:: Session :no-index: .. method:: do_request_queued(msg: ~gi.repository.Soup.Message) -> None The type of the None singleton. :param msg: .. method:: do_request_unqueued(msg: ~gi.repository.Soup.Message) -> None The type of the None singleton. :param msg: Fields ------ .. rst-class:: interim-class .. class:: Session :no-index: .. attribute:: parent_instance