PyObjC PushKit Framework

Warnings

• breaking PyObjC 12.0 dropped support for Python 3.9. Ensure your project uses Python 3.10 or later.
  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`).
• breaking 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.
  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.
• gotcha 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.
  Fix: Ensure an appropriate `AppHelper.runConsoleEventLoop()` call or integration into an `NSApplication` runloop is present in your application's main execution flow.
• gotcha 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.
  Fix: Familiarize yourself with basic Objective-C and Cocoa programming patterns and consult Apple's official documentation for the `PushKit` framework and `PKPushRegistryDelegate` protocol.
• gotcha 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.
  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.

Install

• pip install pyobjc-framework-pushkit Install latest version

Imports

• PKPushRegistry

  from PushKit import PKPushRegistry

• PKPushRegistryDelegate

  from PushKit import PKPushRegistryDelegate

• PKPushTypeVoIP

  from PushKit import PKPushTypeVoIP

Quickstart

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.

import objc
from Foundation import NSObject, NSLog, NSSet
from PushKit import PKPushRegistry, PKPushRegistryDelegate, PKPushTypeVoIP
from PyObjCTools import AppHelper


class PushDelegate(NSObject):
    # Adopting the PKPushRegistryDelegate protocol
    def init(self):
        self = objc.super(PushDelegate, self).init()
        if self is None:
            return None
        NSLog('PushDelegate initialized.')
        return self

    def pushRegistry_didUpdatePushCredentials_forType_(self, registry, credentials, pushType):
        NSLog(f'pushRegistry:didUpdatePushCredentials:forType_ called for type: {pushType}, token: {credentials.token()}')
        # In a real app, send credentials.token() to your server
        # for APNs registration.

    def pushRegistry_didReceiveIncomingPushWithPayload_forType_completionHandler_(self, registry, payload, pushType, completion):
        NSLog(f'pushRegistry:didReceiveIncomingPushWithPayload:forType:completionHandler_ called for type: {pushType}, payload: {payload}')
        # Process the incoming push notification payload.
        # Call the completion handler when done.
        completion()

    def pushRegistry_didInvalidatePushTokenForType_error_(self, registry, pushType, error):
        NSLog(f'pushRegistry:didInvalidatePushTokenForType:error_ called for type: {pushType}, error: {error}')


def main():
    # Initialize an NSApplication (required for delegate pattern)
    # For a console app, you might not explicitly use NSApplication.sharedApplication(),
    # but the runloop expects a Cocoa environment.
    # from AppKit import NSApplication # Uncomment if you need direct AppKit interaction

    # Create the push registry delegate
    delegate = PushDelegate.alloc().init()

    # Create a PKPushRegistry object
    # initWithQueue:nil means callbacks happen on the main thread
    # PKPushRegistry requires a queue, typically the main queue for UI apps
    # For a simple console app, we can use nil to imply the main thread's runloop.
    push_registry = PKPushRegistry.alloc().initWithQueue_(None)
    push_registry.setDelegate_(delegate)

    # Register for VoIP push notifications
    push_registry.setDesiredPushTypes_(NSSet.setWithObject_(PKPushTypeVoIP))

    NSLog('PushKit registration initiated. Entering app event loop.')
    # Run the application's event loop. This is crucial for receiving delegate callbacks.
    # In a real app, this would be part of the main NSApplication runloop.
    # For a simple console demonstration, AppHelper.runConsoleEventLoop() is used.
    try:
        AppHelper.runConsoleEventLoop(installInterrupt=True)
    except KeyboardInterrupt:
        NSLog('Application terminated by user.')
        AppHelper.stopEventLoop()


if __name__ == '__main__':
    main()