Transaction

class Transaction(**properties: Any)

Superclasses: Object

Implemented Interfaces: Initable

Constructors:

Transaction(**properties)
new_for_installation(installation:Flatpak.Installation, cancellable:Gio.Cancellable=None) -> Flatpak.Transaction

Constructors

class Transaction
classmethod new_for_installation(installation: Installation, cancellable: Cancellable | None = None) → Transaction

Creates a new 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 ().

Parameters:

Methods

class Transaction
abort_webflow(id: int) → None

Cancel an ongoing webflow authentication request. This can be call in the time between Transaction::webflow-start returned True, and 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.

Added in version 1.5.1.

Parameters:

id – The webflow id, as passed into the webflow-start signal

add_default_dependency_sources() → None

Similar to add_dependency_source(), but adds all the default installations, which means all the defined system-wide (but not per-user) installations.

add_dependency_source(installation: 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 add_default_dependency_sources().

Parameters:

installation – a Installation

add_install(remote: str, ref: str, subpaths: 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.

Parameters:

  • remote – the name of the remote

  • ref – the ref

  • subpaths – subpaths to install, or the empty list or None to pull all subpaths

add_install_bundle(file: File, gpg_data: Bytes | None = None) → bool

Adds installing the given bundle to this transaction.

Parameters:

  • file – a File that is an flatpak bundle

  • gpg_data – GPG key with which to check bundle signatures, or None to use the key embedded in the bundle (if any)

add_install_flatpakref(flatpakref_data: Bytes) → bool

Adds installing the given flatpakref to this transaction.

Parameters:

flatpakref_data – data from a flatpakref file

add_rebase(remote: str, ref: str, subpaths: str | None = None, previous_ids: 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 add_rebase_and_uninstall() instead. It will add appropriate dependencies between the rebase and uninstall operations.

See add_install() for a description of remote.

Added in version 1.3.3..

Parameters:

  • remote – the name of the remote

  • ref – the ref

  • subpaths – the subpaths to include, or None to install the complete ref

  • 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).

add_rebase_and_uninstall(remote: str, new_ref: str, old_ref: str, subpaths: str | None = None, previous_ids: 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 add_rebase().

See add_install() for a description of remote.

Added in version 1.15.4.

Parameters:

  • remote – the name of the remote

  • new_ref – the ref to rebase to

  • old_ref – the ref to uninstall

  • subpaths – the subpaths to include, or None to install the complete ref

  • 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).

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.

Added in version 1.7.1.

Parameters:

path – a path to a local flatpak repository

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.

Parameters:

ref – the ref

add_update(ref: str, subpaths: Sequence[str] | None = None, commit: str | None = None) → bool

Adds updating the given ref to this transaction.

Parameters:

  • ref – the ref

  • subpaths – subpaths to install; None to use the current set plus the set of configured languages, or { NULL } or { "", NULL } to pull all subpaths.

  • commit – the commit to update to, or None to use the latest

complete_basic_auth(id: int, user: str, password: str, options: Variant) → None

Finishes (or aborts) an ongoing basic auth request.

Added in version 1.5.2.

Parameters:

  • id – The webflow id, as passed into the webflow-start signal

  • user – The user name, or None if aborting request

  • password – The password

  • options – Extra a{sv] variant with options (or None), currently unused.

get_auto_install_debug() → bool

Gets the value set by set_auto_install_debug().

Added in version 1.13.3.

get_auto_install_sdk() → bool

Gets the value set by set_auto_install_sdk().

Added in version 1.13.3.

get_current_operation() → TransactionOperation

Gets the current operation.

get_include_unused_uninstall_ops() → bool

Gets the value set by set_include_unused_uninstall_ops().

Added in version 1.9.1.

get_installation() → Installation

Gets the installation this transaction was created for.

get_no_deploy() → bool

Gets whether the transaction is only downloading updates, and not deploying them.

Added in version 1.5.1.

get_no_interaction() → bool

Gets whether the transaction is interactive. See set_no_interaction().

Added in version 1.13.0.

get_no_pull() → bool

Gets whether the transaction should operate only on locally available data.

Added in version 1.5.1.

get_operations() → list[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.

get_parent_window() → str

Gets the parent window set for this transaction, or None if unset. See get_parent_window().

Added in version 1.5.1.

is_empty() → bool

Returns whether the transaction contains any non-skipped operations.

run(cancellable: 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 Transaction::add-new-remote signals may get emitted while resolving operations. Transaction::ready is emitted when the transaction has been fully resolved, and Transaction::new-operation and Transaction::operation-done are emitted while the operations are carried out. If an error occurs at any point during the execution, Transaction::operation-error is emitted.

Note that this call blocks until the transaction is done.

Parameters:

cancellable – a Cancellable

set_auto_install_debug(auto_install_debug: bool) → None

When this is set to 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.

Added in version 1.13.3.

Parameters:

auto_install_debug – whether to auto install debug info for apps

set_auto_install_sdk(auto_install_sdk: bool) → None

When this is set to True, Flatpak will automatically install the SDK for each app currently being installed or updated. Does nothing if an uninstall is taking place.

Added in version 1.13.3.

Parameters:

auto_install_sdk – whether to auto install SDKs for apps

set_default_arch(arch: str) → None

Sets the architecture to default to where it is unspecified.

Parameters:

arch – the arch to make default

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.

Added in version 1.9.1.

Parameters:

disable_pin – whether to disable auto-pinning

set_disable_dependencies(disable_dependencies: bool) → None

Sets whether the transaction should ignore runtime dependencies when resolving operations for applications.

Parameters:

disable_dependencies – whether to disable runtime dependencies

set_disable_prune(disable_prune: bool) → None

Sets whether the transaction should avoid pruning the local OSTree repository after updating.

Parameters:

disable_prune – whether to avoid pruning

Sets whether the transaction should avoid adding related refs when resolving operations. Related refs are extensions that are suggested by apps, such as locales.

Parameters:

disable_related – whether to avoid adding related refs

set_disable_static_deltas(disable_static_deltas: bool) → None

Sets whether the transaction should avoid using static deltas when pulling.

Parameters:

disable_static_deltas – whether to avoid static deltas

set_force_uninstall(force_uninstall: bool) → None

Sets whether the transaction should uninstall files even if they’re used by a running application.

Parameters:

force_uninstall – whether to force-uninstall refs

set_include_unused_uninstall_ops(include_unused_uninstall_ops: bool) → None

When this is set to 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 list_unused_refs().

Added in version 1.9.1.

Parameters:

include_unused_uninstall_ops – whether to include unused uninstall ops

set_no_deploy(no_deploy: bool) → None

Sets whether the transaction should download updates, but not deploy them.

Parameters:

no_deploy – whether to avoid deploying

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 Installation is used.

Added in version 1.7.3.

Parameters:

no_interaction – Whether to disallow interactive authorization for operations

set_no_pull(no_pull: bool) → None

Sets whether the transaction should operate only on locally available data.

Parameters:

no_pull – whether to avoid pulls

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.

Added in version 1.5.1.

Parameters:

parent_window – whether to avoid pulls

set_reinstall(reinstall: bool) → None

Sets whether the transaction should uninstall first if a ref is already installed.

Parameters:

reinstall – whether to reinstall refs

Properties

class Transaction
props.installation: Installation

The installation that the transaction operates on.

props.no_interaction: bool

True if the transaction is not interactive, False otherwise.

See set_no_interaction().

Added in version 1.13.0.

Signals

class Transaction.signals
add_new_remote(reason: 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.

Parameters:

  • reason – A TransactionRemoteReason for this suggestion

  • from_id – The id of the app/runtime

  • suggested_remote_name – The suggested remote name

  • url – The repo url

basic_auth_start(remote: str, realm: str, options: 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 True. Once the information is gathered call complete_basic_auth() with it.

If the client does not support basic auth then return 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).

Added in version 1.5.2.

Parameters:

  • remote – The remote we’re authenticating with

  • realm – The url to show

  • options – Extra options, currently unused

  • id – The id of the operation, can be used to finish it

choose_remote_for_ref(for_ref: str, runtime_ref: str, remotes: Sequence[str]) → int

The ::choose-remote-for-ref signal gets emitted when a remote needs to be selected during the execution of the transaction.

Parameters:

  • for_ref – The ref we are installing

  • runtime_ref – The ref we are looking for

  • remotes – the remotes that has the ref, sorted in prio order

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.

Parameters:

  • ref – The ref we are installing

  • reason – The eol reason, or None

  • rebase – The new name, if rebased, or None

end_of_lifed_with_rebase(remote: str, ref: str, reason: str, rebased_to_ref: str, previous_ids: 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 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 add_rebase_and_uninstall() on rebased_to_ref and ref, and return True. Otherwise False may be returned.

Added in version 1.3.2.

Parameters:

  • remote – The remote for the ref we are processing

  • ref – The ref we are processing

  • reason – The eol reason, or None

  • rebased_to_ref – The new name, if rebased, or None

  • previous_ids – The previous names for the rebased ref (if any), including the one from ref

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.

Added in version 1.8.0.

Parameters:

  • remote – The remote name

  • authenticator_ref – The ref for the authenticator

new_operation(operation: TransactionOperation, progress: TransactionProgress) → None

The ::new-operation signal gets emitted during the execution of the transaction when a new operation is beginning.

Parameters:
operation_done(operation: TransactionOperation, commit: str | None, result: TransactionResult) → None

The ::operation-done signal gets emitted during the execution of the transaction when an operation is finished.

Parameters:
operation_error(operation: TransactionOperation, error: GError, details: TransactionErrorDetails) → bool

The ::operation-error signal gets emitted when an error occurs during the execution of the transaction.

Parameters:
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 get_operations() will return all the operations that will be executed as part of the transaction.

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 get_operations() will return all the operations that will be executed as part of the transaction. You can call get_requires_authentication() to see which will require authentication.

Added in version 1.9.1.

webflow_done(options: 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.

Added in version 1.5.1.

Parameters:

  • options – Extra options, currently unused

  • id – The id of the operation

webflow_start(remote: str, url: str, options: 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 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 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 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.

Added in version 1.5.1.

Parameters:

  • remote – The remote we’re authenticating with

  • url – The url to show

  • options – Extra options, currently unused

  • id – The id of the operation, can be used to cancel it

Virtual Methods

class Transaction
do_add_new_remote(reason: TransactionRemoteReason, from_id: str, remote_name: str, url: str) → bool
Parameters:

  • reason

  • from_id

  • remote_name

  • url

do_basic_auth_start(remote: str, realm: str, options: Variant, id: int) → bool
Parameters:

  • remote

  • realm

  • options

  • id

do_choose_remote_for_ref(for_ref: str, runtime_ref: str, remotes: str) → int
Parameters:

  • for_ref

  • runtime_ref

  • remotes

do_end_of_lifed(ref: str, reason: str, rebase: str) → None
Parameters:

  • ref

  • reason

  • rebase

do_end_of_lifed_with_rebase(remote: str, ref: str, reason: str, rebased_to_ref: str, previous_ids: str) → bool
Parameters:

  • remote

  • ref

  • reason

  • rebased_to_ref

  • previous_ids

do_install_authenticator(remote: str, authenticator_ref: str) → None
Parameters:

  • remote

  • authenticator_ref

do_new_operation(operation: TransactionOperation, progress: TransactionProgress) → None
Parameters:

  • operation

  • progress

do_operation_done(operation: TransactionOperation, commit: str, details: TransactionResult) → None
Parameters:

  • operation

  • commit

  • details

do_operation_error(operation: TransactionOperation, error: GError, detail: TransactionErrorDetails) → bool
Parameters:

  • operation

  • error

  • detail

do_ready() → bool
do_ready_pre_auth() → bool
do_run(cancellable: 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 Transaction::add-new-remote signals may get emitted while resolving operations. Transaction::ready is emitted when the transaction has been fully resolved, and Transaction::new-operation and Transaction::operation-done are emitted while the operations are carried out. If an error occurs at any point during the execution, Transaction::operation-error is emitted.

Note that this call blocks until the transaction is done.

Parameters:

cancellable – a Cancellable

do_webflow_done(options: Variant, id: int) → None
Parameters:

  • options

  • id

do_webflow_start(remote: str, url: str, options: Variant, id: int) → bool
Parameters:

  • remote

  • url

  • options

  • id

Fields

class Transaction
parent_instance