PyObjC ContactsUI Framework

Warnings

• breaking PyObjC frequently drops support for older Python versions. For example, version 12.0 dropped support for Python 3.9, and version 11.0 dropped Python 3.8. Always check the release notes for minimum Python version requirements before upgrading.
  Fix: Ensure your Python environment meets the minimum version requirement for the PyObjC version you are installing or upgrading to. Use `pyenv` or `conda` to manage Python versions.
• breaking PyObjC versions are tightly coupled with macOS SDKs. Installing an older PyObjC version with a newer macOS SDK, or vice-versa, can lead to build errors or runtime issues due to missing or changed APIs.
  Fix: Always install the PyObjC version that is compatible with your macOS SDK. Use `pip install pyobjc` (or a specific framework like `pyobjc-framework-contactsui`) on the target machine to ensure the correct wheels are installed for your OS and Python version.
• gotcha Objective-C selectors with colons (e.g., `doSomething:withSomethingElse:`) are translated into Python method names with underscores (e.g., `doSomething_withSomethingElse_`). Each underscore represents an argument.
  Fix: When calling Objective-C methods from Python via PyObjC, convert all colons in the Objective-C selector to underscores in the Python method name. Ensure the number of arguments passed matches the number of underscores/colons.
• gotcha Starting with PyObjC 11.1, the core bridge aligns with `clang`'s Automatic Reference Counting (ARC) documentation for initializer methods. Methods in the 'init' family now correctly steal a reference to `self` and return a new reference, which might change reference counting behavior in complex `alloc().init()` patterns.
  Fix: Review code that manually manages object lifetimes or relies on specific `alloc().init()` reference counting behavior, especially when subclassing Objective-C classes. In most cases, PyObjC handles this automatically, but custom memory management code might need adjustments.
• gotcha PyObjC 10.3 introduced changes that could break `__init__` when a class (or its superclass) defines its own `__new__`. Version 10.3.1 partially reverted this, reintroducing the ability to use `__init__` if `__new__` is user-implemented, but not for PyObjC's provided `__new__`.
  Fix: If experiencing issues with `__init__` not being called after `__new__`, ensure you are on `pyobjc` 10.3.1 or later. If relying on PyObjC's default `__new__`, avoid implementing `__init__` in a way that bypasses Objective-C's two-phase initialization (alloc/init).
• deprecated PyObjC removes bindings for macOS frameworks that are deprecated and removed by Apple in newer macOS SDKs. For example, `IMServicePlugIn` bindings were removed in PyObjC 10.0 because the framework was deprecated in macOS 10.13 and removed in macOS 14.
  Fix: Periodically review Apple's developer documentation for framework deprecations and plan to update your application's dependencies and code to newer frameworks as needed when upgrading PyObjC or macOS.

Install

• pip install pyobjc-framework-contactsui Install latest version

Imports

• CNContactPickerViewController

  from ContactsUI import CNContactPickerViewController

  Main class for displaying the contact picker.
• NSApplication

  from AppKit import NSApplication

  Standard import for Cocoa applications to manage the application lifecycle.
• NSObject

  from Foundation import NSObject

  Base class for most Objective-C objects, often used for delegate implementations.
• CNContactPickerDelegate

  from ContactsUI import CNContactPickerDelegate

  Protocol for handling contact picker events. Implement this in a Python class.
• CNContact

  from Contacts import CNContact

  Used for representing contacts, often in conjunction with ContactsUI results.

Quickstart

This quickstart demonstrates how to display a `CNContactPickerViewController` to allow the user to select contacts. It initializes an `NSApplication`, sets up a `CNContactPickerDelegate` to handle selection or cancellation, and then presents the picker as a sheet. The selected contact's name and phone numbers are logged. Note that running PyObjC UI code typically requires an active `NSApplication` event loop.

import objc
from AppKit import NSApplication, NSApp, NSObject, NSWindow
from ContactsUI import CNContactPickerViewController, CNContactPickerDelegate
from Contacts import CNContactGivenNameKey, CNContactFamilyNameKey, CNContactPhoneNumbersKey
from Foundation import NSLog


class ContactPickerDelegate(NSObject, CNContactPickerDelegate):
    def contactPicker_didSelectContact_(self, picker, contact):
        NSLog("Selected contact: %@ %@", contact.givenName(), contact.familyName())
        for phone_number in contact.phoneNumbers():
            NSLog("  Phone: %@", phone_number.value().stringValue())
        picker.dismissViewControllerAnimated_completion_(True, None)
        NSApp().stop_(None)

    def contactPickerDidCancel_(self, picker):
        NSLog("Contact picker cancelled")
        picker.dismissViewControllerAnimated_completion_(True, None)
        NSApp().stop_(None)


def main():
    app = NSApplication.sharedApplication()
    delegate = ContactPickerDelegate.alloc().init()

    picker = CNContactPickerViewController.alloc().init()
    picker.setDelegate_(delegate)
    picker.setDisplayedPropertyKeys_([CNContactGivenNameKey, CNContactFamilyNameKey, CNContactPhoneNumbersKey])

    # Present the picker. In a real app, this would typically be triggered by a button click.
    # For a simple script, we'll just present it directly from a dummy window or by itself.
    # For a console app, it usually needs a backing NSApplication and a way to present it.
    # Creating a minimal window to anchor it for this quickstart example.
    from AppKit import NSWindow, NSBorderlessWindowMask, NSBackingStoreBuffered
    from Foundation import NSMakeRect

    dummy_window = NSWindow.alloc().initWithContentRect_styleMask_backing_defer_(
        NSMakeRect(0, 0, 1, 1), NSBorderlessWindowMask, NSBackingStoreBuffered, False
    )
    dummy_window.orderOut_(None)
    app.activateIgnoringOtherApps_(True)
    
    app.beginSheet_modalForWindow_modalDelegate_didEndSelector_contextInfo_(
        picker.view(),
        dummy_window,
        None,  # No modal delegate needed for simple dismiss
        None,
        None
    )
    
    # The picker is presented as a sheet, which requires the app run loop.
    app.run()

if __name__ == '__main__':
    main()