User Notifications UI Framework (PyObjC)

12.1 · active · verified Tue Apr 14

PyObjC is a bridge between Python and Objective-C, allowing Python scripts to use and extend existing Objective-C class libraries, including Cocoa frameworks on macOS. The `pyobjc-framework-usernotificationsui` package provides Python wrappers for the macOS UserNotificationsUI framework. This framework enables developers to customize the appearance and interactivity of local and remote notifications by adding a notification content app extension to their macOS applications. The current version is 12.1, and PyObjC generally follows an annual release cadence, typically in October.

Warnings

breaking PyObjC v12.0 dropped support for Python 3.9, and v11.0 dropped support for Python 3.8. Users on older Python versions must use an older PyObjC release.
Fix: Upgrade Python to 3.10 or later, or pin `pyobjc` and `pyobjc-core` to a compatible version (e.g., `pyobjc<12` for Python 3.9, `pyobjc<11` for Python 3.8).
breaking The behavior of initializer methods (methods in the 'init' family) was changed in PyObjC v11.1 to align with `clang`'s Automatic Reference Counting (ARC) documentation. Such methods now correctly 'steal' a reference to `self` and return a new reference. This may affect custom memory management or subclassing patterns if not accounted for.
Fix: Review custom Objective-C subclasses and initializer method implementations for correct reference counting behavior under PyObjC 11.1+ ARC rules.
gotcha Subclassing `NSString` or `NSMutableString` in Python is not supported and will lead to crashes. These classes are marked as 'final' in PyObjC due to their special handling in the bridge.
Fix: Avoid subclassing `NSString` or `NSMutableString` directly in Python. Use existing methods or create helper functions/classes that wrap `NSString` instances instead.
gotcha The `pyobjc-framework-usernotificationsui` library is specifically for customizing the *user interface* of notifications within a macOS app extension (a `UNNotificationContentExtension`). It does *not* provide functionality for sending or scheduling notifications; that is handled by the `UserNotifications` framework.
Fix: For sending notifications, use the `pyobjc-framework-usernotifications` package (import `UserNotifications`). For custom UI display of those notifications, use `pyobjc-framework-usernotificationsui` within an app extension.
gotcha PyObjC is a macOS-only library and will not function on other operating systems like Windows or Linux.
Fix: Ensure your development and deployment environment is macOS.

Install

pip install pyobjc-framework-usernotificationsui Install latest version

Imports

UNNotificationContentExtension
```
from UserNotificationsUI import UNNotificationContentExtension
```
Classes within PyObjC framework wrappers are typically imported directly from the top-level framework package.
UNNotification
```
from Foundation import UNNotification
```
Core notification objects like UNNotification are part of the Foundation framework, not UserNotificationsUI.
NSViewController
```
from AppKit import NSViewController
```
Notification Content Extensions are subclasses of NSViewController, which is part of the AppKit framework.

Quickstart

This quickstart demonstrates the basic structure for a Python class using `pyobjc-framework-usernotificationsui` to define a custom notification content extension. This framework is specifically for customizing the *appearance* and *interactivity* of notifications within a dedicated app extension, not for sending notifications. The code must be integrated into a macOS app extension project, typically set up via Xcode, where this Python class would act as the `UNNotificationContentExtension`'s view controller. It cannot be run as a standalone script.

import objc
from AppKit import NSViewController
from Foundation import NSObject, NSLog, UNNotification
from UserNotificationsUI import UNNotificationContentExtension

class MyNotificationViewController (NSObject, NSViewController, UNNotificationContentExtension):
    """
    This class defines a custom view controller for a rich notification.
    It runs as part of a macOS Notification Content Extension.
    This code is illustrative and not directly runnable as a standalone script.
    It requires an Xcode project with a Notification Content Extension target
    configured to use this Python class as its principal class.
    """

    # @objc.IBOutlet('myLabel') # Example if using a NIB/Storyboard
    # myLabel = objc.ivar.IBOutlet()

    def viewDidLoad(self):
        super().viewDidLoad()
        NSLog("MyNotificationViewController: viewDidLoad called!")
        # Access your UI elements here, if loaded from NIB/Storyboard
        # if self.myLabel:
        #    self.myLabel.setStringValue_("Hello from PyObjC notification!")

    def didReceiveNotification_(self, notification: UNNotification):
        """
        Called when a new notification arrives for the extension to display.
        """
        content = notification.request().content()
        NSLog(f"Received notification with title: {content.title()}, body: {content.body()}")
        # Update your custom UI elements based on the notification content
        # if self.myLabel:
        #    self.myLabel.setStringValue_(content.body())

    def didReceiveNotificationResponse_completionHandler_(self, response, completionHandler):
        """
        Called when the user interacts with your custom notification UI (e.g., clicks a button).
        """
        NSLog(f"Received response for action: {response.actionIdentifier()} with text: {response.userText()}")
        # Perform actions based on user interaction
        completionHandler(UNNotificationContentExtension.UNNotificationContentExtensionResponseOptionDoNotDismiss)

# To integrate this, you would typically build a macOS application with py2app
# and include a Notification Content Extension target in Xcode that points to
# this Python code as its principal class.

view raw JSON →