PyObjC ApplicationServices Framework

Warnings

• breaking PyObjC frequently drops support for older Python versions. PyObjC 12.0 dropped Python 3.9, and PyObjC 11.0 dropped Python 3.8. Always check the `requires_python` metadata or release notes to ensure compatibility with your Python environment.
  Fix: Ensure your Python environment meets the `requires_python` specification (>=3.10 for PyObjC 12.1) before upgrading PyObjC.
• breaking PyObjC 11.1 aligned its core bridge with `clang`'s Automatic Reference Counting (ARC) documentation for initializer methods. Methods in the 'init' family now correctly steal a reference to `self` and return a new reference. This changed behavior for `[NSObject alloc]` proxies and can affect custom `init` implementations, potentially leading to crashes if old patterns are used.
  Fix: Review custom `init` implementations in Python subclasses of Objective-C objects. PyObjC 10.3 introduced a Pythonic `Class(...)` instantiation pattern that is generally safer.
• gotcha Version 10.3 initially broke `__init__` usage for Python subclasses of Objective-C classes, particularly when a user implemented `__new__` or when relying on PyObjC's `__new__` behavior. This was partially reverted in 10.3.1 to reintroduce `__init__` support when a user implements `__new__`.
  Fix: When subclassing Objective-C classes, implement Objective-C style `init` methods (e.g., `initWithFoo_:`). If overriding `__new__` in a Python subclass, be aware of the interaction with `__init__` and refer to PyObjC documentation on object instantiation.
• gotcha PyObjC 11.0 introduced experimental support for free-threading (PEP 703) with Python 3.13+. While PyObjC protects its own implementation, Apple's frameworks are not necessarily thread-safe (e.g., `NSMutableArray` for concurrent updates, non-atomic properties, GUI classes on non-main threads).
  Fix: Exercise caution and implement explicit locking when accessing or modifying Objective-C objects and Cocoa APIs concurrently from multiple threads, especially with GUI elements or mutable collections.
• gotcha `NSString` and `NSMutableString` are marked as 'final' in PyObjC versions 11.1 and later. Attempting to subclass these in Python will result in crashes due to special handling within PyObjC.
  Fix: Do not subclass `NSString` or `NSMutableString` in Python. If custom string behavior is needed, wrap an existing `NSString` or use Python's built-in string types.
• gotcha Installing PyObjC (especially from source or if binary wheels aren't suitable) requires Xcode or the Command Line Tools to be installed on macOS, including a compatible SDK for the target macOS version.
  Fix: Ensure Xcode or the Command Line Tools are installed via `xcode-select --install` before attempting installation, particularly if encountering compilation errors.

Install

• pip install pyobjc-framework-applicationservices Install specific framework
• pip install 'pyobjc[allbindings]' Install PyObjC with all framework bindings

Imports

• CoreGraphics

  from ApplicationServices import CoreGraphics

  Sub-frameworks bundled under ApplicationServices, such as CoreGraphics, are accessible directly as modules within the ApplicationServices package.
• kCGColorSpaceGenericRGB

  from ApplicationServices import CoreGraphics; colorSpace = CoreGraphics.CGColorSpaceCreateDeviceRGB()

  Constants and functions from sub-frameworks like CoreGraphics are exposed as attributes of their respective modules imported from ApplicationServices.

Quickstart

This quickstart demonstrates how to access a sub-framework (CoreGraphics) within ApplicationServices to retrieve the primary display's bounds. It highlights the direct import pattern and attribute access for framework elements.

import ApplicationServices
import os

def get_display_bounds():
    """
    Retrieves the bounds of the primary display using CoreGraphics
    from ApplicationServices.
    """
    # Access CoreGraphics functions via ApplicationServices.CoreGraphics
    main_display_id = ApplicationServices.CoreGraphics.CGMainDisplayID()
    bounds = ApplicationServices.CoreGraphics.CGDisplayBounds(main_display_id)

    # PyObjC automatically bridges CGRect to a dictionary-like object
    x = bounds.origin.x
    y = bounds.origin.y
    width = bounds.size.width
    height = bounds.size.height

    print(f"Primary display bounds: x={x}, y={y}, width={width}, height={height}")
    return {"x": x, "y": y, "width": width, "height": height}

if __name__ == '__main__':
    # This example does not require an active NSApplication runloop
    # for just getting display bounds.
    display_info = get_display_bounds()
    assert display_info['width'] > 0 and display_info['height'] > 0
    print("Successfully retrieved display information.")