quickmacapp 2025.3.18__py3-none-any.whl → 2025.4.15__py3-none-any.whl

quickmacapp/_notifications.py

@@ -0,0 +1,498 @@
+from __future__ import annotations
+
+from dataclasses import dataclass
+from types import TracebackType
+from typing import Any, Awaitable, Callable, Protocol, TypeAlias
+from zoneinfo import ZoneInfo
+
+from datetype import DateTime
+from Foundation import (
+    NSTimeZone,
+    NSDateComponents,
+    NSError,
+    NSLog,
+    NSObject,
+    NSCalendar,
+    NSCalendarIdentifierGregorian,
+)
+from objc import object_property
+from twisted.internet.defer import Deferred
+from UserNotifications import (
+    UNAuthorizationOptionNone,
+    UNCalendarNotificationTrigger,
+    UNMutableNotificationContent,
+    UNNotification,
+    UNNotificationAction,
+    UNNotificationActionOptionAuthenticationRequired,
+    UNNotificationActionOptionDestructive,
+    UNNotificationActionOptionForeground,
+    UNNotificationActionOptions,
+    UNNotificationCategory,
+    UNNotificationCategoryOptionAllowInCarPlay,
+    UNNotificationCategoryOptionHiddenPreviewsShowSubtitle,
+    UNNotificationCategoryOptionHiddenPreviewsShowTitle,
+    UNNotificationCategoryOptions,
+    UNNotificationPresentationOptionBanner,
+    UNNotificationPresentationOptions,
+    UNNotificationRequest,
+    UNNotificationResponse,
+    UNNotificationSettings,
+    UNNotificationTrigger,
+    UNTextInputNotificationAction,
+    UNUserNotificationCenter,
+)
+
+
+def make[T: NSObject](cls: type[T], **attributes: object) -> T:
+    self: T = cls.alloc().init()
+    self.setValuesForKeysWithDictionary_(attributes)
+    return self
+
+
+@dataclass
+class _AppNotificationsCtxBuilder:
+    _center: UNUserNotificationCenter
+    _cfg: _NotifConfigImpl | None
+
+    async def __aenter__(self) -> _NotifConfigImpl:
+        """
+        Request authorization, then start building this notifications manager.
+        """
+        NSLog("beginning build")
+        grantDeferred: Deferred[bool] = Deferred()
+
+        def completed(granted: bool, error: NSError | None) -> None:
+            # TODO: convert non-None NSErrors into failures on this Deferred
+            grantDeferred.callback(granted)
+            NSLog(
+                "Notification authorization response: %@ with error: %@", granted, error
+            )
+
+        NSLog("requesting authorization")
+        self._center.requestAuthorizationWithOptions_completionHandler_(
+            UNAuthorizationOptionNone, completed
+        )
+        NSLog("requested")
+        granted = await grantDeferred
+        settingsDeferred: Deferred[UNNotificationSettings] = Deferred()
+
+        def gotSettings(settings: UNNotificationSettings) -> None:
+            NSLog("received notification settings %@", settings)
+            settingsDeferred.callback(settings)
+
+        NSLog("requesting notification settings")
+        self._center.getNotificationSettingsWithCompletionHandler_(gotSettings)
+        settings = await settingsDeferred
+        NSLog("initializing config")
+        self.cfg = _NotifConfigImpl(
+            self._center,
+            [],
+            _wasGrantedPermission=granted,
+            _settings=settings,
+        )
+        NSLog("done!")
+        return self.cfg
+
+    async def __aexit__(
+        self,
+        exc_type: type[BaseException] | None,
+        exc_value: BaseException | None,
+        traceback: TracebackType | None,
+        /,
+    ) -> bool:
+        """
+        Finalize the set of notification categories and actions in use for this application.
+        """
+        NSLog("async exit from ctx manager")
+        if traceback is None and self.cfg is not None:
+            qmandw = _QMANotificationDelegateWrapper.alloc().initWithConfig_(self.cfg)
+            qmandw.retain()
+            NSLog("Setting delegate! %@", qmandw)
+            self._center.setDelegate_(qmandw)
+            self.cfg._register()
+        else:
+            NSLog("NOT setting delegate!!!")
+        return False
+
+
+class _QMANotificationDelegateWrapper(NSObject):
+    """
+    UNUserNotificationCenterDelegate implementation.
+    """
+
+    config: _NotifConfigImpl = object_property()
+
+    def initWithConfig_(self, cfg: _NotifConfigImpl) -> _QMANotificationDelegateWrapper:
+        self.config = cfg
+        return self
+
+    def userNotificationCenter_willPresentNotification_withCompletionHandler_(
+        self,
+        notificationCenter: UNUserNotificationCenter,
+        notification: UNNotification,
+        completionHandler: Callable[[UNNotificationPresentationOptions], None],
+    ) -> None:
+        NSLog("willPresent: %@", notification)
+        # TODO: allow for client code to customize this; here we are saying
+        # "please present the notification to the user as a banner, even if we
+        # are in the foreground".  We should allow for customization on a
+        # category basis; rather than @response.something, maybe
+        # @present.something, as a method on the python category class?
+        completionHandler(UNNotificationPresentationOptionBanner)
+
+    def userNotificationCenter_didReceiveNotificationResponse_withCompletionHandler_(
+        self,
+        notificationCenter: UNUserNotificationCenter,
+        notificationResponse: UNNotificationResponse,
+        completionHandler: Callable[[], None],
+    ) -> None:
+        """
+        We received a response to a notification.
+        """
+        NSLog("received notification repsonse %@", notificationResponse)
+
+        # TODO: actually hook up the dispatch of the notification response to
+        # the registry of action callbacks already set up in
+        # NotificationConfig.
+        async def respond() -> None:
+            notifier = self.config._notifierByCategory(
+                notificationResponse.notification()
+                .request()
+                .content()
+                .categoryIdentifier()
+            )
+            await notifier._handleResponse(notificationResponse)
+            completionHandler()
+
+        Deferred.fromCoroutine(respond()).addErrback(
+            lambda error: NSLog("error: %@", error)
+        )
+
+
+class NotificationTranslator[T](Protocol):
+    """
+    Translate notifications from the notification ID and some user data,
+    """
+
+    def fromNotification(self, notificationID: str, userData: dict[str, Any]) -> T:
+        """
+        A user interacted with a notification with the given parameters;
+        deserialize them into a Python object that can process that action.
+        """
+
+    def toNotification(self, notification: T) -> tuple[str, dict[str, Any]]:
+        """
+        The application has requested to send a notification to the operating
+        system, serialize the Python object represneting this category of
+        notification into a 2-tuple of C{notificatcionID}, C{userData} that can
+        be encapsulated in a C{UNNotificationRequest}.
+        """
+
+
+@dataclass
+class Notifier[NotifT]:
+    """
+    A notifier for a specific category.
+    """
+
+    # Public interface:
+    def undeliver(self, notification: NotifT) -> None:
+        """
+        Remove the previously-delivered notification object from the
+        notification center, if it's still there.
+        """
+        notID, _ = self._tx.toNotification(notification)
+        self._cfg._center.removeDeliveredNotificationsWithIdentifiers_([notID])
+
+    def unsend(self, notification: NotifT) -> None:
+        """
+        Prevent the as-yet undelivered notification object from being
+        delivered.
+        """
+        notID, _ = self._tx.toNotification(notification)
+        self._cfg._center.removePendingNotificationRequestsWithIdentifiers_([notID])
+
+    async def notifyAt(
+        self, when: DateTime[ZoneInfo], notification: NotifT, title: str, body: str
+    ) -> None:
+
+        components: NSDateComponents = NSDateComponents.alloc().init()
+        components.setCalendar_(
+            NSCalendar.calendarWithIdentifier_(NSCalendarIdentifierGregorian)
+        )
+        components.setTimeZone_(NSTimeZone.timeZoneWithName_(when.tzinfo.key))
+        components.setYear_(when.year)
+        components.setMonth_(when.month)
+        components.setDay_(when.day)
+        components.setHour_(when.hour)
+        components.setMinute_(when.minute)
+        components.setSecond_(when.second)
+
+        repeats: bool = False
+        trigger: UNNotificationTrigger = (
+            UNCalendarNotificationTrigger.triggerWithDateMatchingComponents_repeats_(
+                components,
+                repeats,
+            )
+        )
+        await self._notifyWithTrigger(trigger, notification, title, body)
+
+    # Attributes:
+    _notificationCategoryID: str
+    _cfg: _NotifConfigImpl
+    _tx: NotificationTranslator[NotifT]
+    _actionInfos: list[_oneActionInfo]
+    _allowInCarPlay: bool
+    _hiddenPreviewsShowTitle: bool
+    _hiddenPreviewsShowSubtitle: bool
+
+    # Private implementation details:
+    async def _handleResponse(self, response: UNNotificationResponse) -> None:
+        userInfo = response.notification().request().content().userInfo()
+        actionID: str = response.actionIdentifier()
+        notificationID: str = response.notification().request().identifier()
+        cat = self._tx.fromNotification(notificationID, userInfo)
+        for cb, eachActionID, action, options in self._actionInfos:
+            if actionID == eachActionID:
+                break
+        else:
+            raise KeyError(actionID)
+        await cb(cat, response)
+
+    def _createUNNotificationCategory(self) -> UNNotificationCategory:
+        actions = []
+        # We don't yet support intent identifiers.
+        intentIdentifiers: list[str] = []
+        options = 0
+        for handler, actionID, toRegister, extraOptions in self._actionInfos:
+            options |= extraOptions
+            if toRegister is not None:
+                actions.append(toRegister)
+        NSLog("actions generated: %@ options: %@", actions, options)
+        if self._allowInCarPlay:
+            # Ha ha. Someday, maybe.
+            options |= UNNotificationCategoryOptionAllowInCarPlay
+        if self._hiddenPreviewsShowTitle:
+            options |= UNNotificationCategoryOptionHiddenPreviewsShowTitle
+        if self._hiddenPreviewsShowSubtitle:
+            options |= UNNotificationCategoryOptionHiddenPreviewsShowSubtitle
+        return UNNotificationCategory.categoryWithIdentifier_actions_intentIdentifiers_options_(
+            self._notificationCategoryID, actions, intentIdentifiers, options
+        )
+
+    async def _notifyWithTrigger(
+        self,
+        trigger: UNNotificationTrigger,
+        notification: NotifT,
+        title: str,
+        body: str,
+    ) -> None:
+        notificationID, userInfo = self._tx.toNotification(notification)
+        request = UNNotificationRequest.requestWithIdentifier_content_trigger_(
+            notificationID,
+            make(
+                UNMutableNotificationContent,
+                title=title,
+                body=body,
+                categoryIdentifier=self._notificationCategoryID,
+                userInfo=userInfo,
+            ),
+            trigger,
+        )
+        d: Deferred[NSError | None] = Deferred()
+        self._cfg._center.addNotificationRequest_withCompletionHandler_(
+            request, d.callback
+        )
+        error = await d
+        NSLog("completed notification request with error %@", error)
+
+
+@dataclass
+class _NotifConfigImpl:
+    _center: UNUserNotificationCenter
+    _notifiers: list[Notifier[Any]]
+    _wasGrantedPermission: bool
+    _settings: UNNotificationSettings
+
+    def add[NotifT](
+        self,
+        category: type[NotifT],
+        translator: NotificationTranslator[NotifT],
+        allowInCarPlay: bool = False,
+        hiddenPreviewsShowTitle: bool = False,
+        hiddenPreviewsShowSubtitle: bool = False,
+        # customDismissAction: bool = False,
+    ) -> Notifier[NotifT]:
+        """
+        @param category: the category to add
+
+        @param translator: a translator that can load and save a translator.
+        """
+        catid: str = f"{category.__module__}.{category.__qualname__}"
+        notifier = Notifier(
+            catid,
+            self,
+            translator,
+            _getAllActionInfos(category),
+            _allowInCarPlay=allowInCarPlay,
+            _hiddenPreviewsShowTitle=hiddenPreviewsShowTitle,
+            _hiddenPreviewsShowSubtitle=hiddenPreviewsShowSubtitle,
+        )
+        self._notifiers.append(notifier)
+        return notifier
+
+    def _notifierByCategory(self, categoryID: str) -> Notifier[Any]:
+        for notifier in self._notifiers:
+            if categoryID == notifier._notificationCategoryID:
+                return notifier
+        raise KeyError(categoryID)
+
+    def _register(self) -> None:
+        self._center.setNotificationCategories_(
+            [pynot._createUNNotificationCategory() for pynot in self._notifiers]
+        )
+
+
+_ACTION_INFO_ATTR = "__qma_notification_action_info__"
+
+
+_oneActionInfo = tuple[
+    # Action handler to stuff away into dispatch; does the pulling out of
+    # userText if necessary
+    Callable[[Any, UNNotificationResponse], Awaitable[None]],
+    # action ID
+    str,
+    # the notification action to register; None for default & dismiss
+    UNNotificationAction | None,
+    UNNotificationCategoryOptions,
+]
+
+
+_anyActionInfo: TypeAlias = (
+    "_PlainNotificationActionInfo | _TextNotificationActionInfo | _BuiltinActionInfo"
+)
+
+
+def _getActionInfo(o: object) -> _oneActionInfo | None:
+    handler: _anyActionInfo | None = getattr(o, _ACTION_INFO_ATTR, None)
+    if handler is None:
+        return None
+    appCallback: Any = o
+    actionID = handler.identifier
+    callback = handler._makeCallback(appCallback)
+    extraOptions = handler._extraOptions
+    return (callback, actionID, handler._toAction(), extraOptions)
+
+
+def _setActionInfo[T](wrapt: T, actionInfo: _anyActionInfo) -> T:
+    setattr(wrapt, _ACTION_INFO_ATTR, actionInfo)
+    return wrapt
+
+
+def _getAllActionInfos(t: type[object]) -> list[_oneActionInfo]:
+    result = []
+    for attr in dir(t):
+        actionInfo = _getActionInfo(getattr(t, attr, None))
+        if actionInfo is not None:
+            result.append(actionInfo)
+    return result
+
+
+def _py2options(
+    foreground: bool,
+    destructive: bool,
+    authenticationRequired: bool,
+) -> UNNotificationActionOptions:
+    """
+    Convert some sensibly-named data types into UNNotificationActionOptions.
+    """
+    options = 0
+    if foreground:
+        options |= UNNotificationActionOptionForeground
+    if destructive:
+        options |= UNNotificationActionOptionDestructive
+    if authenticationRequired:
+        options |= UNNotificationActionOptionAuthenticationRequired
+    return options
+
+
+@dataclass
+class _PlainNotificationActionInfo:
+    identifier: str
+    title: str
+    foreground: bool
+    destructive: bool
+    authenticationRequired: bool
+    _extraOptions: UNNotificationCategoryOptions = 0
+
+    def _makeCallback[T](
+        self, appCallback: Callable[[T], Awaitable[None]]
+    ) -> Callable[[Any, UNNotificationResponse], Awaitable[None]]:
+        async def takesNotification(self: T, response: UNNotificationResponse) -> None:
+            await appCallback(self)
+            return None
+
+        return takesNotification
+
+    def _toAction(self) -> UNNotificationAction:
+        return UNNotificationAction.actionWithIdentifier_title_options_(
+            self.identifier,
+            self.title,
+            _py2options(
+                self.foreground,
+                self.destructive,
+                self.authenticationRequired,
+            ),
+        )
+
+
+@dataclass
+class _TextNotificationActionInfo:
+    identifier: str
+    title: str
+    foreground: bool
+    destructive: bool
+    authenticationRequired: bool
+    buttonTitle: str
+    textPlaceholder: str
+    _extraOptions: UNNotificationCategoryOptions = 0
+
+    def _makeCallback[T](
+        self, appCallback: Callable[[T, str], Awaitable[None]]
+    ) -> Callable[[Any, UNNotificationResponse], Awaitable[None]]:
+        async def takesNotification(self: T, response: UNNotificationResponse) -> None:
+            await appCallback(self, response.userText())
+            return None
+
+        return takesNotification
+
+    def _toAction(self) -> UNNotificationAction:
+        return UNTextInputNotificationAction.actionWithIdentifier_title_options_textInputButtonTitle_textInputPlaceholder_(
+            self.identifier,
+            self.title,
+            _py2options(
+                self.foreground,
+                self.destructive,
+                self.authenticationRequired,
+            ),
+            self.buttonTitle,
+            self.textPlaceholder,
+        )
+
+
+@dataclass
+class _BuiltinActionInfo:
+    identifier: str
+    _extraOptions: UNNotificationCategoryOptions
+
+    def _toAction(self) -> None:
+        return None
+
+    def _makeCallback[T](
+        self, appCallback: Callable[[T], Awaitable[None]]
+    ) -> Callable[[Any, UNNotificationResponse], Awaitable[None]]:
+        async def takesNotification(self: T, response: UNNotificationResponse) -> None:
+            await appCallback(self)
+            return None
+
+        return takesNotification

quickmacapp/_quickapp.py

@@ -177,7 +177,7 @@ class QuickApplication(NSApplication):
     """
     QuickMacApp's main application class.
 
-    @ivar keyEquivalentHandler: Set this attribute to a custom L{NSResponder}
+    @ivar keyEquivalentHandler: Set this attribute to a custom C{NSResponder}
         if you want to handle key equivalents outside the responder chain.  (I
         believe this is necessary in some apps because the responder chain can
         be more complicated in LSUIElement apps, but there might be a better

quickmacapp/notifications.py

@@ -0,0 +1,276 @@
+"""
+API for emitting macOS notifications.
+
+@see: L{configureNotifications}.
+"""
+
+from contextlib import AbstractAsyncContextManager as _AbstractAsyncContextManager
+from dataclasses import dataclass as _dataclass
+from typing import Callable, Protocol
+from zoneinfo import ZoneInfo
+
+from datetype import DateTime
+from UserNotifications import (
+    UNNotificationCategoryOptionCustomDismissAction as _UNNotificationCategoryOptionCustomDismissAction,
+    UNNotificationDefaultActionIdentifier as _UNNotificationDefaultActionIdentifier,
+    UNNotificationDismissActionIdentifier as _UNNotificationDismissActionIdentifier,
+)
+from UserNotifications import UNUserNotificationCenter as _UNUserNotificationCenter
+
+from quickmacapp._notifications import (
+    NotificationTranslator,
+    _AppNotificationsCtxBuilder,
+    _BuiltinActionInfo,
+    _PlainNotificationActionInfo,
+    _setActionInfo,
+    _TextNotificationActionInfo,
+)
+
+__all__ = [
+    "NotificationTranslator",
+    "Action",
+    "TextAction",
+    "response",
+    "Notifier",
+    "NotificationConfig",
+]
+
+
+class Action[NotificationT](Protocol):
+    """
+    An action is just an async method that takes its C{self} (an instance of a
+    notification class encapsulating the ID & data), and reacts to the
+    specified action.
+    """
+
+    async def __call__(__no_self__, /, self: NotificationT) -> None:
+        """
+        React to the action.
+        """
+
+
+class TextAction[NotificationT](Protocol):
+    """
+    A L{TextAction} is just like an L{Action}, but it takes some text.
+    """
+
+    async def __call__(__no_self__, /, self: NotificationT, text: str) -> None:
+        """
+        React to the action with the user's input.
+        """
+
+
+@_dataclass
+class response:
+    identifier: str
+    title: str
+    foreground: bool = False
+    destructive: bool = False
+    authenticationRequired: bool = False
+
+    def __call__[NT](self, action: Action[NT], /) -> Action[NT]:
+        return _setActionInfo(
+            action,
+            _PlainNotificationActionInfo(
+                identifier=self.identifier,
+                title=self.title,
+                foreground=self.foreground,
+                destructive=self.destructive,
+                authenticationRequired=self.authenticationRequired,
+            ),
+        )
+
+    def text[NT](
+        self, *, title: str | None = None, placeholder: str = ""
+    ) -> Callable[[TextAction[NT]], TextAction[NT]]:
+        return lambda wrapt: _setActionInfo(
+            wrapt,
+            _TextNotificationActionInfo(
+                identifier=self.identifier,
+                title=self.title,
+                buttonTitle=title if title is not None else self.title,
+                textPlaceholder=placeholder,
+                foreground=self.foreground,
+                destructive=self.destructive,
+                authenticationRequired=self.authenticationRequired,
+            ),
+        )
+
+    @staticmethod
+    def default[NT]() -> Callable[[Action[NT]], Action[NT]]:
+        return lambda wrapt: _setActionInfo(
+            wrapt, _BuiltinActionInfo(_UNNotificationDefaultActionIdentifier, 0)
+        )
+
+    @staticmethod
+    def dismiss[NT]() -> Callable[[Action[NT]], Action[NT]]:
+        return lambda wrapt: _setActionInfo(
+            wrapt,
+            _BuiltinActionInfo(
+                _UNNotificationDismissActionIdentifier,
+                _UNNotificationCategoryOptionCustomDismissAction,
+            ),
+        )
+
+
+class Notifier[NotifT](Protocol):
+    """
+    A L{Notifier} can deliver notifications.
+    """
+
+    async def notifyAt(
+        self, when: DateTime[ZoneInfo], notification: NotifT, title: str, body: str
+    ) -> None:
+        """
+        Request a future notification at the given time.
+        """
+
+    def undeliver(self, notification: NotifT) -> None:
+        """
+        Remove the previously-delivered notification object from the
+        notification center, if it's still there.
+        """
+
+    def unsend(self, notification: NotifT) -> None:
+        """
+        Prevent the as-yet undelivered notification object from being
+        delivered.
+        """
+
+
+class NotificationConfig(Protocol):
+    """
+    The application-wide configuration for a notification.
+    """
+
+    def add[NotifT](
+        self,
+        category: type[NotifT],
+        translator: NotificationTranslator[NotifT],
+        allowInCarPlay: bool = False,
+        hiddenPreviewsShowTitle: bool = False,
+        hiddenPreviewsShowSubtitle: bool = False,
+    ) -> Notifier[NotifT]:
+        """
+        Add a new category (represented by a plain Python class, which may have
+        some methods that were decorated with L{response}C{(...)},
+        L{response.text}C{(...)}).
+
+        @param category: A Python type that contains the internal state for the
+            notifications that will be emitted, that will be relayed back to
+            its responses (e.g. the response methods on the category).
+
+        @param translator: a translator that can serialize and deserialize
+            python objects to C{UNUserNotificationCenter} values.
+
+        @param allowInCarPlay: Should the notification be allowed to show in
+            CarPlay?
+
+        @param hiddenPreviewsShowTitle: Should lock-screen previews for this
+            notification show the unredacted title?
+
+        @param hiddenPreviewsShowSubtitle: Should lock-screen previews for this
+            notification show the unredacted subtitle?
+
+        @return: A L{Notifier} that can deliver notifications to macOS.
+
+        @note: This method can I{only} be called within the C{with} statement
+            for the context manager beneath C{configureNotifications}, and can
+            only do this once per process.  Otherwise it will raise an
+            exception.
+        """
+
+
+def configureNotifications() -> _AbstractAsyncContextManager[NotificationConfig]:
+    """
+    Configure notifications for the current application.
+
+    This is an asynchronous (using Twisted's Deferred) context manager, run
+    with `with` statement, which works like this::
+
+        async with configureNotifications() as cfg:
+            notifier = cfg.add(MyNotificationData, MyNotificationLoader())
+
+    Each L{add <NotificationConfig.add>} invocation adds a category of
+    notifications you can send, and returns an object (a L{Notifier}) that can
+    send that category of notification.
+
+    At the end of the C{async with} block, the notification configuration is
+    finalized, its state is sent to macOS, and the categories of notification
+    your application can send is frozen for the rest of the lifetime of your
+    process; the L{Notifier} objects returned from L{add
+    <NotificationConfig.add>} are now active nad can be used.  Note that you
+    may only call L{configureNotifications} once in your entire process, so you
+    will need to pass those notifiers elsewhere!
+
+    Each call to add requires 2 arguments: a notification-data class which
+    stores the sent notification's ID and any other ancillary data transmitted
+    along with it, and an object that can load and store that first class, when
+    notification responses from the operating system convey data that was
+    previously scheduled as a notification.  In our example above, they can be
+    as simple as this::
+
+        class MyNotificationData:
+            id: str
+
+        class MyNotificationLoader:
+            def fromNotification(
+                self, notificationID: str, userData: dict[str, object]
+            ) -> MyNotificationData:
+                return MyNotificationData(notificationID)
+            def toNotification(
+                self,
+                notification: MyNotificationData,
+            ) -> tuple[str, dict[str, object]]:
+                return (notification.id, {})
+
+    Then, when you want to I{send} a notification, you can do::
+
+        await notifier.notifyAt(
+            aware(datetime.now(TZ) + timedelta(seconds=5), TZ),
+            MyNotificationData("my.notification.id.1"),
+            "Title Here",
+            "Subtitle Here",
+        )
+
+    And that will show the user a notification.
+
+    The C{MyNotificationData} class might seem simplistic to the point of
+    uselessness, and in this oversimplified case, it is!  However, if you are
+    sending notifications to a user, you really need to be able to I{respond}
+    to notifications from a user, and that's where your notification data class
+    as well as L{response} comes in.  To respond to a notification when the
+    user clicks on it, you can add a method like so::
+
+        class MyNotificationData:
+            id: str
+
+            @response(identifier="response-action-1", title="Action 1")
+            async def responseAction1(self) -> None:
+                await answer("User pressed 'Action 1' button")
+
+            @response.default()
+            async def userClicked(self) -> None:
+                await answer("User clicked the notification.")
+
+    When sent with L{Notifier.notifyAt}, your C{MyNotificationData} class will
+    be serialized and deserialized with C{MyNotificationLoader.toNotification}
+    (converting your Python class into a macOS notification, to send along to
+    the OS) and C{MyNotificationLoader.fromNotification} (converting the data
+    sent along with the user's response back into a C{MyNotificationData}).
+
+    @note: If your app schedules a notification, then quits, when the user
+        responds (clicks on it, uses a button, dismisses it, etc) then the OS
+        will re-launch your application and send the notification data back in,
+        which is why all the serialization and deserialization is required.
+        Your process may have exited and thus the original notification will no
+        longer be around.  However, if you are just running as a Python script,
+        piggybacking on the 'Python Launcher' app bundle, macOS will not be
+        able to re-launch your app.  Notifications going back to the same
+        process seem to work okay, but note that as documented, macOS really
+        requires your application to have its own bundle and its own unique
+        CFBundleIdentifier in order to avoid any weird behavior.
+    """
+    return _AppNotificationsCtxBuilder(
+        _UNUserNotificationCenter.currentNotificationCenter(), None
+    )

{quickmacapp-2025.3.18.dist-info → quickmacapp-2025.4.15.dist-info}/METADATA

@@ -1,13 +1,15 @@
-Metadata-Version: 2.2
+Metadata-Version: 2.4
 Name: quickmacapp
-Version: 2025.3.18
+Version: 2025.4.15
 Summary: Make it easier to write Mac apps in Python
 Description-Content-Type: text/x-rst
 License-File: LICENSE
 Requires-Dist: pyobjc-framework-Cocoa
 Requires-Dist: pyobjc-framework-ExceptionHandling
 Requires-Dist: pyobjc-framework-UserNotifications
+Requires-Dist: datetype
 Requires-Dist: twisted[macos_platform,tls]
+Dynamic: license-file
 
 QuickMacApp
 ==============================

quickmacapp-2025.4.15.dist-info/RECORD

@@ -0,0 +1,12 @@
+quickmacapp/__init__.py,sha256=NsZW_cPvJTunDShN3RjOyK1gTwTKsghMb7wb6vRgTXI,335
+quickmacapp/_background.py,sha256=M_ob3EF8v-Z_gpKuFDl2N9XrQz0eBLFfUp2XErDB3DU,5943
+quickmacapp/_interactions.py,sha256=eLv_mVf5Jr-puNizlR8tDL_DlLy1Rc82XQ80o0GP5R4,3439
+quickmacapp/_notifications.py,sha256=DNm4-vOF0wQNUUTBHqp3-RKXVQK98ef53isxwsWqyj8,16965
+quickmacapp/_quickapp.py,sha256=Ed5n9rAw12nlHxyBMzyPc1Vt4K2OVIqCszWPqQyVElk,7571
+quickmacapp/notifications.py,sha256=UCigVIurf-zWAqVXUYjTtz_xMjcoI23dqyJ4OzZurQM,10275
+quickmacapp/py.typed,sha256=47DEQpj8HBSa-_TImW-5JCeuQeRkm5NMpJWZG3hSuFU,0
+quickmacapp-2025.4.15.dist-info/licenses/LICENSE,sha256=7RIBNNvrnKHR3lw9z3KXv3Q6RRjhyxtNQoMnoUsf3_M,1091
+quickmacapp-2025.4.15.dist-info/METADATA,sha256=KV6153Iy7rHC5Xrgs8RVtTtBauSRG9GNKzOk3btM-Rg,1344
+quickmacapp-2025.4.15.dist-info/WHEEL,sha256=CmyFI0kx5cdEMTLiONQRbGQwjIoR1aIYB7eCAQ4KPJ0,91
+quickmacapp-2025.4.15.dist-info/top_level.txt,sha256=_iJkekUYnuWhCZbFSQyo2d5_6B7OoPwx7k527bokzeA,12
+quickmacapp-2025.4.15.dist-info/RECORD,,

{quickmacapp-2025.3.18.dist-info → quickmacapp-2025.4.15.dist-info}/WHEEL

@@ -1,5 +1,5 @@
 Wheel-Version: 1.0
-Generator: setuptools (76.1.0)
+Generator: setuptools (78.1.0)
 Root-Is-Purelib: true
 Tag: py3-none-any
 

quickmacapp-2025.3.18.dist-info/RECORD

@@ -1,10 +0,0 @@
-quickmacapp/__init__.py,sha256=NsZW_cPvJTunDShN3RjOyK1gTwTKsghMb7wb6vRgTXI,335
-quickmacapp/_background.py,sha256=M_ob3EF8v-Z_gpKuFDl2N9XrQz0eBLFfUp2XErDB3DU,5943
-quickmacapp/_interactions.py,sha256=eLv_mVf5Jr-puNizlR8tDL_DlLy1Rc82XQ80o0GP5R4,3439
-quickmacapp/_quickapp.py,sha256=UdZQKIJG40OSzzJ4bdMWix7bpgyZnDAGftF-ksk1VDw,7571
-quickmacapp/py.typed,sha256=47DEQpj8HBSa-_TImW-5JCeuQeRkm5NMpJWZG3hSuFU,0
-quickmacapp-2025.3.18.dist-info/LICENSE,sha256=7RIBNNvrnKHR3lw9z3KXv3Q6RRjhyxtNQoMnoUsf3_M,1091
-quickmacapp-2025.3.18.dist-info/METADATA,sha256=7db1LqTDV1pWVXzIEjjubLE7t4_XU4nW4mTxMhMklxo,1298
-quickmacapp-2025.3.18.dist-info/WHEEL,sha256=beeZ86-EfXScwlR_HKu4SllMC9wUEj_8Z_4FJ3egI2w,91
-quickmacapp-2025.3.18.dist-info/top_level.txt,sha256=_iJkekUYnuWhCZbFSQyo2d5_6B7OoPwx7k527bokzeA,12
-quickmacapp-2025.3.18.dist-info/RECORD,,