PyObjC Collaboration 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 Python 3.8. Ensure your Python version is compatible with the PyObjC version you are installing.
  Fix: Upgrade your Python environment to Python 3.10 or later for PyObjC 12.x. Always check `requires_python` on PyPI or the PyObjC changelog for specific version requirements.
• breaking PyObjC 10.3 introduced changes to `__new__` and `__init__` behavior, specifically disallowing direct use of `__init__` for classes relying on PyObjC's `__new__`. Version 10.3.1 partially reverted this to allow `__init__` when a user implements `__new__` or a superclass implements `__new__`. PyObjC 11.1 also aligned initializer methods with `clang`'s ARC documentation, affecting reference counting for `init` family methods.
  Fix: Review custom Python subclasses of Objective-C classes, especially those overriding `__new__` or `__init__`, to ensure they align with PyObjC's instantiation model. For ARC changes, understand that `init` methods now 'steal' a reference to `self` and return a new one.
• deprecated The `IMServicePlugIn` bindings were removed in PyObjC 10.0 as the entire framework was deprecated in macOS 10.13 and removed in macOS 14. Code relying on these bindings will fail.
  Fix: Update your application to use modern macOS APIs for instant messaging or collaboration, as the `IMServicePlugIn` framework is no longer supported by Apple or PyObjC.
• gotcha PyObjC is a macOS-specific library and will not install or run on other operating systems. The frameworks it wraps (like Collaboration) are Apple-proprietary.
  Fix: Only use `pyobjc-framework-collaboration` in macOS environments. For cross-platform development, consider alternative libraries or platform-specific conditional logic.
• gotcha Unlike Objective-C, where sending a message to `nil` (equivalent to Python `None`) is a no-op, attempting to call a method on a Python `None` object (which PyObjC translates from `nil`) will raise an `AttributeError`.
  Fix: Always check for `None` before calling methods on PyObjC-wrapped objects that might originate from Objective-C `nil` values. E.g., `if my_obj is not None: my_obj.doSomething_()`
• gotcha While PyObjC 11.0 introduced experimental support for free-threading (PEP 703) with Python 3.13, and later versions have improved it, note that Apple's underlying frameworks are not necessarily thread-safe. Concurrent access to Objective-C collections (like `NSMutableArray`) or `nonatomic` properties without explicit locking can lead to issues.
  Fix: When developing multi-threaded PyObjC applications, especially with free-threading, consult Apple's documentation for thread-safety guidelines of the specific Cocoa classes being used. Employ Python's threading primitives (locks, semaphores) where concurrent Objective-C access might be unsafe.

Install

• pip install pyobjc-framework-collaboration Install the Collaboration framework bindings

Imports

• CBIdentity

  from Collaboration import CBIdentity

  PyObjC frameworks map directly to Python packages. Classes, constants, and functions from the Collaboration framework are available after importing `Collaboration`.

Quickstart

This quickstart demonstrates how to import the `Collaboration` framework and list the available identity authorities on a macOS system. For interactive operations like presenting an identity picker, an `AppKit` run loop would typically need to be active. The example includes a minimal `NSApplication` setup for broader compatibility with PyObjC patterns, though it might not be strictly necessary for simple authority listing.

import objc
from Collaboration import CBIdentityAuthority
from AppKit import NSApplication, NSApp # Required for an active run loop in UI applications

def list_identity_authorities():
    """Lists available identity authorities on the system."""
    authorities = CBIdentityAuthority.allAuthorities()
    if authorities:
        print("Available Collaboration Identity Authorities:")
        for authority in authorities:
            print(f"- {authority.displayName()} (Type: {authority.type()})")
            if authority.isLocal():
                print("  (Local Authority)")
            print(f"  Identifier: {authority.identifier()}")
    else:
        print("No Collaboration Identity Authorities found.")

if __name__ == "__main__":
    # For non-UI interactions, a run loop is not strictly necessary but
    # for many PyObjC applications, especially those involving UI,
    # NSApplication.sharedApplication() or an active run loop is needed.
    # Starting a minimal AppKit environment for consistency.
    if not NSApp:
        NSApplication.sharedApplication()

    list_identity_authorities()