{"id":5799,"library":"pyobjc-framework-addressbook","title":"AddressBook Framework Bindings for PyObjC","description":"pyobjc-framework-addressbook provides Pythonic wrappers for the macOS AddressBook framework, allowing Python applications to interact with contact data. It is part of the larger PyObjC project, which bridges Python and Objective-C. The current version is 12.1 and new releases generally align with macOS SDK updates and Python version support changes.","status":"active","version":"12.1","language":"en","source_language":"en","source_url":"https://github.com/ronaldoussoren/pyobjc","tags":["macos","pyobjc","framework","addressbook","contacts","objective-c"],"install":[{"cmd":"pip install pyobjc-framework-addressbook","lang":"bash","label":"Install PyObjC AddressBook bindings"}],"dependencies":[{"reason":"Provides the core bridge between Python and Objective-C.","package":"pyobjc-core","optional":false}],"imports":[{"note":"All classes and functions from the AddressBook framework are exposed under the 'AddressBook' package.","symbol":"ABAddressBook","correct":"from AddressBook import ABAddressBook"},{"symbol":"ABPerson","correct":"from AddressBook import ABPerson"}],"quickstart":{"code":"from AddressBook import ABAddressBook, ABPerson\n\ndef get_first_person_name():\n    try:\n        # On modern macOS, you might need to grant permission to access contacts.\n        # This code will likely prompt for permission the first time it's run.\n        book = ABAddressBook.sharedAddressBook() #\n        people = book.people() #\n\n        if people.count() > 0:\n            person = people[0] #\n            display_name = person.displayName() #\n            return display_name\n        else:\n            return \"No contacts found.\"\n    except Exception as e:\n        return f\"An error occurred: {e}\"\n\nif __name__ == '__main__':\n    print(f\"First contact's display name: {get_first_person_name()}\")","lang":"python","description":"Fetches the default AddressBook instance and prints the name of the first person found, if any. Note that on modern macOS, this might trigger a privacy permission prompt."},"warnings":[{"fix":"Upgrade to Python 3.10 or newer, or use an older PyObjC version that supports your Python runtime.","message":"PyObjC has dropped support for older Python versions in recent major releases. Version 12.0 dropped support for Python 3.9, and version 11.0 dropped support for Python 3.8. Ensure your Python environment meets the 'requires_python' specification (>=3.10).","severity":"breaking","affected_versions":"11.0, 12.0"},{"fix":"Migrate your application logic to use the Contacts framework instead of AddressBook.","message":"The AddressBook framework itself has been deprecated by Apple since macOS 10.11. For new development, it is strongly recommended to use the Contacts framework (available via `pyobjc-framework-Contacts`) instead.","severity":"breaking","affected_versions":"All versions, due to macOS deprecation."},{"fix":"Remove any dependencies on the `IMServicePlugIn` framework. Consider alternative APIs if functionality is still required.","message":"The `IMServicePlugIn` framework bindings were entirely removed in PyObjC 10.0, as the framework was deprecated in macOS 10.13 and removed in macOS 14.","severity":"breaking","affected_versions":"10.0 and later"},{"fix":"For Python subclasses of Objective-C classes, prefer Objective-C style `init*` methods for initialization. If you implement a custom `__new__`, ensure `__init__` is correctly invoked if needed. Avoid using `__init__` if `__new__` is implicitly provided by PyObjC for standard Objective-C class instantiation.","message":"In PyObjC 10.3, the behavior around `__init__` when a Python class relies on PyObjC's provided `__new__` for Objective-C object instantiation changed, preventing `__init__` from being called. While PyObjC 10.3.1 partially reverted this for user-implemented `__new__` methods, code relying on the `__new__` provided by PyObjC still cannot use `__init__`.","severity":"gotcha","affected_versions":"10.3, 10.3.1"},{"fix":"Ensure that any `NSURL` or `CFURLRef` objects passed to `os.fspath()` represent local filesystem paths. Handle non-local URLs appropriately without `os.fspath()` if a `TypeError` is encountered.","message":"Using `os.fspath()` with Cocoa URLs (like `NSURL` or `CFURLRef`) that *do not* refer to local filesystem paths will raise a `TypeError`. This functionality was improved in PyObjC 10.1 to enable standard Python filesystem APIs for *local* paths.","severity":"gotcha","affected_versions":"10.1 and later"},{"fix":"Be aware that KVO will not function for Python subclasses of `NSProxy`. If KVO-like functionality is required, implement it manually or consider alternative class structures.","message":"As of PyObjC 12.1, Key-Value Observation (KVO) usage is automatically disabled for subclasses of `NSProxy` defined in Python to prevent unexpected behavior.","severity":"gotcha","affected_versions":"12.1 and later"}],"env_vars":null,"last_verified":"2026-04-14T00:00:00.000Z","next_check":"2026-07-13T00:00:00.000Z"}