quickmacapp 2025.4.4__tar.gz → 2025.6.24__tar.gz

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

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: quickmacapp
-Version: 2025.4.4
+Version: 2025.6.24
 Summary: Make it easier to write Mac apps in Python
 Description-Content-Type: text/x-rst
 License-File: LICENSE

{quickmacapp-2025.4.4 → quickmacapp-2025.6.24}/pyproject.toml

@@ -9,7 +9,7 @@ build-backend = "setuptools.build_meta"
 name = "quickmacapp"
 description = "Make it easier to write Mac apps in Python"
 readme = "README.rst"
-version = "2025.04.04"
+version = "2025.06.24"
 dependencies = [
     "pyobjc-framework-Cocoa",
     "pyobjc-framework-ExceptionHandling",

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

@@ -1,9 +1,10 @@
-from ._quickapp import Actionable, Status, mainpoint, menu, quit
+from ._quickapp import Actionable, ItemState, Status, mainpoint, menu, quit
 from ._interactions import ask, choose, answer, getpass
 from ._background import dockIconWhenVisible
 
 __all__ = [
     "Actionable",
+    "ItemState",
     "Status",
     "mainpoint",
     "menu",

{quickmacapp-2025.4.4 → quickmacapp-2025.6.24}/src/quickmacapp/_notifications.py

@@ -1,36 +1,43 @@
 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 zoneinfo import ZoneInfo
 
 from datetype import DateTime
-
-from Foundation import NSError, NSLog, NSObject, NSDateComponents
+from Foundation import (
+    NSTimeZone,
+    NSDateComponents,
+    NSError,
+    NSLog,
+    NSObject,
+    NSCalendar,
+    NSCalendarIdentifierGregorian,
+)
 from objc import object_property
 from twisted.internet.defer import Deferred
 from UserNotifications import (
-    UNNotificationCategoryOptions,
     UNAuthorizationOptionNone,
+    UNCalendarNotificationTrigger,
     UNMutableNotificationContent,
     UNNotification,
     UNNotificationAction,
-    UNNotificationActionOptions,
     UNNotificationActionOptionAuthenticationRequired,
     UNNotificationActionOptionDestructive,
     UNNotificationActionOptionForeground,
+    UNNotificationActionOptions,
     UNNotificationCategory,
     UNNotificationCategoryOptionAllowInCarPlay,
     UNNotificationCategoryOptionHiddenPreviewsShowSubtitle,
     UNNotificationCategoryOptionHiddenPreviewsShowTitle,
+    UNNotificationCategoryOptions,
     UNNotificationPresentationOptionBanner,
     UNNotificationPresentationOptions,
     UNNotificationRequest,
     UNNotificationResponse,
     UNNotificationSettings,
     UNNotificationTrigger,
-    UNCalendarNotificationTrigger,
     UNTextInputNotificationAction,
     UNUserNotificationCenter,
 )
@@ -178,7 +185,7 @@ class NotificationTranslator[T](Protocol):
         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}.
+        be encapsulated in a C{UNNotificationRequest}.
         """
 
 
@@ -208,7 +215,19 @@ class Notifier[NotifT]:
     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_(

{quickmacapp-2025.4.4 → quickmacapp-2025.6.24}/src/quickmacapp/_quickapp.py

@@ -3,31 +3,48 @@ from __future__ import annotations
 import os
 import sys
 import traceback
-from typing import Callable, Protocol, Any
-
-from objc import ivar, IBAction, super
-
-from Foundation import (
-    NSObject,
-    NSException,
-)
+from dataclasses import dataclass
+from types import FunctionType
+from typing import Any, Callable, Iterable, Protocol, Sequence, Literal
 
 from AppKit import (
     NSApp,
     NSApplication,
     NSEvent,
-    NSResponder,
-    NSMenu,
     NSImage,
+    NSMenu,
     NSMenuItem,
+    NSResponder,
     NSStatusBar,
     NSVariableStatusItemLength,
+    NSControlStateValueOn,
+    NSControlStateValueOff,
 )
-
+from ExceptionHandling import NSStackTraceKey  # type:ignore
+from Foundation import NSException, NSObject
+from objc import IBAction, ivar, super
 from PyObjCTools.Debugging import _run_atos, isPythonException
-from ExceptionHandling import (  # type:ignore
-    NSStackTraceKey,
-)
+
+
+def asSelectorString(f: FunctionType) -> str:
+    """
+    Convert a method on a PyObjC class into a selector string.
+    """
+    return f.__name__.replace("_", ":")
+
+
+@dataclass(kw_only=True)
+class ItemState:
+    """
+    The state of a menu item.
+    """
+
+    enabled: bool = True
+    "Should the menu item be disabled? True if not, False if so."
+    checked: bool = False
+    "Should the menu item display a check-mark next to itself? True if so, False if not."
+    key: str | None = None
+    "Should the menu shortcut mnemonic key be set, blank, or derived from the item's title?"
 
 
 class Actionable(NSObject):
@@ -35,15 +52,20 @@ class Actionable(NSObject):
     Wrap a Python no-argument function call in an NSObject with a C{doIt:}
     method.
     """
-    _thunk: Callable[[], None]
 
-    def initWithFunction_(self, thunk: Callable[[], None]) -> Actionable:
+    _thunk: Callable[[], object]
+    _state: ItemState
+
+    def initWithFunction_andState_(
+        self, thunk: Callable[[], None], state: ItemState
+    ) -> Actionable:
         """
         Remember the given callable.
 
         @param thunk: the callable to run in L{doIt_}.
         """
         self._thunk = thunk
+        self._state = state
         return self
 
     @IBAction
@@ -52,10 +74,41 @@ class Actionable(NSObject):
         Call the given callable; exposed as an C{IBAction} in case you want IB
         to be able to see it.
         """
-        self._thunk()
+        result = self._thunk()
+        if isinstance(result, ItemState):
+            self._state = result
+
+    def validateMenuItem_(self, item: NSMenuItem) -> bool:
+        item.setState_(
+            NSControlStateValueOn if self._state.checked else NSControlStateValueOff
+        )
+        return self._state.enabled
+
+
+ACTION_METHOD = asSelectorString(Actionable.doIt_)
+
+
+def _adjust(
+    items: Iterable[
+        tuple[str, Callable[[], object]] | tuple[str, Callable[[], object], ItemState]
+    ],
+) -> Iterable[tuple[str, Callable[[], object], ItemState]]:
+    for item in items:
+        if len(item) == 3:
+            yield item
+        else:
+            yield (*item, ItemState())
+
 
+ItemSeq = Sequence[
+    tuple[str, Callable[[], object]] | tuple[str, Callable[[], object], ItemState]
+]
 
-def menu(title: str, items: list[tuple[str, Callable[[], object]]]) -> NSMenu:
+
+def menu(
+    title: str,
+    items: ItemSeq,
+) -> NSMenu:
     """
     Construct an NSMenu from a list of tuples describing it.
 
@@ -68,11 +121,16 @@ def menu(title: str, items: list[tuple[str, Callable[[], object]]]) -> NSMenu:
     @return: a new Menu tha is not attached to anything.
     """
     result = NSMenu.alloc().initWithTitle_(title)
-    for (subtitle, thunk) in items:
+    for subtitle, thunk, state in _adjust(items):
+        initialKeyEquivalent = subtitle[0].lower()
         item = NSMenuItem.alloc().initWithTitle_action_keyEquivalent_(
-            subtitle, "doIt:", subtitle[0].lower()
+            subtitle,
+            ACTION_METHOD,
+            initialKeyEquivalent if state.key is None else state.key,
+        )
+        item.setTarget_(
+            Actionable.alloc().initWithFunction_andState_(thunk, state).retain()
         )
-        item.setTarget_(Actionable.alloc().initWithFunction_(thunk).retain())
         result.addItem_(item)
     result.update()
     return result
@@ -97,11 +155,12 @@ class Status:
             self.item.button().setImage_(image)
         elif text is None:
             from __main__ import __file__ as default
+
             text = os.path.basename(default)
         if text is not None:
             self.item.button().setTitle_(text)
 
-    def menu(self, items: list[tuple[str, Callable[[], object]]]) -> None:
+    def menu(self, items: ItemSeq) -> None:
         """
         Set the status drop-down menu.
 
@@ -177,12 +236,13 @@ 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
         way to do this.)
     """
+
     keyEquivalentHandler: NSResponder = ivar()
 
     def sendEvent_(self, event: NSEvent) -> None:
@@ -210,6 +270,7 @@ class MainRunner(Protocol):
     """
     A function which has been decorated with a runMain attribute.
     """
+
     def __call__(self, reactor: Any) -> None:
         """
         @param reactor: A Twisted reactor, which provides the usual suspects of
@@ -218,6 +279,7 @@ class MainRunner(Protocol):
 
     runMain: Callable[[], None]
 
+
 def mainpoint() -> Callable[[Callable[[Any], None]], MainRunner]:
     """
     Add a .runMain attribute to function
@@ -227,10 +289,11 @@ def mainpoint() -> Callable[[Callable[[Any], None]], MainRunner]:
         The runMain attribute starts a reactor and calls the original function
         with a running, initialized, reactor.
     """
+
     def wrapup(appmain: Callable[[Any], None]) -> MainRunner:
         def doIt() -> None:
-            from twisted.internet import cfreactor
             import PyObjCTools.AppHelper
+            from twisted.internet import cfreactor
 
             QuickApplication.sharedApplication()
 

{quickmacapp-2025.4.4 → quickmacapp-2025.6.24}/src/quickmacapp/notifications.py

@@ -12,18 +12,18 @@ from zoneinfo import ZoneInfo
 from datetype import DateTime
 from UserNotifications import (
     UNNotificationCategoryOptionCustomDismissAction as _UNNotificationCategoryOptionCustomDismissAction,
-    UNUserNotificationCenter as _UNUserNotificationCenter,
     UNNotificationDefaultActionIdentifier as _UNNotificationDefaultActionIdentifier,
     UNNotificationDismissActionIdentifier as _UNNotificationDismissActionIdentifier,
 )
+from UserNotifications import UNUserNotificationCenter as _UNUserNotificationCenter
 
 from quickmacapp._notifications import (
     NotificationTranslator,
+    _AppNotificationsCtxBuilder,
     _BuiltinActionInfo,
     _PlainNotificationActionInfo,
     _setActionInfo,
     _TextNotificationActionInfo,
-    _AppNotificationsCtxBuilder,
 )
 
 __all__ = [
@@ -139,6 +139,9 @@ class Notifier[NotifT](Protocol):
 
 
 class NotificationConfig(Protocol):
+    """
+    The application-wide configuration for a notification.
+    """
 
     def add[NotifT](
         self,
@@ -147,7 +150,35 @@ class NotificationConfig(Protocol):
         allowInCarPlay: bool = False,
         hiddenPreviewsShowTitle: bool = False,
         hiddenPreviewsShowSubtitle: bool = False,
-    ) -> Notifier[NotifT]: ...
+    ) -> 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]:
@@ -208,7 +239,7 @@ def configureNotifications() -> _AbstractAsyncContextManager[NotificationConfig]
     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
+    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:
@@ -226,7 +257,7 @@ def configureNotifications() -> _AbstractAsyncContextManager[NotificationConfig]
     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}).
+    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

{quickmacapp-2025.4.4 → quickmacapp-2025.6.24}/src/quickmacapp.egg-info/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: quickmacapp
-Version: 2025.4.4
+Version: 2025.6.24
 Summary: Make it easier to write Mac apps in Python
 Description-Content-Type: text/x-rst
 License-File: LICENSE