PyObjC CompositorServices Framework

12.1 · active · verified Wed Apr 15

This library provides Python bindings for the macOS CompositorServices framework, enabling interaction with its Objective-C APIs. CompositorServices is a highly specialized framework used for building custom rendering pipelines for displays connected to Apple silicon. This specific binding is part of the larger PyObjC project, currently at version 12.1, which maintains a regular release cadence with updates corresponding to macOS SDK changes and Python version support.

Warnings

breaking PyObjC 12.0 dropped support for Python 3.9. Ensure your environment uses Python 3.10 or later.
Fix: Upgrade your Python interpreter to 3.10 or newer.
breaking PyObjC 11.0 dropped support for Python 3.8. Users on older PyObjC versions should be aware of this if upgrading.
Fix: Upgrade your Python interpreter to 3.9 or newer (for PyObjC 11.x) or 3.10+ (for PyObjC 12.x).
gotcha The CompositorServices framework and its bindings were newly introduced in PyObjC 12.0, corresponding to the macOS 26 SDK (likely macOS 15+). It will not be available in older PyObjC versions or on macOS versions that do not support CompositorServices.
Fix: Ensure you are using PyObjC 12.0 or later and targeting a sufficiently new macOS SDK.
gotcha PyObjC 11.1 aligned initializer method behavior with Clang's Automatic Reference Counting (ARC) documentation. This means `init` family methods now correctly model stealing a reference to `self` and returning a new one. This might subtly alter memory management behavior compared to previous versions if custom `init` methods were relying on older PyObjC semantics.
Fix: Review custom `init` implementations to ensure they correctly handle reference counting, especially when interacting with `alloc` and `super().init()`.
gotcha Changes in PyObjC 10.3 and 10.3.1 affected the interaction between `__init__` and `__new__` for Python subclasses of Objective-C objects. While 10.3.1 partially restored support for `__init__` when a user implements `__new__`, code relying on PyObjC's default `__new__` still cannot use `__init__`.
Fix: If implementing `__new__` in a Python subclass of an Objective-C object, ensure `__init__` is used cautiously. Consider initializing instance state within `__new__` or a dedicated setup method if you're not overriding `__new__`.
gotcha Experimental free-threading (PEP 703) in Python 3.13 is an experimental feature and was introduced in PyObjC 11.0 with significant internal changes. PyObjC versions like 10.3 explicitly state they do not support this experimental feature, and caution should be exercised when using it with any PyObjC version.
Fix: If working with Python 3.13 and free-threading, consult the latest PyObjC documentation for compatibility and known issues. For stability, consider sticking to standard CPython builds without free-threading.

Install

pip install pyobjc-framework-compositorservices Install latest version

Imports

CSDisplay
```
from CompositorServices import CSDisplay
```
Classes within the CompositorServices framework are typically prefixed with 'CS'.

Quickstart

Due to the highly specialized nature of the CompositorServices framework, a simple 'Hello World' directly using its APIs is not practical. This quickstart demonstrates basic PyObjC object creation and method calling using the general Foundation framework. To use CompositorServices, you would import its specific classes (e.g., `CSDisplayManager`) and interact with them according to Apple's CompositorServices documentation for macOS.

import objc
from Foundation import NSObject, NSBundle

# CompositorServices is a highly specialized framework.
# A simple 'Hello World' for it is not practical without
# deep knowledge of macOS graphics programming.
# This example demonstrates basic PyObjC class instantiation.

class MyPyObjCClass(NSObject):
    def init(self):
        self = super().init()
        if self is None:
            return None
        print("MyPyObjCClass instance initialized!")
        return self

    @objc.python_method
    def say_hello(self):
        print("Hello from PyObjC!")

if __name__ == "__main__":
    # Instantiate a basic PyObjC object
    obj = MyPyObjCClass.alloc().init()
    obj.say_hello()

    # For CompositorServices, you would import and use specific classes like:
    # from CompositorServices import CSDisplayManager
    # manager = CSDisplayManager.sharedManager()
    # ... and interact with its methods according to Apple's documentation.

view raw JSON →