quickmacapp 2025.3.16__tar.gz → 2025.4.4__tar.gz

{quickmacapp-2025.3.16 → quickmacapp-2025.4.4}/PKG-INFO

@@ -1,13 +1,15 @@
-Metadata-Version: 2.2
+Metadata-Version: 2.4
 Name: quickmacapp
-Version: 2025.3.16
+Version: 2025.4.4
 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.3.16 → quickmacapp-2025.4.4}/pyproject.toml

@@ -9,10 +9,11 @@ build-backend = "setuptools.build_meta"
 name = "quickmacapp"
 description = "Make it easier to write Mac apps in Python"
 readme = "README.rst"
-version = "2025.03.16"
+version = "2025.04.04"
 dependencies = [
     "pyobjc-framework-Cocoa",
     "pyobjc-framework-ExceptionHandling",
     "pyobjc-framework-UserNotifications",
+    "datetype",
     "twisted[tls,macos_platform]",
 ]

{quickmacapp-2025.3.16 → quickmacapp-2025.4.4}/src/quickmacapp/__init__.py

@@ -1,5 +1,6 @@
 from ._quickapp import Actionable, Status, mainpoint, menu, quit
 from ._interactions import ask, choose, answer, getpass
+from ._background import dockIconWhenVisible
 
 __all__ = [
     "Actionable",
@@ -11,4 +12,5 @@ __all__ = [
     "choose",
     "answer",
     "getpass",
+    "dockIconWhenVisible",
 ]

quickmacapp-2025.4.4/src/quickmacapp/_background.py

@@ -0,0 +1,155 @@
+from typing import Any, Callable
+
+from dataclasses import dataclass, field
+
+from AppKit import (
+    NSApplication,
+    NSApplicationActivateIgnoringOtherApps,
+    NSApplicationActivationPolicyAccessory,
+    NSApplicationActivationPolicyRegular,
+    NSLog,
+    NSNotification,
+    NSNotificationCenter,
+    NSRunningApplication,
+    NSWindow,
+    NSWindowWillCloseNotification,
+    NSWorkspace,
+    NSWorkspaceActiveSpaceDidChangeNotification,
+    NSWorkspaceApplicationKey,
+    NSWorkspaceDidActivateApplicationNotification,
+    NSWorkspaceDidHideApplicationNotification,
+)
+
+
+@dataclass
+class SometimesBackground:
+    """
+    An application that is sometimes in the background but has a window that,
+    when visible, can own the menubar, become key, etc.  However, when that
+    window is closed, we withdraw to the menu bar and continue running in the
+    background, as an accessory.
+    """
+
+    mainWindow: NSWindow
+    hideIconOnOtherSpaces: bool
+    onSpaceChange: Callable[[], None]
+    currentlyRegular: bool = False
+    previouslyActiveApp: NSRunningApplication = field(init=False)
+
+    def someApplicationActivated_(self, notification: Any) -> None:
+        # NSLog(f"active {notification} {__file__}")
+        whichApp = notification.userInfo()[NSWorkspaceApplicationKey]
+
+        if whichApp == NSRunningApplication.currentApplication():
+            if self.currentlyRegular:
+                # NSLog("show editor window")
+                self.mainWindow.setIsVisible_(True)
+            else:
+                # NSLog("reactivate workaround")
+                self.currentlyRegular = True
+                self.previouslyActiveApp.activateWithOptions_(
+                    NSApplicationActivateIgnoringOtherApps
+                )
+                app = NSApplication.sharedApplication()
+                app.setActivationPolicy_(NSApplicationActivationPolicyRegular)
+                self.mainWindow.setIsVisible_(True)
+                from twisted.internet import reactor
+
+                reactor.callLater(  # type:ignore[attr-defined]
+                    0.1, lambda: app.activateIgnoringOtherApps_(True)
+                )
+        else:
+            self.previouslyActiveApp = whichApp
+
+    def someApplicationHidden_(self, notification: Any) -> None:
+        """
+        An app was hidden.
+        """
+        whichApp = notification.userInfo()[NSWorkspaceApplicationKey]
+        if whichApp == NSRunningApplication.currentApplication():
+            # 'hide others' (and similar functionality) should *not* hide the
+            # progress window; that would obviate the whole point of having
+            # this app live in the background in order to maintain a constant
+            # presence in the user's visual field.  however if we're being told
+            # to hide, don't ignore the user, hide the main window and retreat
+            # into the background as if we were closed.
+            self.mainWindow.close()
+            app = NSApplication.sharedApplication()
+            app.unhide_(self)
+
+    def someSpaceActivated_(self, notification: NSNotification) -> None:
+        """
+        Sometimes, fullscreen application stop getting the HUD overlay.
+        """
+        menuBarOwner = NSWorkspace.sharedWorkspace().menuBarOwningApplication()
+        # me = NSRunningApplication.currentApplication()
+        NSLog("space activated where allegedly %@ owns the menu bar", menuBarOwner)
+        if not self.mainWindow.isOnActiveSpace():
+            if self.hideIconOnOtherSpaces:
+                NSLog("I am not on the active space, closing the window")
+                self.mainWindow.close()
+            else:
+                NSLog("I am not on the active space, but that's OK, leaving window open.")
+        else:
+            NSLog("I am on the active space; not closing.")
+        self.onSpaceChange()
+
+    def someWindowWillClose_(self, notification: NSNotification) -> None:
+        """
+        The main window that we're observing will close.
+        """
+        if notification.object() == self.mainWindow:
+            self.currentlyRegular = False
+            NSApplication.sharedApplication().setActivationPolicy_(
+                NSApplicationActivationPolicyAccessory
+            )
+
+    def startObserving(self) -> None:
+        """
+        Attach the various callbacks.
+        """
+        NSNotificationCenter.defaultCenter().addObserver_selector_name_object_(
+            self, "someWindowWillClose:", NSWindowWillCloseNotification, None
+        )
+        wsnc = NSWorkspace.sharedWorkspace().notificationCenter()
+
+        self.previouslyActiveApp = (
+            NSWorkspace.sharedWorkspace().menuBarOwningApplication()
+        )
+
+        wsnc.addObserver_selector_name_object_(
+            self,
+            "someApplicationActivated:",
+            NSWorkspaceDidActivateApplicationNotification,
+            None,
+        )
+
+        wsnc.addObserver_selector_name_object_(
+            self,
+            "someApplicationHidden:",
+            NSWorkspaceDidHideApplicationNotification,
+            None,
+        )
+
+        wsnc.addObserver_selector_name_object_(
+            self,
+            "someSpaceActivated:",
+            NSWorkspaceActiveSpaceDidChangeNotification,
+            None,
+        )
+
+
+def dockIconWhenVisible(
+    mainWindow: NSWindow,
+    hideIconOnOtherSpaces: bool = True,
+    onSpaceChange: Callable[[], None] = lambda: None,
+):
+    """
+    When the given main window is visible, we should have a dock icon (i.e.: be
+    NSApplicationActivationPolicyRegular).  When our application is activated,
+    (i.e.: the user launches it from Spotlight, Finder, or similar) we should
+    make the window visible so that the dock icon appears.  When that window is
+    then closed, or when our application is hidden, we should hide our dock
+    icon (i.e.: be NSApplicationActivationPolicyAccessory).
+    """
+    SometimesBackground(mainWindow, hideIconOnOtherSpaces, onSpaceChange).startObserving()

quickmacapp-2025.4.4/src/quickmacapp/_notifications.py

@@ -0,0 +1,479 @@
+from __future__ import annotations
+
+from dataclasses import dataclass
+from zoneinfo import ZoneInfo
+from types import TracebackType
+from typing import Any, Awaitable, Callable, Protocol, TypeAlias
+
+from datetype import DateTime
+
+from Foundation import NSError, NSLog, NSObject, NSDateComponents
+from objc import object_property
+from twisted.internet.defer import Deferred
+from UserNotifications import (
+    UNNotificationCategoryOptions,
+    UNAuthorizationOptionNone,
+    UNMutableNotificationContent,
+    UNNotification,
+    UNNotificationAction,
+    UNNotificationActionOptions,
+    UNNotificationActionOptionAuthenticationRequired,
+    UNNotificationActionOptionDestructive,
+    UNNotificationActionOptionForeground,
+    UNNotificationCategory,
+    UNNotificationCategoryOptionAllowInCarPlay,
+    UNNotificationCategoryOptionHiddenPreviewsShowSubtitle,
+    UNNotificationCategoryOptionHiddenPreviewsShowTitle,
+    UNNotificationPresentationOptionBanner,
+    UNNotificationPresentationOptions,
+    UNNotificationRequest,
+    UNNotificationResponse,
+    UNNotificationSettings,
+    UNNotificationTrigger,
+    UNCalendarNotificationTrigger,
+    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 L{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()
+        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-2025.4.4/src/quickmacapp/notifications.py

@@ -0,0 +1,245 @@
+"""
+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,
+    UNUserNotificationCenter as _UNUserNotificationCenter,
+    UNNotificationDefaultActionIdentifier as _UNNotificationDefaultActionIdentifier,
+    UNNotificationDismissActionIdentifier as _UNNotificationDismissActionIdentifier,
+)
+
+from quickmacapp._notifications import (
+    NotificationTranslator,
+    _BuiltinActionInfo,
+    _PlainNotificationActionInfo,
+    _setActionInfo,
+    _TextNotificationActionInfo,
+    _AppNotificationsCtxBuilder,
+)
+
+__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):
+
+    def add[NotifT](
+        self,
+        category: type[NotifT],
+        translator: NotificationTranslator[NotifT],
+        allowInCarPlay: bool = False,
+        hiddenPreviewsShowTitle: bool = False,
+        hiddenPreviewsShowSubtitle: bool = False,
+    ) -> Notifier[NotifT]: ...
+
+
+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{responder} 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 L{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.16 → quickmacapp-2025.4.4}/src/quickmacapp.egg-info/PKG-INFO

@@ -1,13 +1,15 @@
-Metadata-Version: 2.2
+Metadata-Version: 2.4
 Name: quickmacapp
-Version: 2025.3.16
+Version: 2025.4.4
 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.3.16 → quickmacapp-2025.4.4}/src/quickmacapp.egg-info/SOURCES.txt

@@ -2,8 +2,11 @@ LICENSE
 README.rst
 pyproject.toml
 src/quickmacapp/__init__.py
+src/quickmacapp/_background.py
 src/quickmacapp/_interactions.py
+src/quickmacapp/_notifications.py
 src/quickmacapp/_quickapp.py
+src/quickmacapp/notifications.py
 src/quickmacapp/py.typed
 src/quickmacapp.egg-info/PKG-INFO
 src/quickmacapp.egg-info/SOURCES.txt

{quickmacapp-2025.3.16 → quickmacapp-2025.4.4}/src/quickmacapp.egg-info/requires.txt

@@ -1,4 +1,5 @@
 pyobjc-framework-Cocoa
 pyobjc-framework-ExceptionHandling
 pyobjc-framework-UserNotifications
+datetype
 twisted[macos_platform,tls]