PyObjC UserNotifications Framework

Warnings

• breaking Python 3.9 support was dropped in PyObjC 12.0. If you are using Python 3.9, you must use an older version of PyObjC.
  Fix: Upgrade your Python environment to 3.10 or later, or pin `pyobjc-framework-usernotifications<12.0`.
• breaking Python 3.8 support was dropped in PyObjC 11.0. If you are using Python 3.8, you must use an older version of PyObjC.
  Fix: Upgrade your Python environment to 3.9 or later, or pin `pyobjc-framework-usernotifications<11.0`.
• breaking PyObjC 11.1 introduced changes to align initializer method (e.g., `init*`) behavior with `clang`'s Automatic Reference Counting (ARC) documentation. This means `init` methods now correctly 'steal' a reference to `self` and return a new one, which might alter reference counting and lead to memory management issues or crashes in existing code that relies on older reference semantics.
  Fix: Review custom `init` methods in your PyObjC code to ensure they adhere to ARC best practices for reference handling. Consult the PyObjC documentation on 'What's new' for version 11.1 and clang's ARC documentation.
• gotcha In PyObjC 10.3, behavior around user-defined `__new__` and `__init__` methods changed, preventing `__init__` from being called in some cases. While partially reverted in 10.3.1 to reintroduce `__init__` calls for user-defined `__new__` methods, `__init__` is still not called when relying on PyObjC's default `__new__` implementation. This can lead to unexpected initialization behavior.
  Fix: If your classes implement custom `__new__`, ensure `__init__` is explicitly called or that initialization logic is handled within `__new__`. Refer to PyObjC's documentation regarding object instantiation for detailed guidance.

Install

• pip install pyobjc-framework-usernotifications Install pyobjc-framework-usernotifications

Imports

• UserNotifications

  from UserNotifications import *

  PyObjC frameworks are typically imported directly from their top-level module name.
• Foundation

  from Foundation import *

  Often needed for basic Objective-C types and runtime functions when working with Cocoa frameworks.

Quickstart

This quickstart demonstrates how to send a simple user notification using `pyobjc-framework-usernotifications`. It requests notification authorization, creates notification content and a trigger, and then schedules the notification. The script uses `NSRunLoop` to keep the Python process alive briefly, allowing macOS to process and display the notification. For persistent applications, a full `NSApplication` run loop would be required.

import objc
from Foundation import *
from UserNotifications import *

def send_test_notification():
    center = UNUserNotificationCenter.currentNotificationCenter()

    # Request authorization for alerts, sounds, and badges
    options = UNAuthorizationOptionAlert | UNAuthorizationOptionSound | UNAuthorizationOptionBadge
    # The completionHandler can be None for simple cases if no Python callback is needed.
    granted, error = center.requestAuthorizationWithOptions_completionHandler_(options, None)
    
    if error:
        print(f"Error requesting authorization: {error.localizedDescription()}") # cite: 11
        return
    
    if not granted:
        print("Notification authorization denied. Please enable in System Settings -> Notifications -> Python.") # cite: 11
        return

    # Create notification content
    content = UNMutableNotificationContent.alloc().init()
    content.setTitle_("PyObjC Notification")
    content.setBody_("This is a test notification from your Python script!")
    content.setSound_(UNNotificationSound.defaultSound())
    content.setUserInfo_({"source": "PyObjC"}) # Optional: Add custom data

    # Create a trigger for immediate delivery (1 second from now, no repeat)
    trigger = UNTimeIntervalNotificationTrigger.triggerWithTimeInterval_repeats_(1, False)

    # Create the request with a unique identifier, content, and trigger
    request = UNNotificationRequest.requestWithIdentifier_content_trigger_("pyobjcTestNotification", content, trigger)

    # Add the request to the notification center
    center.addNotificationRequest_withCompletionHandler_(request, None)
    print("Notification request added. Check your macOS Notification Center.")

    # Keep the Python process alive briefly to allow the notification to be processed by macOS.
    # In a full macOS application, you would typically run an NSApplication main loop.
    NSRunLoop.currentRunLoop().runUntilDate_(NSDate.dateWithTimeIntervalSinceNow_(3.0))
    print("Script finished. Notification should appear shortly if authorized.")

if __name__ == "__main__":
    send_test_notification()