Dialog

swiftDialog integration for user-facing dialogs and notifications (macOS only).

class Dialog(binary_path: str | None = None, temp_dir: str | Path | None = None, use_temp_file: bool = False)[source]

Bases: object

Executor class for displaying swiftDialog dialogs.

This class handles binary discovery, command building, subprocess execution, and temp file management for displaying DialogTemplate configurations.

By default, passes JSON configuration via –jsonstring (in-memory) to avoid file permission issues when running as root via MDM. When use_temp_file=True, creates a world-readable temp file for compatibility with all users.

Parameters:

  • binary_path (str | None, optional) – Path to swiftDialog binary, or None to auto-discover

  • temp_dir (str | Path, optional) – Directory for temp file creation. Defaults to /Users/Shared for multi-user accessibility. Only used when use_temp_file=True

  • use_temp_file (bool, optional) – If True, write JSON config to a temp file instead of passing as string. The temp file is created with world-readable permissions (0o644) for MDM compatibility. Defaults to False

Example:
>>> dialog = Dialog()
>>> template = DialogTemplate(title="Hello", message="World")
>>> result = dialog.show(template)
>>> if result.ok:
...     print("User clicked OK")
show(template: DialogTemplate | SystemNotification, logger: MdmLogger | None = None, timeout: int | None = None, check_console_user: bool = True) → DialogReturn[source]

Display the dialog using swiftDialog.

Parameters:

  • template (DialogTemplate | SystemNotification) – DialogTemplate or SystemNotification with dialog configuration

  • logger (MdmLogger | None, optional) – Optional MdmLogger instance for logging, defaults to None

  • timeout (int | None, optional) – Timeout in seconds for dialog execution, defaults to None

  • check_console_user (bool, optional) – Whether to check for console user before showing dialog, defaults to True

Returns:

DialogReturn instance with results

Return type:

DialogReturn

static update_command_file(command_file: str | Path, updates: dict[str, Any]) → None[source]

Update dialog content dynamically via command file.

This method writes update commands to the command file specified in the dialog template, allowing real-time updates to dialog content.

Parameters:

  • command_file (str | Path) – Path to the command file

  • updates (dict[str, Any]) – Dictionary of updates (e.g., {“title”: “New Title”, “message”: “New Message”})

Raises:

IOError – If the command file cannot be written

Return type:

None

class DialogTemplate(title: str = '', subtitle: str | None = None, message: str | None = None, style: Style | None = None, alignment: MessageAlignment | None = None, position: MessagePosition | None = None, help_message: str | None = None, help_image: str | Path | None = None, icon: str | Path | None = None, icon_size: int | None = None, icon_alpha: int | None = None, overlay_icon: str | Path | None = None, banner_image: str | Path | None = None, banner_title: str | None = None, banner_text: str | None = None, button1_text: str | None = None, button1_action: str | None = None, button2_text: str | None = None, button2_action: str | None = None, info_button_text: str | None = None, info_button_action: str | None = None, button_style: ButtonStyle | None = None, button_size: ButtonSize | None = None, small: bool = False, big: bool = False, fullscreen: bool = False, ontop: bool = False, moveable: bool = False, width: int | None = None, height: int | None = None, textfields: list[TextField] = <factory>, selectitems: list[SelectItem] = <factory>, radioitems: list[SelectItem] = <factory>, checkboxes: list[CheckboxItem] = <factory>, infobox: str | None = None, timer: int | None = None, timerbar: bool = False, progress: int | None = None, commandfile: str | Path | None = None, json: bool = True, webcontent: str | None = None, video: str | Path | None = None, video_position: str | None = None, quitkey: str | None = None, quit_on_info: bool = False)[source]

Template for configuring swiftDialog dialogs.

This dataclass provides a comprehensive interface for defining dialog configurations including text fields, selects, checkboxes, timers, and more. Use the Dialog class to display templates.

Parameters:

  • title (str) – Dialog title (required)

  • subtitle (str | None, optional) – Optional subtitle text

  • message (str | None, optional) – Main message content (supports markdown)

  • style (Style | None)

  • alignment (MessageAlignment | None)

  • position (MessagePosition | None)

  • help_message (str | None)

  • help_image (str | Path | None)

  • icon (str | Path | None)

  • icon_size (int | None)

  • icon_alpha (int | None)

  • overlay_icon (str | Path | None)

  • banner_image (str | Path | None)

  • banner_title (str | None)

  • banner_text (str | None)

  • button1_text (str | None)

  • button1_action (str | None)

  • button2_text (str | None)

  • button2_action (str | None)

  • info_button_text (str | None)

  • info_button_action (str | None)

  • button_style (ButtonStyle | None)

  • button_size (ButtonSize | None)

  • small (bool)

  • big (bool)

  • fullscreen (bool)

  • ontop (bool)

  • moveable (bool)

  • width (int | None)

  • height (int | None)

  • textfields (list[TextField])

  • selectitems (list[SelectItem])

  • radioitems (list[SelectItem])

  • checkboxes (list[CheckboxItem])

  • infobox (str | None)

  • timer (int | None)

  • timerbar (bool)

  • progress (int | None)

  • commandfile (str | Path | None)

  • json (bool)

  • webcontent (str | None)

  • video (str | Path | None)

  • video_position (str | None)

  • quitkey (str | None)

  • quit_on_info (bool)

Example:
>>> template = DialogTemplate(
...     title="Welcome",
...     message="Please enter your details",
...     textfields=[TextField(title="Username", required=True)],
... )
>>> dialog = Dialog()
>>> result = dialog.show(template)
title: str = ''
subtitle: str | None = None
message: str | None = None
style: Style | None = None
alignment: MessageAlignment | None = None
position: MessagePosition | None = None
help_message: str | None = None
help_image: str | Path | None = None
icon: str | Path | None = None
icon_size: int | None = None
icon_alpha: int | None = None
overlay_icon: str | Path | None = None
banner_image: str | Path | None = None
banner_title: str | None = None
banner_text: str | None = None
button1_text: str | None = None
button1_action: str | None = None
button2_text: str | None = None
button2_action: str | None = None
info_button_text: str | None = None
info_button_action: str | None = None
button_style: ButtonStyle | None = None
button_size: ButtonSize | None = None
small: bool = False
big: bool = False
fullscreen: bool = False
ontop: bool = False
moveable: bool = False
width: int | None = None
height: int | None = None
textfields: list[TextField]
selectitems: list[SelectItem]
radioitems: list[SelectItem]
checkboxes: list[CheckboxItem]
infobox: str | None = None
timer: int | None = None
timerbar: bool = False
progress: int | None = None
commandfile: str | Path | None = None
json: bool = True
webcontent: str | None = None
video: str | Path | None = None
video_position: str | None = None
quitkey: str | None = None
quit_on_info: bool = False
to_jsonstring() → str[source]

Convert DialogTemplate to JSON string for swiftDialog.

Returns:

JSON string representation

Return type:

str

to_dict() → dict[str, Any][source]

Convert DialogTemplate to a dictionary.

Returns:

Dictionary representation of the template

Return type:

dict[str, Any]

Example:
>>> template = DialogTemplate(title="Test", message="Hello")
>>> d = template.to_dict()
>>> d["title"]
'Test'
classmethod from_dict(data: dict[str, Any]) → DialogTemplate[source]

Create DialogTemplate from a dictionary.

Parameters:

data (dict[str, Any]) – Dictionary with dialog configuration options

Returns:

DialogTemplate instance

Return type:

DialogTemplate

Example:
>>> data = {"title": "Test", "message": "Hello", "width": 500}
>>> template = DialogTemplate.from_dict(data)
>>> template.title
'Test'
class DialogReturn(exit_code: int, raw_output: str = '', data: dict[str, ~typing.Any]=<factory>, textfields: dict[str, str]=<factory>, selects: dict[str, ~pymdm.dialog.SelectResult]=<factory>, checkboxes: dict[str, bool]=<factory>)[source]

Structured result from a swiftDialog invocation.

Captures:

  • exit_code: The process return code (see DialogExitCode)

  • raw_output: The raw stdout string

  • data: Parsed JSON dict when –json flag was used

  • textfields: Dict of textfield label -> user input

  • selects: Dict of select title -> SelectResult

  • checkboxes: Dict of checkbox label -> bool

Parameters:
exit_code: int
raw_output: str = ''
data: dict[str, Any]
textfields: dict[str, str]
selects: dict[str, SelectResult]
checkboxes: dict[str, bool]
property ok: bool[source]

True if user clicked Ok/Button1.

property cancelled: bool[source]

True if user clicked Cancel/Button2 or quit.

property timed_out: bool[source]

True if dialog closed due to timer expiration.

property exit_reason: str[source]

Human-readable exit reason.

get_textfield(label: str, default: str = '') → str[source]

Get a textfield value by label.

Parameters:
Return type:

str

get_select(title: str) → SelectResult | None[source]

Get a select result by title.

Parameters:

title (str)

Return type:

SelectResult | None

get_checkbox(label: str, default: bool = False) → bool[source]

Get a checkbox value by label.

Parameters:
Return type:

bool

classmethod from_subprocess(result: CompletedProcess) → DialogReturn[source]

Create from a subprocess.CompletedProcess result.

Parameters:

result (CompletedProcess)

Return type:

DialogReturn

class DialogExitCode(*values)[source]

swiftDialog exit codes.

ok = 0
button2 = 2
info_button = 3
timer_expired = 4
quit_command = 5
user_quit = 10
timer_zero = 20
auth_failed = 30
image_not_found = 201
file_not_found = 202
invalid_color = 203
class SystemNotification(title: str, message: str | None = None, subtitle: str | None = None, icon: str | Path | None = None, button1_text: str | None = None, button1_action: str | None = None, button2_text: str | None = None, button2_action: str | None = None)[source]

Configuration for swiftDialog system notifications (toast).

Unlike full dialogs, notifications only support a limited set of properties. All other DialogTemplate properties are ignored by swiftDialog when –notification is used.

Docs: https://github.com/swiftDialog/swiftDialog/wiki/Notifications

Parameters:

  • title (str)

  • message (str | None)

  • subtitle (str | None)

  • icon (str | Path | None)

  • button1_text (str | None)

  • button1_action (str | None)

  • button2_text (str | None)

  • button2_action (str | None)

title: str
message: str | None = None
subtitle: str | None = None
icon: str | Path | None = None
button1_text: str | None = None
button1_action: str | None = None
button2_text: str | None = None
button2_action: str | None = None
to_jsonstring() → str[source]

Convert to JSON string for swiftDialog.

Return type:

str

class CheckboxItem(label: str, checked: bool = False, disabled: bool = False, icon: str | None = None)[source]

Configuration for a checkbox item in swiftDialog.

Parameters:

  • label (str) – Label text for the checkbox

  • checked (bool, optional) – Whether checkbox is checked by default, defaults to False

  • disabled (bool, optional) – Whether checkbox is disabled, defaults to False

  • icon (str | None, optional) – Icon to display next to checkbox, defaults to None

label: str
checked: bool = False
disabled: bool = False
icon: str | None = None
class SelectItem(title: str, values: list[str] = <factory>, default: str | None = None)[source]

Configuration for a select/dropdown in swiftDialog.

Each SelectItem represents a single dropdown menu with a label and options.

Parameters:

  • title (str) – Label displayed above the dropdown

  • values (list[str]) – List of options to choose from

  • default (str | None, optional) – Default selected value (must match one of the values), defaults to None

title: str
values: list[str]
default: str | None = None
class SelectResult(selected_value: str, selected_index: int)[source]

Parsed result from a dropdown/select field.

Parameters:

  • selected_value (str)

  • selected_index (int)

selected_value: str
selected_index: int
class TextField(title: str, prompt: str | None = None, value: str | None = None, secure: bool = False, required: bool = False, regex: str | None = None, regexerror: str | None = None)[source]

Configuration for a text field in swiftDialog.

Parameters:

  • title (str) – Title/label for the text field (displayed to user)

  • prompt (str | None, optional) – Prompt text shown inside the field, defaults to None

  • value (str | None, optional) – Default value, defaults to None

  • secure (bool, optional) – Whether input should be masked (password field), defaults to False

  • required (bool, optional) – Whether field is required, defaults to False

  • regex (str | None, optional) – Validation regex pattern, defaults to None

  • regexerror (str | None, optional) – Error message to show when regex validation fails, defaults to None

title: str
prompt: str | None = None
value: str | None = None
secure: bool = False
required: bool = False
regex: str | None = None
regexerror: str | None = None