AddressBook Framework Bindings for PyObjC

12.1 · active · verified Tue Apr 14

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.

Warnings

breaking 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).
Fix: Upgrade to Python 3.10 or newer, or use an older PyObjC version that supports your Python runtime.
breaking 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.
Fix: Migrate your application logic to use the Contacts framework instead of AddressBook.
breaking 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.
Fix: Remove any dependencies on the `IMServicePlugIn` framework. Consider alternative APIs if functionality is still required.
gotcha 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__`.
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.
gotcha 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.
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.
gotcha As of PyObjC 12.1, Key-Value Observation (KVO) usage is automatically disabled for subclasses of `NSProxy` defined in Python to prevent unexpected behavior.
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.

Install

pip install pyobjc-framework-addressbook Install PyObjC AddressBook bindings

Imports

ABAddressBook
```
from AddressBook import ABAddressBook
```
All classes and functions from the AddressBook framework are exposed under the 'AddressBook' package.
ABPerson
```
from AddressBook import ABPerson
```

Quickstart

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.

from AddressBook import ABAddressBook, ABPerson

def get_first_person_name():
    try:
        # On modern macOS, you might need to grant permission to access contacts.
        # This code will likely prompt for permission the first time it's run.
        book = ABAddressBook.sharedAddressBook() #
        people = book.people() #

        if people.count() > 0:
            person = people[0] #
            display_name = person.displayName() #
            return display_name
        else:
            return "No contacts found."
    except Exception as e:
        return f"An error occurred: {e}"

if __name__ == '__main__':
    print(f"First contact's display name: {get_first_person_name()}")

view raw JSON →