Core

Running

qtrio.run(async_fn, *args, done_callback=None)

Run a Trio-flavored async function in guest mode on a Qt host application, and return the outcomes.

Parameters
Return type

Outcomes

Returns

The qtrio.Outcomes with both the Trio and Qt outcomes.

class qtrio.Runner(application=NOTHING, quit_application=True, timeout=None, reenter=NOTHING, done_callback=None)

This class helps run Trio in guest mode on a Qt host application.

application

The Qt application object to run as the host. If not set before calling run() the application will be created as QtWidgets.QApplication(sys.argv[1:]) and .setQuitOnLastWindowClosed(False) will be called on it to allow the application to continue throughout the lifetime of the async function passed to qtrio.Runner.run().

quit_application

When true, the done_callback() method will quit the application when the async function passed to qtrio.Runner.run() has completed.

timeout

If not :py:object`None`, use trio.move_on_after() to cancel after timeout seconds and raise.

reenter

The QObject instance which will receive the events requesting execution of the needed Trio and user code in the host’s event loop and thread.

done_callback

The builtin done_callback() will be passed to trio.lowlevel.start_guest_run() but will call the callback passed here before (maybe) quitting the application. The outcome.Outcome from the completion of the async function passed to run() will be passed to this callback.

outcomes

The outcomes from the Qt and Trio runs.

cancel_scope

An all encompassing cancellation scope for the Trio execution.

run(async_fn, *args, execute_application=True)

Start the guest loop executing async_fn.

Parameters

  • async_fn (Callable[[], Awaitable[None]]) – The async function to be run in the Qt host loop by the Trio guest.

  • args – Arguments to pass when calling async_fn.

  • execute_application (bool) – If True, the Qt application will be executed and this call will block until it finishes.

Return type

Outcomes

Returns

If execute_application is true, an Outcomes containing outcomes from the Qt application and async_fn will be returned. Otherwise, an empty Outcomes.

run_sync_soon_threadsafe(fn)

Helper for the Trio guest to execute a sync function in the Qt host thread when called from the Trio guest thread. This call will not block waiting for completion of fn nor will it return the result of calling fn.

Parameters

fn (Callable[[], Any]) – A no parameter callable.

Return type

None

await trio_main(async_fn, args)

Will be run as the main async function by the Trio guest. It creates a cancellation scope to be cancelled when QtGui.QGuiApplication.lastWindowClosed is emitted. Within this scope the application’s async_fn will be run and passed args.

Parameters

  • async_fn (Callable[…, Awaitable[None]]) – The application’s main async function to be run by Trio in the Qt host’s thread.

  • args (Tuple[Any, …]) – Positional arguments to be passed to async_fn

Return type

None

trio_done(run_outcome)

Will be called after the Trio guest run has finished. This allows collection of the outcome.Outcome and execution of any application provided done callback. Finally, if quit_application was set when creating the instance then the Qt application will be requested to quit().

Actions such as outputting error information or unwrapping the outcomes need to be further considered.

Return type

None

class qtrio.Outcomes(qt=None, trio=None)

This class holds an outcome.Outcome from each of the Trio and the Qt application execution. Do not construct instances directly. Instead, an instance will be returned from qtrio.run() or available on instances of qtrio.Runner.outcomes.

qt

The Qt application outcome.Outcome

trio

The Trio async function outcome.Outcome

unwrap()

Unwrap either the Trio or Qt outcome. First, errors are given priority over success values. Second, the Trio outcome gets priority over the Qt outcome. If both are still None a qtrio.NoOutcomesError is raised.

Emissions

The basics of handling Qt GUIs is to respond to the widgets’ signals being emitted. qtrio.enter_emissions_channel() is the primary tool for handling this. It allows for connection of signals prior to showing a window and subsequent iteration of the emissions. See the emissions example for an example usage.

async with qtrio.enter_emissions_channel(signals, max_buffer_size=inf)

Create a memory channel fed by the emissions of the signals and enter both the send and receive channels’ context managers.

Parameters

  • signals (Collection[Signal]) – A collection of signals which will be monitored for emissions.

  • max_buffer_size – When the number of unhandled emissions in the channel reaches this limit then additional emissions will be silently thrown out the window.

Return type

AsyncGenerator[MemoryReceiveChannel, None]

class qtrio.Emission(signal, args)

Stores the emission of a signal including the emitted arguments. Can be compared against a signal instance to check the source. Do not construct this class directly. Instead, instances will be received through a channel created by qtrio.enter_emissions_channel().

Note

Each time you access a signal such as a_qobject.some_signal you get a different signal instance object so the signal attribute generally will not be the same object. A signal instance is a QtCore.SignalInstance in PySide2 or QtCore.pyqtBoundSignal in PyQt5.

signal

An instance of the original signal.

args

A tuple of the arguments emitted by the signal.

class qtrio.Emissions(channel, send_channel)

Hold elements useful for the application to work with emissions from signals. Do not construct this class directly. Instead, use qtrio.enter_emissions_channel().

channel

A memory receive channel to be fed by signal emissions.

send_channel

A memory send channel collecting signal emissions.