{"id":6187,"library":"pyobjc-framework-usernotificationsui","title":"User Notifications UI Framework (PyObjC)","description":"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.","status":"active","version":"12.1","language":"en","source_language":"en","source_url":"https://github.com/ronaldoussoren/pyobjc","tags":["macos","cocoa","ui","notifications","app extension"],"install":[{"cmd":"pip install pyobjc-framework-usernotificationsui","lang":"bash","label":"Install latest version"}],"dependencies":[{"reason":"The core PyObjC bridge is required for all framework wrappers.","package":"pyobjc-core","optional":false}],"imports":[{"note":"Classes within PyObjC framework wrappers are typically imported directly from the top-level framework package.","symbol":"UNNotificationContentExtension","correct":"from UserNotificationsUI import UNNotificationContentExtension"},{"note":"Core notification objects like UNNotification are part of the Foundation framework, not UserNotificationsUI.","symbol":"UNNotification","correct":"from Foundation import UNNotification"},{"note":"Notification Content Extensions are subclasses of NSViewController, which is part of the AppKit framework.","symbol":"NSViewController","correct":"from AppKit import NSViewController"}],"quickstart":{"code":"import objc\nfrom AppKit import NSViewController\nfrom Foundation import NSObject, NSLog, UNNotification\nfrom UserNotificationsUI import UNNotificationContentExtension\n\nclass MyNotificationViewController (NSObject, NSViewController, UNNotificationContentExtension):\n    \"\"\"\n    This class defines a custom view controller for a rich notification.\n    It runs as part of a macOS Notification Content Extension.\n    This code is illustrative and not directly runnable as a standalone script.\n    It requires an Xcode project with a Notification Content Extension target\n    configured to use this Python class as its principal class.\n    \"\"\"\n\n    # @objc.IBOutlet('myLabel') # Example if using a NIB/Storyboard\n    # myLabel = objc.ivar.IBOutlet()\n\n    def viewDidLoad(self):\n        super().viewDidLoad()\n        NSLog(\"MyNotificationViewController: viewDidLoad called!\")\n        # Access your UI elements here, if loaded from NIB/Storyboard\n        # if self.myLabel:\n        #    self.myLabel.setStringValue_(\"Hello from PyObjC notification!\")\n\n    def didReceiveNotification_(self, notification: UNNotification):\n        \"\"\"\n        Called when a new notification arrives for the extension to display.\n        \"\"\"\n        content = notification.request().content()\n        NSLog(f\"Received notification with title: {content.title()}, body: {content.body()}\")\n        # Update your custom UI elements based on the notification content\n        # if self.myLabel:\n        #    self.myLabel.setStringValue_(content.body())\n\n    def didReceiveNotificationResponse_completionHandler_(self, response, completionHandler):\n        \"\"\"\n        Called when the user interacts with your custom notification UI (e.g., clicks a button).\n        \"\"\"\n        NSLog(f\"Received response for action: {response.actionIdentifier()} with text: {response.userText()}\")\n        # Perform actions based on user interaction\n        completionHandler(UNNotificationContentExtension.UNNotificationContentExtensionResponseOptionDoNotDismiss)\n\n# To integrate this, you would typically build a macOS application with py2app\n# and include a Notification Content Extension target in Xcode that points to\n# this Python code as its principal class.","lang":"python","description":"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."},"warnings":[{"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).","message":"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.","severity":"breaking","affected_versions":">=11.0"},{"fix":"Review custom Objective-C subclasses and initializer method implementations for correct reference counting behavior under PyObjC 11.1+ ARC rules.","message":"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.","severity":"breaking","affected_versions":">=11.1"},{"fix":"Avoid subclassing `NSString` or `NSMutableString` directly in Python. Use existing methods or create helper functions/classes that wrap `NSString` instances instead.","message":"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.","severity":"gotcha","affected_versions":"All versions"},{"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.","message":"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.","severity":"gotcha","affected_versions":"All versions"},{"fix":"Ensure your development and deployment environment is macOS.","message":"PyObjC is a macOS-only library and will not function on other operating systems like Windows or Linux.","severity":"gotcha","affected_versions":"All versions"}],"env_vars":null,"last_verified":"2026-04-14T00:00:00.000Z","next_check":"2026-07-13T00:00:00.000Z","problems":[]}