:right-sidebar: True Transaction =================================================================== .. currentmodule:: gi.repository.Flatpak .. class:: Transaction(**properties: ~typing.Any) :no-contents-entry: Superclasses: :class:`~gi.repository.GObject.Object` Implemented Interfaces: :class:`~gi.repository.Gio.Initable` :Constructors: :: Transaction(**properties) new_for_installation(installation:Flatpak.Installation, cancellable:Gio.Cancellable=None) -> Flatpak.Transaction Constructors ------------ .. rst-class:: interim-class .. class:: Transaction :no-index: .. classmethod:: new_for_installation(installation: ~gi.repository.Flatpak.Installation, cancellable: ~gi.repository.Gio.Cancellable | None = None) -> ~gi.repository.Flatpak.Transaction Creates a new :obj:`~gi.repository.Flatpak.Transaction` object that can be used to do installation and updates of multiple refs, as well as their dependencies, in a single operation. Set the options you want on the transaction and add the refs you want to install/update, then start the transaction with flatpak_transaction_run (). :param installation: a :obj:`~gi.repository.Flatpak.Installation` :param cancellable: a :obj:`~gi.repository.Gio.Cancellable` Methods ------- .. rst-class:: interim-class .. class:: Transaction :no-index: .. method:: abort_webflow(id: int) -> None Cancel an ongoing webflow authentication request. This can be call in the time between :obj:`~gi.repository.Flatpak.Transaction`::webflow-start returned :const:`True`, and :obj:`~gi.repository.Flatpak.Transaction`::webflow-done is emitted. It will cancel the ongoing authentication operation. This is useful for example if you're showing an authenticaion window with a browser, but the user closed it before it was finished. .. versionadded:: 1.5.1 :param id: The webflow id, as passed into the webflow-start signal .. method:: add_default_dependency_sources() -> None Similar to :func:`~gi.repository.Flatpak.Transaction.add_dependency_source`, but adds all the default installations, which means all the defined system-wide (but not per-user) installations. .. method:: add_dependency_source(installation: ~gi.repository.Flatpak.Installation) -> None Adds an extra installation as a source for application dependencies. This means that applications can be installed in this transaction relying on runtimes from this additional installation (whereas it would normally install required runtimes that are not installed in the installation the transaction works on). Also see :func:`~gi.repository.Flatpak.Transaction.add_default_dependency_sources`. :param installation: a :obj:`~gi.repository.Flatpak.Installation` .. method:: add_install(remote: str, ref: str, subpaths: ~typing.Sequence[str] | None = None) -> bool Adds installing the given ref to this transaction. The ``remote`` can either be a configured remote of the installation, or a file:// uri pointing at a local repository to install from, in which case an origin remote is created. :param remote: the name of the remote :param ref: the ref :param subpaths: subpaths to install, or the empty list or :const:`None` to pull all subpaths .. method:: add_install_bundle(file: ~gi.repository.Gio.File, gpg_data: ~gi.repository.GLib.Bytes | None = None) -> bool Adds installing the given bundle to this transaction. :param file: a :obj:`~gi.repository.Gio.File` that is an flatpak bundle :param gpg_data: GPG key with which to check bundle signatures, or :const:`None` to use the key embedded in the bundle (if any) .. method:: add_install_flatpakref(flatpakref_data: ~gi.repository.GLib.Bytes) -> bool Adds installing the given flatpakref to this transaction. :param flatpakref_data: data from a flatpakref file .. method:: add_rebase(remote: str, ref: str, subpaths: str | None = None, previous_ids: ~typing.Sequence[str] | None = None) -> bool Adds updating the ``previous_ids`` of the given ref to this transaction, via either installing the ``ref`` if it was not already present or updating it. This will treat ``ref`` as the result of following an eol-rebase, and data migration from the refs in ``previous_ids`` will be set up. If you want to rebase the ref and uninstall the old version of it, consider using :func:`~gi.repository.Flatpak.Transaction.add_rebase_and_uninstall` instead. It will add appropriate dependencies between the rebase and uninstall operations. See :func:`~gi.repository.Flatpak.Transaction.add_install` for a description of ``remote``. .. versionadded:: 1.3.3. :param remote: the name of the remote :param ref: the ref :param subpaths: the subpaths to include, or :const:`None` to install the complete ref :param previous_ids: Previous ids to add to the given ref. These should simply be the ids, not the full ref names (e.g. org.foo.Bar, not org.foo.Bar/x86_64/master). .. method:: add_rebase_and_uninstall(remote: str, new_ref: str, old_ref: str, subpaths: str | None = None, previous_ids: ~typing.Sequence[str] | None = None) -> bool Adds updating the ``previous_ids`` of the given ``new_ref`` to this transaction, via either installing the ``new_ref`` if it was not already present or updating it. This will treat ``new_ref`` as the result of following an eol-rebase, and data migration from the refs in ``previous_ids`` will be set up. Also adds an operation to uninstall ``old_ref`` to this transaction. This operation will only be run if the operation to install/update ``new_ref`` succeeds. If ``old_ref`` is not already installed (which can happen if requesting to install an EOLed app, rather than update one which is already installed), the uninstall operation will silently not be added, and this function will behave similarly to :func:`~gi.repository.Flatpak.Transaction.add_rebase`. See :func:`~gi.repository.Flatpak.Transaction.add_install` for a description of ``remote``. .. versionadded:: 1.15.4 :param remote: the name of the remote :param new_ref: the ref to rebase to :param old_ref: the ref to uninstall :param subpaths: the subpaths to include, or :const:`None` to install the complete ref :param previous_ids: Previous ids to add to the given ref. These should simply be the ids, not the full ref names (e.g. org.foo.Bar, not org.foo.Bar/x86_64/master). .. method:: add_sideload_repo(path: str) -> None Adds an extra local ostree repo as source for installation. This is equivalent to using the sideload-repos directories (see flatpak(1)), but can be done dynamically. Any path added here is used in addition to ones in those directories. .. versionadded:: 1.7.1 :param path: a path to a local flatpak repository .. method:: add_uninstall(ref: str) -> bool Adds uninstalling the given ref to this transaction. If the transaction is set to not deploy updates, the request is ignored. :param ref: the ref .. method:: add_update(ref: str, subpaths: ~typing.Sequence[str] | None = None, commit: str | None = None) -> bool Adds updating the given ref to this transaction. :param ref: the ref :param subpaths: subpaths to install; :const:`None` to use the current set plus the set of configured languages, or `{ NULL }` or `{ "", NULL }` to pull all subpaths. :param commit: the commit to update to, or :const:`None` to use the latest .. method:: complete_basic_auth(id: int, user: str, password: str, options: ~gi.repository.GLib.Variant) -> None Finishes (or aborts) an ongoing basic auth request. .. versionadded:: 1.5.2 :param id: The webflow id, as passed into the webflow-start signal :param user: The user name, or :const:`None` if aborting request :param password: The password :param options: Extra a{sv] variant with options (or :const:`None`), currently unused. .. method:: get_auto_install_debug() -> bool Gets the value set by :func:`~gi.repository.Flatpak.Transaction.set_auto_install_debug`. .. versionadded:: 1.13.3 .. method:: get_auto_install_sdk() -> bool Gets the value set by :func:`~gi.repository.Flatpak.Transaction.set_auto_install_sdk`. .. versionadded:: 1.13.3 .. method:: get_current_operation() -> ~gi.repository.Flatpak.TransactionOperation Gets the current operation. .. method:: get_include_unused_uninstall_ops() -> bool Gets the value set by :func:`~gi.repository.Flatpak.Transaction.set_include_unused_uninstall_ops`. .. versionadded:: 1.9.1 .. method:: get_installation() -> ~gi.repository.Flatpak.Installation Gets the installation this transaction was created for. .. method:: get_no_deploy() -> bool Gets whether the transaction is only downloading updates, and not deploying them. .. versionadded:: 1.5.1 .. method:: get_no_interaction() -> bool Gets whether the transaction is interactive. See :func:`~gi.repository.Flatpak.Transaction.set_no_interaction`. .. versionadded:: 1.13.0 .. method:: get_no_pull() -> bool Gets whether the transaction should operate only on locally available data. .. versionadded:: 1.5.1 .. method:: get_operations() -> list[~gi.repository.Flatpak.TransactionOperation] Gets the list of operations. Skipped operations are not included. The order of the list is the order in which the operations are executed. .. method:: get_parent_window() -> str Gets the parent window set for this transaction, or :const:`None` if unset. See :func:`~gi.repository.Flatpak.Transaction.get_parent_window`. .. versionadded:: 1.5.1 .. method:: is_empty() -> bool Returns whether the transaction contains any non-skipped operations. .. method:: run(cancellable: ~gi.repository.Gio.Cancellable | None = None) -> bool Executes the transaction. During the course of the execution, various signals will get emitted. The FlatpakTransaction::choose-remote-for-ref and :obj:`~gi.repository.Flatpak.Transaction`::add-new-remote signals may get emitted while resolving operations. :obj:`~gi.repository.Flatpak.Transaction`::ready is emitted when the transaction has been fully resolved, and :obj:`~gi.repository.Flatpak.Transaction`::new-operation and :obj:`~gi.repository.Flatpak.Transaction`::operation-done are emitted while the operations are carried out. If an error occurs at any point during the execution, :obj:`~gi.repository.Flatpak.Transaction`::operation-error is emitted. Note that this call blocks until the transaction is done. :param cancellable: a :obj:`~gi.repository.Gio.Cancellable` .. method:: set_auto_install_debug(auto_install_debug: bool) -> None When this is set to :const:`True`, Flatpak will automatically install the debug info for each app currently being installed or updated, as well as its dependencies. Does nothing if an uninstall is taking place. .. versionadded:: 1.13.3 :param auto_install_debug: whether to auto install debug info for apps .. method:: set_auto_install_sdk(auto_install_sdk: bool) -> None When this is set to :const:`True`, Flatpak will automatically install the SDK for each app currently being installed or updated. Does nothing if an uninstall is taking place. .. versionadded:: 1.13.3 :param auto_install_sdk: whether to auto install SDKs for apps .. method:: set_default_arch(arch: str) -> None Sets the architecture to default to where it is unspecified. :param arch: the arch to make default .. method:: set_disable_auto_pin(disable_pin: bool) -> None Normally the transaction pins any explicit installations so they will not be automatically removed. But this can be disabled if you don't want this behaviour. .. versionadded:: 1.9.1 :param disable_pin: whether to disable auto-pinning .. method:: set_disable_dependencies(disable_dependencies: bool) -> None Sets whether the transaction should ignore runtime dependencies when resolving operations for applications. :param disable_dependencies: whether to disable runtime dependencies .. method:: set_disable_prune(disable_prune: bool) -> None Sets whether the transaction should avoid pruning the local OSTree repository after updating. :param disable_prune: whether to avoid pruning .. method:: set_disable_related(disable_related: bool) -> None Sets whether the transaction should avoid adding related refs when resolving operations. Related refs are extensions that are suggested by apps, such as locales. :param disable_related: whether to avoid adding related refs .. method:: set_disable_static_deltas(disable_static_deltas: bool) -> None Sets whether the transaction should avoid using static deltas when pulling. :param disable_static_deltas: whether to avoid static deltas .. method:: set_force_uninstall(force_uninstall: bool) -> None Sets whether the transaction should uninstall files even if they're used by a running application. :param force_uninstall: whether to force-uninstall refs .. method:: set_include_unused_uninstall_ops(include_unused_uninstall_ops: bool) -> None When this is set to :const:`True`, Flatpak will add uninstall operations to the transaction for each runtime it considers unused. This is used by the "update" CLI command to garbage collect runtimes and free disk space. No guarantees are made about the exact hueristic used; e.g. only end-of-life unused runtimes may be uninstalled with this set. To see the full list of unused runtimes in an installation, use :func:`~gi.repository.Flatpak.Installation.list_unused_refs`. .. versionadded:: 1.9.1 :param include_unused_uninstall_ops: whether to include unused uninstall ops .. method:: set_no_deploy(no_deploy: bool) -> None Sets whether the transaction should download updates, but not deploy them. :param no_deploy: whether to avoid deploying .. method:: set_no_interaction(no_interaction: bool) -> None This method can be used to prevent interactive authorization dialogs to appear for operations on ``self``. This is useful for background operations that are not directly triggered by a user action. By default, the setting from the parent :obj:`~gi.repository.Flatpak.Installation` is used. .. versionadded:: 1.7.3 :param no_interaction: Whether to disallow interactive authorization for operations .. method:: set_no_pull(no_pull: bool) -> None Sets whether the transaction should operate only on locally available data. :param no_pull: whether to avoid pulls .. method:: set_parent_window(parent_window: str) -> None Sets the parent window (if any) to use for any UI show by this transaction. This is used by authenticators if they need to interact with the user during authentication. The format of this string depends on the display system in use, and is the same as used by xdg-desktop-portal. On X11 it should be of the form x11:$xid where $xid is the hex version of the xwindows id. On wayland is should be wayland:$handle where handle is gotten by using the export call of the xdg-foreign-unstable wayland extension. .. versionadded:: 1.5.1 :param parent_window: whether to avoid pulls .. method:: set_reinstall(reinstall: bool) -> None Sets whether the transaction should uninstall first if a ref is already installed. :param reinstall: whether to reinstall refs Properties ---------- .. rst-class:: interim-class .. class:: Transaction :no-index: .. attribute:: props.installation :type: ~gi.repository.Flatpak.Installation The installation that the transaction operates on. .. attribute:: props.no_interaction :type: bool :const:`True` if the transaction is not interactive, :const:`False` otherwise. See :func:`~gi.repository.Flatpak.Transaction.set_no_interaction`. .. versionadded:: 1.13.0 Signals ------- .. rst-class:: interim-class .. class:: Transaction.signals :no-index: .. method:: add_new_remote(reason: ~gi.repository.Flatpak.TransactionRemoteReason, from_id: str, suggested_remote_name: str, url: str) -> bool The ::add-new-remote signal gets emitted if, as part of the transaction, it is required or recommended that a new remote is added, for the reason described in ``reason``. :param reason: A :obj:`~gi.repository.Flatpak.TransactionRemoteReason` for this suggestion :param from_id: The id of the app/runtime :param suggested_remote_name: The suggested remote name :param url: The repo url .. method:: basic_auth_start(remote: str, realm: str, options: ~gi.repository.GLib.Variant, id: int) -> bool The ::basic-auth-start signal gets emitted when a basic user/password authentication is needed during the operation. If the caller handles this it should ask the user for the user and password and return :const:`True`. Once the information is gathered call :func:`~gi.repository.Flatpak.Transaction.complete_basic_auth` with it. If the client does not support basic auth then return :const:`False` from this signal (or don't implement it). This will abort the authentication and likely result in the transaction failing (unless the authentication was somehow optional). .. versionadded:: 1.5.2 :param remote: The remote we're authenticating with :param realm: The url to show :param options: Extra options, currently unused :param id: The id of the operation, can be used to finish it .. method:: choose_remote_for_ref(for_ref: str, runtime_ref: str, remotes: ~typing.Sequence[str]) -> int The ::choose-remote-for-ref signal gets emitted when a remote needs to be selected during the execution of the transaction. :param for_ref: The ref we are installing :param runtime_ref: The ref we are looking for :param remotes: the remotes that has the ref, sorted in prio order .. method:: end_of_lifed(ref: str, reason: str, rebase: str) -> None The ::end-of-lifed signal gets emitted when a ref is found to be marked as end-of-life during the execution of the transaction. :param ref: The ref we are installing :param reason: The eol reason, or :const:`None` :param rebase: The new name, if rebased, or :const:`None` .. method:: end_of_lifed_with_rebase(remote: str, ref: str, reason: str, rebased_to_ref: str, previous_ids: ~typing.Sequence[str]) -> bool The ::end-of-lifed-with-rebase signal gets emitted when a ref is found to be marked as end-of-life before the transaction begins. Unlike :obj:`~gi.repository.Flatpak.Transaction`::end-of-lifed, this signal allows for the transaction to be modified in order to e.g. install the rebased ref. If the caller wants to install the rebased ref, they should call :func:`~gi.repository.Flatpak.Transaction.add_rebase_and_uninstall` on ``rebased_to_ref`` and ``ref``, and return :const:`True`. Otherwise :const:`False` may be returned. .. versionadded:: 1.3.2 :param remote: The remote for the ref we are processing :param ref: The ref we are processing :param reason: The eol reason, or :const:`None` :param rebased_to_ref: The new name, if rebased, or :const:`None` :param previous_ids: The previous names for the rebased ref (if any), including the one from ``ref`` .. method:: install_authenticator(remote: str, authenticator_ref: str) -> None The ::install-authenticator signal gets emitted if, as part of resolving the transaction, we need to use an authenticator, but the authentication is not installed, but is available to be installed from the ref. The application can handle this signal, and if so create another transaction to install the authenticator. The default handler does nothing, and if the authenticator is not installed when the signal handler fails the transaction will error out. .. versionadded:: 1.8.0 :param remote: The remote name :param authenticator_ref: The ref for the authenticator .. method:: new_operation(operation: ~gi.repository.Flatpak.TransactionOperation, progress: ~gi.repository.Flatpak.TransactionProgress) -> None The ::new-operation signal gets emitted during the execution of the transaction when a new operation is beginning. :param operation: The new :obj:`~gi.repository.Flatpak.TransactionOperation` :param progress: A :obj:`~gi.repository.Flatpak.TransactionProgress` for ``operation`` .. method:: operation_done(operation: ~gi.repository.Flatpak.TransactionOperation, commit: str | None, result: ~gi.repository.Flatpak.TransactionResult) -> None The ::operation-done signal gets emitted during the execution of the transaction when an operation is finished. :param operation: The :obj:`~gi.repository.Flatpak.TransactionOperation` which finished :param commit: The commit :param result: A :obj:`~gi.repository.Flatpak.TransactionResult` giving details about the result .. method:: operation_error(operation: ~gi.repository.Flatpak.TransactionOperation, error: ~gi.repository.GLib.GError, details: ~gi.repository.Flatpak.TransactionErrorDetails) -> bool The ::operation-error signal gets emitted when an error occurs during the execution of the transaction. :param operation: The :obj:`~gi.repository.Flatpak.TransactionOperation` which failed :param error: A :obj:`~gi.repository.GLib.Error` :param details: A :obj:`~gi.repository.Flatpak.TransactionErrorDetails` with details about the error .. method:: ready() -> bool The ::ready signal is emitted when all the refs involved in the operation have been resolved to commits, and the required authentication for all ops is gotten. At this point :func:`~gi.repository.Flatpak.Transaction.get_operations` will return all the operations that will be executed as part of the transaction. .. method:: ready_pre_auth() -> bool The ::ready-pre-auth signal is emitted when all the refs involved in the transaction have been resolved to commits, but we might not necessarily have asked for authentication for all their required operations. This is very similar to the ::ready signal, and you can choose which one (or both) to use depending on how you want to handle authentication in your user interface. At this point :func:`~gi.repository.Flatpak.Transaction.get_operations` will return all the operations that will be executed as part of the transaction. You can call :func:`~gi.repository.Flatpak.TransactionOperation.get_requires_authentication` to see which will require authentication. .. versionadded:: 1.9.1 .. method:: webflow_done(options: ~gi.repository.GLib.Variant, id: int) -> None The ::webflow-done signal gets emitted when the authentication finished the webflow, independent of the reason and results. If you for were showing a web-browser window it can now be closed. .. versionadded:: 1.5.1 :param options: Extra options, currently unused :param id: The id of the operation .. method:: webflow_start(remote: str, url: str, options: ~gi.repository.GLib.Variant, id: int) -> bool The ::webflow-start signal gets emitted when some kind of user authentication is needed during the operation. If the caller handles this it should show the url in a webbrowser and return :const:`True`. This will eventually cause the webbrowser to finish the authentication operation and operation will continue, as signaled by the webflow-done being emitted. If the client does not support webflow then return :const:`False` from this signal (or don't implement it). This will abort the authentication and likely result in the transaction failing (unless the authentication was somehow optional). During the time between webflow-start and webflow-done the client can call :func:`~gi.repository.Flatpak.Transaction.abort_webflow` to manually abort the authentication. This is useful if the user aborted the authentication operation some way, like e.g. closing the browser window. .. versionadded:: 1.5.1 :param remote: The remote we're authenticating with :param url: The url to show :param options: Extra options, currently unused :param id: The id of the operation, can be used to cancel it Virtual Methods --------------- .. rst-class:: interim-class .. class:: Transaction :no-index: .. method:: do_add_new_remote(reason: ~gi.repository.Flatpak.TransactionRemoteReason, from_id: str, remote_name: str, url: str) -> bool :param reason: :param from_id: :param remote_name: :param url: .. method:: do_basic_auth_start(remote: str, realm: str, options: ~gi.repository.GLib.Variant, id: int) -> bool :param remote: :param realm: :param options: :param id: .. method:: do_choose_remote_for_ref(for_ref: str, runtime_ref: str, remotes: str) -> int :param for_ref: :param runtime_ref: :param remotes: .. method:: do_end_of_lifed(ref: str, reason: str, rebase: str) -> None :param ref: :param reason: :param rebase: .. method:: do_end_of_lifed_with_rebase(remote: str, ref: str, reason: str, rebased_to_ref: str, previous_ids: str) -> bool :param remote: :param ref: :param reason: :param rebased_to_ref: :param previous_ids: .. method:: do_install_authenticator(remote: str, authenticator_ref: str) -> None :param remote: :param authenticator_ref: .. method:: do_new_operation(operation: ~gi.repository.Flatpak.TransactionOperation, progress: ~gi.repository.Flatpak.TransactionProgress) -> None :param operation: :param progress: .. method:: do_operation_done(operation: ~gi.repository.Flatpak.TransactionOperation, commit: str, details: ~gi.repository.Flatpak.TransactionResult) -> None :param operation: :param commit: :param details: .. method:: do_operation_error(operation: ~gi.repository.Flatpak.TransactionOperation, error: ~gi.repository.GLib.GError, detail: ~gi.repository.Flatpak.TransactionErrorDetails) -> bool :param operation: :param error: :param detail: .. method:: do_ready() -> bool .. method:: do_ready_pre_auth() -> bool .. method:: do_run(cancellable: ~gi.repository.Gio.Cancellable | None = None) -> bool Executes the transaction. During the course of the execution, various signals will get emitted. The FlatpakTransaction::choose-remote-for-ref and :obj:`~gi.repository.Flatpak.Transaction`::add-new-remote signals may get emitted while resolving operations. :obj:`~gi.repository.Flatpak.Transaction`::ready is emitted when the transaction has been fully resolved, and :obj:`~gi.repository.Flatpak.Transaction`::new-operation and :obj:`~gi.repository.Flatpak.Transaction`::operation-done are emitted while the operations are carried out. If an error occurs at any point during the execution, :obj:`~gi.repository.Flatpak.Transaction`::operation-error is emitted. Note that this call blocks until the transaction is done. :param cancellable: a :obj:`~gi.repository.Gio.Cancellable` .. method:: do_webflow_done(options: ~gi.repository.GLib.Variant, id: int) -> None :param options: :param id: .. method:: do_webflow_start(remote: str, url: str, options: ~gi.repository.GLib.Variant, id: int) -> bool :param remote: :param url: :param options: :param id: Fields ------ .. rst-class:: interim-class .. class:: Transaction :no-index: .. attribute:: parent_instance