PyObjC: IOBluetoothUI Framework

Warnings

• breaking PyObjC frequently drops support for older Python versions. PyObjC 12.0 dropped support for Python 3.9, and PyObjC 11.0 dropped support for Python 3.8. Always check the `requires_python` metadata or release notes when upgrading.
  Fix: Ensure your Python environment meets the minimum version requirement for the PyObjC version you are installing. Upgrade Python if necessary.
• breaking PyObjC 11.1 introduced a significant change in how Automatic Reference Counting (ARC) is modeled for initializer methods. Methods in the 'init' family now correctly steal a reference to self and return a new reference, aligning with `clang`'s documentation. This can affect object lifecycle management if you relied on previous PyObjC behavior.
  Fix: Review code involving custom `alloc`-`init` patterns or manual reference counting with older PyObjC versions. Adapt to the correct ARC semantics, particularly for methods returning newly allocated objects.
• gotcha Interactions between Python's `__init__` and `__new__` methods in PyObjC classes saw changes in versions 10.3 and 10.3.1. While 10.3 initially dropped `__init__` support when `__new__` was provided by PyObjC, 10.3.1 reintroduced `__init__` support for classes with user-implemented `__new__`. However, classes relying on PyObjC's default `__new__` still cannot use `__init__` for initialization.
  Fix: If defining custom Objective-C classes in Python, use the `alloc().init()` pattern or a custom `__new__` method to ensure proper object initialization. Be aware of the specific `__init__` limitations when using PyObjC's default `__new__`.
• gotcha PyObjC 11.0 introduced experimental support for Python 3.13's free-threading (PEP 703), but PyObjC 10.3 explicitly stated that it does *not* support free threading in Python 3.13. Using PyObjC in a free-threaded Python 3.13 environment might lead to undefined behavior or crashes until full support is officially announced.
  Fix: If targeting Python 3.13, avoid relying on its experimental free-threading features when using PyObjC. Monitor PyObjC release notes for explicit free-threading support.
• breaking PyObjC framework bindings are tied to macOS SDKs. As Apple deprecates and removes frameworks, PyObjC will also remove their bindings. For example, the 'IMServicePlugIn' bindings were removed in PyObjC 10.0 due to their removal in macOS 14. Be aware that specific framework wrappers might disappear in new major PyObjC versions.
  Fix: When upgrading PyObjC or targeting newer macOS versions, verify that all required frameworks still have bindings available. Update application logic to use modern APIs if a framework has been removed or deprecated by Apple.

Install

• pip install pyobjc-framework-iobluetoothui Install latest version

Imports

• IOBluetoothServiceBrowserController

  from IOBluetoothUI import IOBluetoothServiceBrowserController

  PyObjC recommends direct import of classes from the framework package for clarity and consistency.
• NSApplication

  from AppKit import NSApplication

• NSObject

  from Foundation import NSObject

• AppHelper

  from PyObjCTools import AppHelper

Quickstart

This quickstart initializes a macOS Cocoa application, sets up a simple delegate, and then displays the IOBluetoothServiceBrowserController as a modal dialog. The application will wait for the user to dismiss the Bluetooth browser before terminating. This demonstrates how to interact with a core UI component from the IOBluetoothUI framework.

from Foundation import NSObject
from AppKit import NSApplication
from PyObjCTools import AppHelper
from IOBluetoothUI import IOBluetoothServiceBrowserController

class AppDelegate(NSObject):
    def applicationDidFinishLaunching_(self, notification):
        print("Application finished launching. Showing Bluetooth Service Browser...")
        self.browserController = IOBluetoothServiceBrowserController.withServiceBrowserController_()
        if self.browserController:
            # Options can be specified here, e.g., 0 for default
            self.browserController.setOptions_(0) 
            # showModal_ blocks until the browser dialog is dismissed
            self.browserController.showModal_(None) 
            print("Bluetooth Service Browser dismissed.")
        else:
            print("Failed to create IOBluetoothServiceBrowserController.")
        # In a real app, you might want to quit the app or keep it running
        # For this quickstart, we'll quit after the modal dialog is dismissed.
        NSApplication.sharedApplication().terminate_(None)

def main():
    app = NSApplication.sharedApplication()
    delegate = AppDelegate.alloc().init()
    app.setDelegate_(delegate)
    # Run the Cocoa event loop
    AppHelper.runEventLoop()

if __name__ == "__main__":
    main()