{"id":6158,"library":"pyobjc-framework-pushkit","title":"PyObjC PushKit Framework","description":"pyobjc-framework-pushkit provides Python wrappers for the PushKit framework on macOS, allowing Python applications to interact with Apple's PushKit services, such as VoIP push notifications. The library is currently at version 12.1 and typically releases new versions in alignment with macOS SDK updates, often with several releases per year to incorporate new features, bug fixes, and Python version support.","status":"active","version":"12.1","language":"en","source_language":"en","source_url":"https://github.com/ronaldoussoren/pyobjc","tags":["macos","objective-c","cocoa","push-notifications","apple","voip"],"install":[{"cmd":"pip install pyobjc-framework-pushkit","lang":"bash","label":"Install latest version"}],"dependencies":[{"reason":"Core bridge between Python and Objective-C, required for all PyObjC framework wrappers.","package":"pyobjc-core"},{"reason":"Provides fundamental Cocoa classes like NSObject and NSApplication, often implicitly required by macOS applications.","package":"pyobjc-framework-Cocoa","optional":true}],"imports":[{"symbol":"PKPushRegistry","correct":"from PushKit import PKPushRegistry"},{"symbol":"PKPushRegistryDelegate","correct":"from PushKit import PKPushRegistryDelegate"},{"symbol":"PKPushTypeVoIP","correct":"from PushKit import PKPushTypeVoIP"}],"quickstart":{"code":"import objc\nfrom Foundation import NSObject, NSLog, NSSet\nfrom PushKit import PKPushRegistry, PKPushRegistryDelegate, PKPushTypeVoIP\nfrom PyObjCTools import AppHelper\n\n\nclass PushDelegate(NSObject):\n    # Adopting the PKPushRegistryDelegate protocol\n    def init(self):\n        self = objc.super(PushDelegate, self).init()\n        if self is None:\n            return None\n        NSLog('PushDelegate initialized.')\n        return self\n\n    def pushRegistry_didUpdatePushCredentials_forType_(self, registry, credentials, pushType):\n        NSLog(f'pushRegistry:didUpdatePushCredentials:forType_ called for type: {pushType}, token: {credentials.token()}')\n        # In a real app, send credentials.token() to your server\n        # for APNs registration.\n\n    def pushRegistry_didReceiveIncomingPushWithPayload_forType_completionHandler_(self, registry, payload, pushType, completion):\n        NSLog(f'pushRegistry:didReceiveIncomingPushWithPayload:forType:completionHandler_ called for type: {pushType}, payload: {payload}')\n        # Process the incoming push notification payload.\n        # Call the completion handler when done.\n        completion()\n\n    def pushRegistry_didInvalidatePushTokenForType_error_(self, registry, pushType, error):\n        NSLog(f'pushRegistry:didInvalidatePushTokenForType:error_ called for type: {pushType}, error: {error}')\n\n\ndef main():\n    # Initialize an NSApplication (required for delegate pattern)\n    # For a console app, you might not explicitly use NSApplication.sharedApplication(),\n    # but the runloop expects a Cocoa environment.\n    # from AppKit import NSApplication # Uncomment if you need direct AppKit interaction\n\n    # Create the push registry delegate\n    delegate = PushDelegate.alloc().init()\n\n    # Create a PKPushRegistry object\n    # initWithQueue:nil means callbacks happen on the main thread\n    # PKPushRegistry requires a queue, typically the main queue for UI apps\n    # For a simple console app, we can use nil to imply the main thread's runloop.\n    push_registry = PKPushRegistry.alloc().initWithQueue_(None)\n    push_registry.setDelegate_(delegate)\n\n    # Register for VoIP push notifications\n    push_registry.setDesiredPushTypes_(NSSet.setWithObject_(PKPushTypeVoIP))\n\n    NSLog('PushKit registration initiated. Entering app event loop.')\n    # Run the application's event loop. This is crucial for receiving delegate callbacks.\n    # In a real app, this would be part of the main NSApplication runloop.\n    # For a simple console demonstration, AppHelper.runConsoleEventLoop() is used.\n    try:\n        AppHelper.runConsoleEventLoop(installInterrupt=True)\n    except KeyboardInterrupt:\n        NSLog('Application terminated by user.')\n        AppHelper.stopEventLoop()\n\n\nif __name__ == '__main__':\n    main()\n","lang":"python","description":"This quickstart demonstrates how to initialize `PKPushRegistry` and register for VoIP push notifications using `pyobjc-framework-pushkit`. It defines a delegate class to handle push registration updates and incoming notifications, then starts a console event loop to process these events. This code requires a macOS environment and an application bundle that has PushKit capabilities enabled."},"warnings":[{"fix":"Upgrade your Python environment to 3.10 or newer, or pin pyobjc-framework-pushkit to a version prior to 12.0 if Python 3.9 is required (e.g., `pyobjc-framework-pushkit<12.0`).","message":"PyObjC 12.0 dropped support for Python 3.9. Ensure your project uses Python 3.10 or later.","severity":"breaking","affected_versions":">=12.0"},{"fix":"Upgrade your Python environment to 3.9 or newer (preferably 3.10+ for current PyObjC versions). Review custom `__init__` and `alloc().init()` patterns in subclasses if upgrading from versions prior to 11.1.","message":"PyObjC 11.0 dropped support for Python 3.8. Additionally, version 11.1 introduced changes to how ARC behavior is modeled for initializer methods, aligning with `clang`'s documentation. This can affect custom Objective-C class subclasses in Python.","severity":"breaking","affected_versions":">=11.0"},{"fix":"Ensure an appropriate `AppHelper.runConsoleEventLoop()` call or integration into an `NSApplication` runloop is present in your application's main execution flow.","message":"PyObjC applications deeply integrate with the macOS Cocoa event loop. For console applications or scripts, you must explicitly run an event loop (e.g., using `PyObjCTools.AppHelper.runConsoleEventLoop()`) for delegate methods and other asynchronous Cocoa events to be processed.","severity":"gotcha","affected_versions":"all"},{"fix":"Familiarize yourself with basic Objective-C and Cocoa programming patterns and consult Apple's official documentation for the `PushKit` framework and `PKPushRegistryDelegate` protocol.","message":"PyObjC wraps Objective-C APIs directly, meaning Python code must adhere to Objective-C conventions (e.g., delegate patterns, snake_case_for_methods_ with_underscores_representing_colons, specific object lifecycle management) which can be unfamiliar to Python-only developers.","severity":"gotcha","affected_versions":"all"},{"fix":"Follow the sequence: instantiate `PKPushRegistry`, assign its `delegate`, then set `desiredPushTypes`. Store the `PKPushRegistry` and its delegate in long-lived variables to ensure they are not deallocated.","message":"PushKit requires specific registration steps: create a `PKPushRegistry` object at launch, keep a reference to it, and assign its delegate *before* setting `desiredPushTypes` to initiate registration. Incorrect ordering or failure to retain the registry object can lead to pushes not being received.","severity":"gotcha","affected_versions":"all"}],"env_vars":null,"last_verified":"2026-04-14T00:00:00.000Z","next_check":"2026-07-13T00:00:00.000Z"}