PyObjC OpenDirectory Framework

Warnings

• breaking PyObjC frequently drops support for older Python versions to align with macOS SDKs and Python's own EOL cycle. For instance, PyObjC 12.0 dropped support for Python 3.9, and PyObjC 11.0 dropped Python 3.8.
  Fix: Ensure your Python version is compatible with the PyObjC version you are installing. PyObjC 12.1 requires Python >=3.10. Always check `requires_python` on PyPI or the PyObjC changelog for specific version requirements.
• breaking PyObjC 11.1 introduced a major change in how initializer methods (those in the 'init' family) are modeled, now correctly reflecting that they 'steal' a reference to `self` and return a new one, as per clang's ARC documentation. This affects object lifecycle and reference counting.
  Fix: Review code that interacts with object initialization, especially custom subclasses or factory methods, to ensure correct reference handling. While explicit memory management is rarely needed in Python, understanding the underlying Objective-C semantics is crucial for correct behavior.
• gotcha PyObjC 10.3 introduced a change that temporarily broke the ability to use `__init__` in Python classes when a user-defined `__new__` method was present. This was fixed in 10.3.1.
  Fix: Ensure you are using PyObjC 10.3.1 or later if your Python classes override `__new__` and also define `__init__`.
• gotcha In PyObjC 12.1, support was added to automatically disable Key-Value Observing (KVO) usage for subclasses of `NSProxy` defined in Python. This implies that earlier versions might have exhibited unexpected KVO behavior for such subclasses.
  Fix: If using custom Python subclasses of `NSProxy`, upgrade to PyObjC 12.1 or later to benefit from automatic KVO handling, or be aware of potential KVO interaction issues in older versions.
• gotcha PyObjC 11.0 introduced *experimental* support for free-threading (PEP 703) in Python 3.13, but PyObjC 10.3 explicitly stated it did *not* support experimental free threading in Python 3.13. This can lead to confusion and instability if not carefully managed.
  Fix: When using Python 3.13+ with PyObjC, be aware that free-threading support is experimental. Consult the PyObjC changelog for the latest status and any specific caveats or recommendations regarding thread safety.
• deprecated The "IMServicePlugIn" bindings were removed in PyObjC 10.0. The entire framework was deprecated in macOS 10.13 and removed in macOS 14.
  Fix: Applications relying on `IMServicePlugIn` must update to alternative macOS APIs or ensure they are targeting an older macOS version and PyObjC release that still includes these bindings.

Install

• pip install pyobjc-framework-opendirectory Install pyobjc-framework-opendirectory

Imports

• OpenDirectory

  import OpenDirectory

  The bindings for the OpenDirectory framework are accessed directly through the `OpenDirectory` package.

Quickstart

This quickstart demonstrates how to import the `OpenDirectory` framework and retrieve the default OpenDirectory session on macOS. It then attempts to list the available directory node names, showcasing basic interaction with the framework.

import OpenDirectory

# A simple quickstart for OpenDirectory.
# This demonstrates importing the framework and accessing a default session.
# More complex operations would involve querying specific nodes, users, or groups.

def get_opendirectory_info():
    """
    Retrieves information from the default OpenDirectory session.
    """
    print("Attempting to get default OpenDirectory session...")
    try:
        # Access the shared default session
        session = OpenDirectory.ODSession.defaultSession()
        if session:
            print(f"Successfully obtained default OpenDirectory session: {session}")

            # Example: list all node names
            # ODSession.nodeNamesAndReturnError_ is a common way to get node names.
            # The second argument is for an NSError object, passed as None from Python.
            node_names, error = session.nodeNamesAndReturnError_(None)

            if node_names:
                print(f"Available OpenDirectory nodes: {', '.join(node_names)}")
            elif error:
                print(f"Error listing nodes: {error.localizedDescription()}")
            else:
                print("No OpenDirectory nodes found.")
            return session
        else:
            print("Failed to obtain default OpenDirectory session.")
            return None
    except Exception as e:
        print(f"An error occurred: {e}")
        return None

if __name__ == "__main__":
    get_opendirectory_info()