:right-sidebar: True Session =================================================================== .. currentmodule:: gi.repository.Soup .. class:: Session(**properties: ~typing.Any) :no-contents-entry: Superclasses: :class:`~gi.repository.GObject.Object` :Constructors: :: Session(**properties) new() -> Soup.Session 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 ``GLib.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: type) -> 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:: 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 ``Gio.AsyncReadyCallback``. :param result: the :obj:`~gi.repository.Gio.AsyncResult` passed to your callback .. method:: get_feature(feature_type: type) -> ~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: type, 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: type) -> 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[[...], None] | None = None, *user_data: ~typing.Any) -> 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: type) -> 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[[...], None] | None = None, *user_data: ~typing.Any) -> 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[[...], None] | None = None, *user_data: ~typing.Any) -> 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[[...], None] | None = None, *user_data: ~typing.Any) -> 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: ~typing.Sequence[str] | None, io_priority: int, cancellable: ~gi.repository.Gio.Cancellable | None = None, callback: ~typing.Callable[[...], None] | None = None, *user_data: ~typing.Any) -> 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 If non-:const:`None`, the value to use for the "Accept-Language" header on :obj:`~gi.repository.Soup.Message`'s sent from this session. Setting this will disable :obj:`~gi.repository.Soup.Session.props.accept_language_auto`. .. attribute:: props.accept_language_auto :type: bool If :const:`True`, :obj:`~gi.repository.Soup.Session` will automatically set the string for the "Accept-Language" header on every :obj:`~gi.repository.Soup.Message` sent, based on the return value of :obj:`~gi.repository.GLib.get_language_names`. Setting this will override any previous value of :obj:`~gi.repository.Soup.Session.props.accept_language`. .. attribute:: props.idle_timeout :type: int 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 :obj:`~gi.repository.Session.abort` after setting this if you want to ensure that all future connections will have this timeout value. .. attribute:: props.local_address :type: ~gi.repository.Gio.InetSocketAddress Sets the :obj:`~gi.repository.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. .. attribute:: props.max_conns :type: int The maximum number of connections that the session can open at once. .. attribute:: props.max_conns_per_host :type: int The maximum number of connections that the session can open at once to a given host. .. attribute:: props.proxy_resolver :type: ~gi.repository.Gio.ProxyResolver A :obj:`~gi.repository.Gio.ProxyResolver` to use with this session. If no proxy resolver is set, then the default proxy resolver will be used. See :obj:`~gi.repository.Gio.ProxyResolver.get_default`. You can set it to :const:`None` if you don't want to use proxies, or set it to your own :obj:`~gi.repository.Gio.ProxyResolver` if you want to control what proxies get used. .. attribute:: props.remote_connectable :type: ~gi.repository.Gio.SocketConnectable 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 :obj:`~gi.repository.Gio.UnixSocketAddress` can be passed to this function. .. attribute:: props.timeout :type: int 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 :obj:`~gi.repository.Session.abort` after setting this if you want to ensure that all future connections will have this timeout value. Not to be confused with :obj:`~gi.repository.Soup.Session.props.idle_timeout` (which is the length of time that idle persistent connections will be kept open). .. attribute:: props.tls_database :type: ~gi.repository.Gio.TlsDatabase Sets the :obj:`~gi.repository.Gio.TlsDatabase` to use for validating SSL/TLS certificates. If no certificate database is set, then the default database will be used. See :obj:`~gi.repository.Gio.TlsBackend.get_default_database`. .. attribute:: props.tls_interaction :type: ~gi.repository.Gio.TlsInteraction A :obj:`~gi.repository.Gio.TlsInteraction` object that will be passed on to any :obj:`~gi.repository.Gio.TlsConnection`'s created by the session. This can be used to provide client-side certificates, for example. .. attribute:: props.user_agent :type: str User-Agent string. If non-:const:`None`, the value to use for the "User-Agent" header on :obj:`~gi.repository.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 :obj:`~gi.repository.Soup.Session.props.user_agent` property that has trailing whitespace, :obj:`~gi.repository.Soup.Session` will append its own product token (eg, ``libsoup/2.3.2``) to the end of the header for you. Signals ------- .. rst-class:: interim-class .. class:: Session.signals :no-index: .. method:: request_queued(msg: ~gi.repository.Soup.Message) -> None Emitted when a request is queued on ``session``. When sending a request, first :obj:`~gi.repository.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 :obj:`~gi.repository.Soup.Message` signals are emitted as the message is processed. If the message is requeued, it will emit :obj:`~gi.repository.Soup.Message.signals.restarted`, which will then be followed by other :obj:`~gi.repository.Soup.Message` signals when the message is re-sent. Eventually, the message will emit :obj:`~gi.repository.Soup.Message.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 :obj:`~gi.repository.Soup.Session.signals.request_unqueued` to indicate that it is done with the message. To sum up: :obj:`~gi.repository.Soup.Session.signals.request_queued` and :obj:`~gi.repository.Soup.Session.signals.request_unqueued` are guaranteed to be emitted exactly once, but :obj:`~gi.repository.Soup.Message.signals.finished` (and all of the other :obj:`~gi.repository.Soup.Message` signals) may be invoked multiple times for a given message. :param msg: the request that was queued .. method:: request_unqueued(msg: ~gi.repository.Soup.Message) -> None Emitted when a request is removed from ``session``'s queue, indicating that ``session`` is done with it. See :obj:`~gi.repository.Soup.Session.signals.request_queued` for a detailed description of the message lifecycle within a session. :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 :param msg: .. method:: do_request_unqueued(msg: ~gi.repository.Soup.Message) -> None :param msg: Fields ------ .. rst-class:: interim-class .. class:: Session :no-index: .. attribute:: parent_instance