Skip to content

Commit

Permalink
Update docs to make async methods clearly async.
Browse files Browse the repository at this point in the history
  • Loading branch information
@freakboy3742
freakboy3742 committed Dec 13, 2023
1 parent 26285dd commit 92a1629
Show file tree
Hide file tree
Showing 2 changed files with 68 additions and 41 deletions.
12 changes: 6 additions & 6 deletions core/src/toga/widgets/webview.py
View file
Original file line number Diff line number Diff line change
Expand Up @@ -126,13 +126,13 @@ def set_content(self, root_url: str, content: str):
def evaluate_javascript(self, javascript, on_result=None) -> JavaScriptResult:
"""Evaluate a JavaScript expression.
There is no guarantee that the JavaScript has finished evaluating when this
method returns. The object returned by this method can be awaited to obtain the
value of the expression, or you can provide an ``on_result`` callback.
**This is an asynchronous method**. There is no guarantee that the JavaScript
has finished evaluating when this method returns. The object returned by this
method can be awaited to obtain the value of the expression.
**Note:** On Android and Windows, *no exception handling is performed*.
If a JavaScript error occurs, a return value of None will be reported,
but no exception will be provided.
**Note:** On Android and Windows, *no exception handling is performed*. If a
JavaScript error occurs, a return value of None will be reported, but no
exception will be provided.
:param javascript: The JavaScript expression to evaluate.
:param on_result: **DEPRECATED** ``await`` the return value of this method.
Expand Down
97 changes: 62 additions & 35 deletions core/src/toga/window.py
View file
Original file line number Diff line number Diff line change
Expand Up @@ -353,11 +353,15 @@ def info_dialog(
Presents as a dialog with a single "OK" button to close the dialog.
**This is an asynchronous method**. If you invoke this method in synchronous
context, it will show the dialog, but will return *immediately*. The object
returned by this method can be awaited to obtain the result of the dialog.
:param title: The title of the dialog window.
:param message: The message to display.
:param on_result: **DEPRECATED** ``await`` the return value of this method.
:returns: An awaitable Dialog object. The Dialog object returns
``None`` when the user presses the 'OK' button.
:returns: An awaitable Dialog object. The Dialog object returns ``None`` when
the user presses the 'OK' button.
"""
dialog = Dialog(
self,
Expand All @@ -376,12 +380,15 @@ def question_dialog(
Presents as a dialog with "Yes" and "No" buttons.
**This is an asynchronous method**. If you invoke this method in synchronous
context, it will show the dialog, but will return *immediately*. The object
returned by this method can be awaited to obtain the result of the dialog.
:param title: The title of the dialog window.
:param message: The question to be answered.
:param on_result: **DEPRECATED** ``await`` the return value of this method.
:returns: An awaitable Dialog object. The Dialog object returns
``True`` when the "Yes" button is pressed, ``False`` when
the "No" button is pressed.
:returns: An awaitable Dialog object. The Dialog object returns ``True`` when
the "Yes" button is pressed, ``False`` when the "No" button is pressed.
"""
dialog = Dialog(
self,
Expand All @@ -398,15 +405,18 @@ def confirm_dialog(
) -> Dialog:
"""Ask the user to confirm if they wish to proceed with an action.
Presents as a dialog with "Cancel" and "OK" buttons (or whatever labels
are appropriate on the current platform).
Presents as a dialog with "Cancel" and "OK" buttons (or whatever labels are
appropriate on the current platform).
**This is an asynchronous method**. If you invoke this method in synchronous
context, it will show the dialog, but will return *immediately*. The object
returned by this method can be awaited to obtain the result of the dialog.
:param title: The title of the dialog window.
:param message: A message describing the action to be confirmed.
:param on_result: **DEPRECATED** ``await`` the return value of this method.
:returns: An awaitable Dialog object. The Dialog object returns
``True`` when the "OK" button is pressed, ``False`` when
the "Cancel" button is pressed.
:returns: An awaitable Dialog object. The Dialog object returns ``True`` when
the "OK" button is pressed, ``False`` when the "Cancel" button is pressed.
"""
dialog = Dialog(
self,
Expand All @@ -425,11 +435,15 @@ def error_dialog(
Presents as an error dialog with a "OK" button to close the dialog.
**This is an asynchronous method**. If you invoke this method in synchronous
context, it will show the dialog, but will return *immediately*. The object
returned by this method can be awaited to obtain the result of the dialog.
:param title: The title of the dialog window.
:param message: The error message to display.
:param on_result: **DEPRECATED** ``await`` the return value of this method.
:returns: An awaitable Dialog object. The Dialog object returns
``None`` when the user presses the "OK" button.
:returns: An awaitable Dialog object. The Dialog object returns ``None`` when
the user presses the "OK" button.
"""
dialog = Dialog(
self,
Expand Down Expand Up @@ -481,12 +495,15 @@ def stack_trace_dialog(
) -> Dialog:
"""Open a dialog to display a large block of text, such as a stack trace.
**This is an asynchronous method**. If you invoke this method in synchronous
context, it will show the dialog, but will return *immediately*. The object
returned by this method can be awaited to obtain the result of the dialog.
:param title: The title of the dialog window.
:param message: Contextual information about the source of the stack trace.
:param content: The stack trace, pre-formatted as a multi-line string.
:param retry: If true, the user will be given options to "Retry" or
"Quit"; if false, a single option to acknowledge the error will
be displayed.
:param retry: If true, the user will be given options to "Retry" or "Quit"; if
false, a single option to acknowledge the error will be displayed.
:param on_result: **DEPRECATED** ``await`` the return value of this method.
:returns: An awaitable Dialog object. If ``retry`` is true, the Dialog object
returns ``True`` when the user selects "Retry", and ``False`` when they
Expand Down Expand Up @@ -516,10 +533,14 @@ def save_file_dialog(
This dialog is not currently supported on Android or iOS.
**This is an asynchronous method**. If you invoke this method in synchronous
context, it will show the dialog, but will return *immediately*. The object
returned by this method can be awaited to obtain the result of the dialog.
:param title: The title of the dialog window
:param suggested_filename: A default filename
:param file_types: The allowed filename extensions, without leading dots. If
not provided, any extension will be allowed.
:param file_types: The allowed filename extensions, without leading dots. If not
provided, any extension will be allowed.
:param on_result: **DEPRECATED** ``await`` the return value of this method.
:returns: An awaitable Dialog object. The Dialog object returns a path object
for the selected file location, or ``None`` if the user cancelled the save
Expand Down Expand Up @@ -595,20 +616,23 @@ def open_file_dialog(
This dialog is not currently supported on Android or iOS.
**This is an asynchronous method**. If you invoke this method in synchronous
context, it will show the dialog, but will return *immediately*. The object
returned by this method can be awaited to obtain the result of the dialog.
:param title: The title of the dialog window
:param initial_directory: The initial folder in which to open the dialog.
If ``None``, use the default location provided by the operating system
(which will often be the last used location)
:param file_types: The allowed filename extensions, without leading dots. If
not provided, all files will be shown.
:param multiple_select: If True, the user will be able to select multiple
files; if False, the selection will be restricted to a single file.
:param initial_directory: The initial folder in which to open the dialog. If
``None``, use the default location provided by the operating system (which
will often be the last used location)
:param file_types: The allowed filename extensions, without leading dots. If not
provided, all files will be shown.
:param multiple_select: If True, the user will be able to select multiple files;
if False, the selection will be restricted to a single file.
:param on_result: **DEPRECATED** ``await`` the return value of this method.
:param multiselect: **DEPRECATED** Use ``multiple_select``.
:returns: An awaitable Dialog object. The Dialog object returns
a list of ``Path`` objects if ``multiple_select`` is ``True``, or a single
``Path`` otherwise. Returns ``None`` if the open operation is
cancelled by the user.
:returns: An awaitable Dialog object. The Dialog object returns a list of
``Path`` objects if ``multiple_select`` is ``True``, or a single ``Path``
otherwise. Returns ``None`` if the open operation is cancelled by the user.
"""
######################################################################
# 2023-08: Backwards compatibility
Expand Down Expand Up @@ -681,19 +705,22 @@ def select_folder_dialog(
This dialog is not currently supported on Android or iOS.
**This is an asynchronous method**. If you invoke this method in synchronous
context, it will show the dialog, but will return *immediately*. The object
returned by this method can be awaited to obtain the result of the dialog.
:param title: The title of the dialog window
:param initial_directory: The initial folder in which to open the dialog.
If ``None``, use the default location provided by the operating system
(which will often be "last used location")
:param initial_directory: The initial folder in which to open the dialog. If
``None``, use the default location provided by the operating system (which
will often be "last used location")
:param multiple_select: If True, the user will be able to select multiple
directories; if False, the selection will be restricted to a single
directory. This option is not supported on WinForms.
:param on_result: **DEPRECATED** ``await`` the return value of this method.
:param multiselect: **DEPRECATED** Use ``multiple_select``.
:returns: An awaitable Dialog object. The Dialog object returns
a list of ``Path`` objects if ``multiple_select`` is ``True``, or a single
``Path`` otherwise. Returns ``None`` if the open operation is
cancelled by the user.
:returns: An awaitable Dialog object. The Dialog object returns a list of
``Path`` objects if ``multiple_select`` is ``True``, or a single ``Path``
otherwise. Returns ``None`` if the open operation is cancelled by the user.
"""
######################################################################
# 2023-08: Backwards compatibility
Expand Down

0 comments on commit 92a1629

Please sign in to comment.