juno.dialogs

Native UIKit dialogs from Python — alerts, action sheets, date / time pickers, and single-line text input.

All functions are blocking: each call presents a modal dialog and returns the user’s response. Stop / KeyboardInterrupt is honoured while a dialog is up — the dialog dismisses and the script continues at the interrupt point.

Typical usage:

from juno import dialogs

if dialogs.confirm("Delete?", "This cannot be undone.",
                   destructive=True):
    ...

name = dialogs.input_alert("Hello", "What's your name?",
                           placeholder="e.g. Alex")
if name:
    print(f"Hi {name}")

choice = dialogs.action_sheet(
    "Quality",
    buttons=["Low", "Medium", "High", "Cancel"],
    cancel=3,
)

when = dialogs.pick_datetime(
    title="Reminder",
    initial=datetime.datetime.now(),
)
juno.dialogs.alert(title, message='', buttons=None, *, cancel=None, destructive=None)

Present a modal alert with one or more buttons.

Parameters:

  • title (str) – Alert title text. May be empty.

  • message (str) – Secondary message below the title. May be empty.

  • buttons (list[str] | None) – Button labels in display order. Defaults to ["OK"] when omitted.

  • cancel (int | None) – Index of the cancel button (gets .cancel styling — bold). Optional.

  • destructive (int | None) – Index of the destructive button (red text). Optional. Cannot equal cancel.

Returns:

The pressed button’s index in buttons.

Raises:

  • TypeError – If any argument has the wrong type.

  • ValueError – If buttons is empty, or cancel / destructive are out of range or collide.

  • DialogsError – If the dialog cannot be presented (no top-most view controller available).

Return type:

int

juno.dialogs.confirm(title, message='', *, ok_text='OK', cancel_text='Cancel', destructive=False)

Present a two-button confirmation alert.

Parameters:

  • title (str) – Alert title.

  • message (str) – Secondary message. May be empty.

  • ok_text (str) – Label for the affirmative button.

  • cancel_text (str) – Label for the cancel button.

  • destructive (bool) – When True, the OK button is styled .destructive (red text). Useful for “Delete” / “Discard” prompts.

Returns:

True when OK was pressed, False when Cancel was pressed.

Raises:

  • TypeError – If destructive is not a real bool (rejects 0 / 1).

  • DialogsError – If the dialog cannot be presented.

Return type:

bool

juno.dialogs.input_alert(title, message='', *, initial='', placeholder='', ok_text='OK', cancel_text='Cancel', secure=False)

Present an alert with a single-line text input field.

Parameters:

  • title (str) – Alert title.

  • message (str) – Secondary message above the input. May be empty.

  • initial (str) – Pre-filled text in the field. Empty by default.

  • placeholder (str) – Grey hint text shown when the field is empty.

  • ok_text (str) – Label for the OK button.

  • cancel_text (str) – Label for the Cancel button.

  • secure (bool) – When True, masks input as a password field.

Returns:

The entered string when the user tapped OK or pressed the on-screen keyboard’s Return key — including the empty string when the user submitted with no input. None when the user tapped Cancel.

Raises:

  • TypeError – If any string argument is not str or secure is not a real bool.

  • DialogsError – If the alert cannot be presented.

Return type:

str | None

juno.dialogs.action_sheet(title='', message='', buttons=None, *, cancel=None, destructive=None)

Present a UIActionSheet (bottom sheet on iPhone, popover on iPad).

Parameters:

  • title (str) – Sheet title. May be empty.

  • message (str) – Secondary message. May be empty.

  • buttons (list[str] | None) – Button labels in display order.

  • cancel (int | None) – Index of the cancel button.

  • destructive (int | None) – Index of the destructive button.

Returns:

The pressed button’s index, or None if the user dismissed the sheet without selecting an option (iPad outside-tap, iPhone interactive swipe-down) and no cancel index was set. When cancel is set, dismissal without selection returns the cancel index — symmetric with tapping the cancel button explicitly.

Raises:

  • TypeError – If any argument has the wrong type.

  • ValueError – If buttons is empty or indices are invalid.

  • DialogsError – If the sheet cannot be presented.

Return type:

int | None

juno.dialogs.pick_date(*, title='', initial=None, minimum=None, maximum=None)

Present a date picker sheet.

Parameters:

  • title (str) – Sheet title shown in the navigation bar.

  • initial (date | None) – Pre-selected date. Defaults to the current date when omitted.

  • minimum (date | None) – Earliest selectable date. No lower bound when omitted.

  • maximum (date | None) – Latest selectable date. No upper bound when omitted.

Returns:

The picked datetime.date, or None if the user cancelled (Cancel button or interactive sheet dismissal).

Raises:

  • TypeError – If any argument has the wrong type. In particular, datetime.datetime is not an accepted date here.

  • ValueError – If minimum > maximum or initial is outside [minimum, maximum].

  • DialogsError – If the picker cannot be presented.

Return type:

date | None

juno.dialogs.pick_time(*, title='', initial=None)

Present a time-of-day picker sheet.

Note

UIDatePicker exposes minute granularity. The picker ignores second and microsecond on the input side (truncated to zero before display) and always returns a datetime.time with second=0 and microsecond=0.

Parameters:

  • title (str) – Sheet title.

  • initial (time | None) – Pre-selected time. Defaults to the current time when omitted.

Returns:

The picked datetime.time, or None on cancel.

Raises:
Return type:

time | None

juno.dialogs.pick_datetime(*, title='', initial=None, minimum=None, maximum=None)

Present a combined date + time picker sheet.

Note

Values are interpreted in the device’s current calendar and time zone (local-naive). Aware datetimes are rejected — convert with dt.replace(tzinfo=None) first. Sub-minute precision is silently truncated; the returned datetime always has second=0 and microsecond=0.

Parameters:

  • title (str) – Sheet title.

  • initial (datetime | None) – Pre-selected datetime. Defaults to the current local datetime when omitted.

  • minimum (datetime | None) – Earliest selectable datetime.

  • maximum (datetime | None) – Latest selectable datetime.

Returns:

The picked datetime.datetime, or None on cancel.

Raises:

  • TypeError – If any argument has the wrong type. Plain datetime.date is not accepted.

  • ValueError – If initial is timezone-aware, or minimum > maximum (after truncation), or initial is outside the bounds.

  • DialogsError – If the picker cannot be presented.

Return type:

datetime | None

exception juno.dialogs.DialogsError

Bases: Exception

Raised when a dialog cannot be presented (e.g. no top view controller available). Argument validation raises TypeError / ValueError instead.