{"id":6121,"library":"pyobjc-framework-iobluetoothui","title":"PyObjC: IOBluetoothUI Framework","description":"pyobjc-framework-iobluetoothui provides Python wrappers for Apple's IOBluetoothUI.framework on macOS, allowing Python applications to interact with Bluetooth-related user interface components. It is part of the larger PyObjC project, which bridges Python and the Objective-C runtime. The current version is 12.1, with releases typically tied to new macOS SDKs and Python version support cycles.","status":"active","version":"12.1","language":"en","source_language":"en","source_url":"https://github.com/ronaldoussoren/pyobjc","tags":["macos","pyobjc","bluetooth","ui","framework","objective-c"],"install":[{"cmd":"pip install pyobjc-framework-iobluetoothui","lang":"bash","label":"Install latest version"}],"dependencies":[{"reason":"Core bridge for PyObjC frameworks, installed automatically.","package":"pyobjc-core","optional":false}],"imports":[{"note":"PyObjC recommends direct import of classes from the framework package for clarity and consistency.","wrong":"import IOBluetoothUI; browser = IOBluetoothUI.IOBluetoothServiceBrowserController.alloc().init()","symbol":"IOBluetoothServiceBrowserController","correct":"from IOBluetoothUI import IOBluetoothServiceBrowserController"},{"symbol":"NSApplication","correct":"from AppKit import NSApplication"},{"symbol":"NSObject","correct":"from Foundation import NSObject"},{"symbol":"AppHelper","correct":"from PyObjCTools import AppHelper"}],"quickstart":{"code":"from Foundation import NSObject\nfrom AppKit import NSApplication\nfrom PyObjCTools import AppHelper\nfrom IOBluetoothUI import IOBluetoothServiceBrowserController\n\nclass AppDelegate(NSObject):\n    def applicationDidFinishLaunching_(self, notification):\n        print(\"Application finished launching. Showing Bluetooth Service Browser...\")\n        self.browserController = IOBluetoothServiceBrowserController.withServiceBrowserController_()\n        if self.browserController:\n            # Options can be specified here, e.g., 0 for default\n            self.browserController.setOptions_(0) \n            # showModal_ blocks until the browser dialog is dismissed\n            self.browserController.showModal_(None) \n            print(\"Bluetooth Service Browser dismissed.\")\n        else:\n            print(\"Failed to create IOBluetoothServiceBrowserController.\")\n        # In a real app, you might want to quit the app or keep it running\n        # For this quickstart, we'll quit after the modal dialog is dismissed.\n        NSApplication.sharedApplication().terminate_(None)\n\ndef main():\n    app = NSApplication.sharedApplication()\n    delegate = AppDelegate.alloc().init()\n    app.setDelegate_(delegate)\n    # Run the Cocoa event loop\n    AppHelper.runEventLoop()\n\nif __name__ == \"__main__\":\n    main()","lang":"python","description":"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."},"warnings":[{"fix":"Ensure your Python environment meets the minimum version requirement for the PyObjC version you are installing. Upgrade Python if necessary.","message":"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.","severity":"breaking","affected_versions":">=11.0"},{"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.","message":"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.","severity":"breaking","affected_versions":">=11.1"},{"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__`.","message":"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.","severity":"gotcha","affected_versions":">=10.3"},{"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.","message":"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.","severity":"gotcha","affected_versions":">=10.3, <12.0"},{"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.","message":"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.","severity":"breaking","affected_versions":">=10.0"}],"env_vars":null,"last_verified":"2026-04-14T00:00:00.000Z","next_check":"2026-07-13T00:00:00.000Z","problems":[]}