Alerts

The Alert class provides imperative access to the host platform's alert dialogs and action sheets. Alerts are not part of the element tree.

There are three entry points:

• Alert.show: fire-and-forget one-button notice (no return value).
• Alert.confirm: awaitable two-button yes/no, resolves to a bool.
• Alert.choose: awaitable multi-button picker / action sheet, resolves to the selected label (or None if dismissed).

Imperative, awaitable system alerts.

Inspired by React Native's Alert.alert() but designed around async / await instead of per-button callbacks. There are three entry points:

• Alert.show: fire-and-forget one-button notice (no return value).
• Alert.confirm: awaitable two-button yes/no, resolves to a bool.
• Alert.choose: awaitable multi-button picker / action sheet, resolves to the selected label (or None if dismissed).

Example

import pythonnative as pn


async def maybe_delete():
    if await pn.Alert.confirm(
        title="Delete item?",
        message="This action cannot be undone.",
        confirm_label="Delete",
        cancel_label="Keep",
    ):
        await delete_item()

Classes:

Name	Description
Alert	Imperative alert / action-sheet helper.

Alert

Imperative alert / action-sheet helper.

All methods are static. Use show for a fire-and-forget single-button notice, confirm for an awaitable yes/no dialog, and choose for a multi-option picker.

Methods:

Name	Description
set_test_response	Queue indices to return from upcoming test alerts.
show	Display a simple, one-button alert and return immediately.
confirm	Present a two-button yes/no dialog and wait for the choice.
choose	Present a multi-option picker and wait for the user's choice.

set_test_response staticmethod

set_test_response(*indices: int) -> None

Queue indices to return from upcoming test alerts.

Use in async tests to script the user's choices: each pending call to confirm or choose pops the next queued index. Pass -1 to simulate a dismiss.

Parameters:

Name	Type	Description	Default
*indices	int	Sequence of button indices to deliver, oldest first. Calls beyond the queue length resolve to -1.	()

show staticmethod

show(title: str, message: Optional[str] = None, *, button: str = 'OK') -> None

Display a simple, one-button alert and return immediately.

Parameters:

Name	Type	Description	Default
title	str	Dialog title.	required
message	Optional[str]	Optional body text.	None
button	str	Label for the single dismiss button (default "OK").	'OK'

This is fire-and-forget. To know what the user did, use confirm or choose and await the result.

confirm async staticmethod

confirm(title: str, message: Optional[str] = None, *, confirm_label: str = 'OK', cancel_label: str = 'Cancel') -> bool

Present a two-button yes/no dialog and wait for the choice.

Parameters:

Name	Type	Description	Default
title	str	Dialog title.	required
message	Optional[str]	Optional body text.	None
confirm_label	str	Label for the "yes" button (default "OK").	'OK'
cancel_label	str	Label for the "no" button (default "Cancel").	'Cancel'

Returns:

Type	Description
bool	True if the user pressed the confirm button, False
bool	for the cancel button or a dismiss.

Example

if await pn.Alert.confirm("Save changes?"):
    await save()

choose async staticmethod

choose(title: str, options: Sequence[str], *, message: Optional[str] = None, cancel_label: Optional[str] = None, style: str = 'action_sheet', destructive_labels: Sequence[str] = ()) -> Optional[str]

Present a multi-option picker and wait for the user's choice.

Parameters:

Name	Type	Description	Default
title	str	Dialog title.	required
options	Sequence[str]	Sequence of option labels (in display order).	required
message	Optional[str]	Optional body text.	None
cancel_label	Optional[str]	If provided, adds a "cancel" button with this label. Selecting it resolves to None.	None
style	str	"action_sheet" (default) for an iOS-style sheet, or "alert" for a stacked alert dialog.	'action_sheet'
destructive_labels	Sequence[str]	Labels in options that should be styled destructively (red on iOS).	()

Returns:

Type	Description
Optional[str]	The selected label, or None if the user dismissed or
Optional[str]	tapped the cancel button.

Example

choice = await pn.Alert.choose(
    "Photo source",
    options=["Camera", "Gallery"],
    cancel_label="Cancel",
)
if choice == "Camera":
    ...

Patterns

• Confirm before destructive actions: await pn.Alert.confirm(...) inside an async def, then branch on the boolean result.
• Pick from options: await pn.Alert.choose(title, options=[...]) returns the selected label.
• Pickers: the built-in Picker component is implemented on top of action sheets; use it for select/dropdown widgets.

Testing

When running off-device (e.g., in unit tests), the alert dispatch records each call to Alert._test_log instead of presenting a dialog. Use Alert.set_test_response(*indices) to script the user's choices for upcoming confirm / choose calls. Reset the log with Alert._test_log.clear() between cases.