Showing exceptions in a dialog¶
exceptions_as_dialog is a context manager that catches exceptions raised in
its block, and shows them in a QMessageBox (or a QErrorMessage, which lets
the user hide messages they've seen), instead of letting them propagate.
exceptions_as_dialog
¶
exceptions_as_dialog(
exceptions: type[BaseException]
| tuple[type[BaseException], ...] = Exception,
icon: Icon = Critical,
title: str = "An error occurred",
msg_template: str = "{exc_value}",
buttons: StandardButton = Ok,
parent: QWidget | None = None,
flags: WindowType = _DEFAULT_FLAGS,
use_error_message: bool | QErrorMessage = False,
)
Context manager that shows a dialog when an exception is raised.
See examples below for common usage patterns.
To determine whether an exception was raised or not, check the exception
attribute after the context manager has exited. If use_error_message is False
(the default), you can also access the dialog attribute to get/manipulate the
QMessageBox instance.
Parameters:
-
exceptions(type[BaseException] | tuple[type[BaseException], ...], default:Exception) –The exception(s) to catch, by default
Exception(i.e. all exceptions). -
icon(Icon, default:Critical) –The icon to show in the QMessageBox, by default
QMessageBox.Icon.Critical -
title(str, default:'An error occurred') –The title of the
QMessageBox, by default"An error occurred". -
msg_template(str, default:'{exc_value}') –The message to show in the
QMessageBox. The message will be formatted using three variables:exc_value: the exception instanceexc_type: the exception typetb: the traceback as a string
The default template is the content of the exception:
"{exc_value}" -
buttons(StandardButton, default:Ok) –The buttons to show in the
QMessageBox, by defaultQMessageBox.StandardButton.Ok -
parent(QWidget | None, default:None) –The parent widget of the
QMessageBox, by defaultNone -
use_error_message(bool | QErrorMessage, default:False) –Whether to use a
QErrorMessageinstead of aQMessageBox. By defaultFalse.QErrorMessageshows a checkbox that the user can check to prevent seeing the message again (based on the text of the formattedmsg_template.) IfTrue, the globalQMessageError.qtHandler()instance is used to maintain a history of dismissed messages. You may also pass aQErrorMessageinstance to use a specific instance. Ifuse_error_messageis True, or if you pass your ownQErrorMessageinstance, theparentargument is ignored.
Attributes:
-
dialog(QMessageBox | None) –The
QMessageBoxinstance that was created (ifuse_error_messagewasFalse). This can be used, among other things, to determine the result of the dialog (e.g.dialog.result()) or to manipulate the dialog (e.g.dialog.setDetailedText("some text")). -
exception(BaseException | None) –Will hold the exception instance if an exception was raised and caught.
Examples:
from qtpy.QtWidgets import QApplication
from superqt.utils import exceptions_as_dialog
app = QApplication([])
with exceptions_as_dialog() as ctx:
raise Exception("This will be caught and shown in a QMessageBox")
# you can access the exception instance here
assert ctx.exception is not None
# with exceptions_as_dialog(ValueError):
# 1 / 0 # ZeroDivisionError is not caught, so this will raise
with exceptions_as_dialog(msg_template="Error: {exc_value}"):
raise Exception("This message will be inserted at 'exc_value'")
for _i in range(3):
with exceptions_as_dialog(AssertionError, use_error_message=True):
assert False, "Uncheck the checkbox to ignore this in the future"
# use ctx.dialog to get the result of the dialog
btns = QMessageBox.StandardButton.Ok | QMessageBox.StandardButton.Cancel
with exceptions_as_dialog(buttons=btns) as ctx:
raise Exception("This will be caught and shown in a QMessageBox")
print(ctx.dialog.result()) # prints which button was clicked
app.exec() # needed only for the use_error_message example to show