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
- 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 toqtrio.Runner.run()
.
-
quit_application
¶ When true, the
done_callback()
method will quit the application when the async function passed toqtrio.Runner.run()
has completed.
-
timeout
¶ If not :py:object`None`, use
trio.move_on_after()
to cancel aftertimeout
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 totrio.lowlevel.start_guest_run()
but will call the callback passed here before (maybe) quitting the application. Theoutcome.Outcome
from the completion of the async function passed torun()
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.
-
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.
-
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.
-
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 fromqtrio.run()
or available on instances ofqtrio.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
-
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.
-