{"id":6155,"library":"pyobjc-framework-phase","title":"PyObjC Framework: PHASE","description":"`pyobjc-framework-phase` provides Python wrappers for Apple's PHASE (Physical Audio Spatialization Engine) framework on macOS. It is part of the larger PyObjC project, allowing Python applications to interact with Objective-C APIs and leverage native macOS functionalities. The current version is 12.1, with releases typically aligning with macOS SDK updates and Python version support changes.","status":"active","version":"12.1","language":"en","source_language":"en","source_url":"https://github.com/ronaldoussoren/pyobjc","tags":["macOS","audio","bindings","objective-c","cocoa","framework"],"install":[{"cmd":"pip install pyobjc-framework-phase","lang":"bash","label":"Install latest version"}],"dependencies":[{"reason":"Required base for all PyObjC framework bindings.","package":"pyobjc-core"},{"reason":"Provides core macOS types and objects; typically a transitive dependency for most frameworks.","package":"pyobjc-framework-Foundation","optional":true}],"imports":[{"note":"Specific classes from the PHASE framework are imported directly from the 'PHASE' package.","symbol":"PHASEEngine","correct":"from PHASE import PHASEEngine"},{"note":"The core PyObjC bridge is often needed for low-level interactions or type conversions.","symbol":"objc","correct":"import objc"}],"quickstart":{"code":"import objc\nfrom Foundation import NSObject, NSLog\nfrom PHASE import PHASEEngine, PHASE_ENGINE_SOUND_EVENT_TYPE_NONE\n\ndef quick_phase_check():\n    NSLog(\"Attempting to create a PHASEEngine instance...\")\n    try:\n        # PHASEEngine requires an identifier for instantiation\n        engine = PHASEEngine.alloc().initWithIdentifier_(\"MyPythonPHASEEngine\")\n        if engine:\n            NSLog(\"Successfully created PHASEEngine instance: %@\", engine)\n            # A real PHASE application would continue with configuration and playback.\n            # This example only verifies the binding's accessibility.\n        else:\n            NSLog(\"Failed to create PHASEEngine instance.\")\n    except Exception as e:\n        NSLog(\"Error creating PHASEEngine: %@\", str(e))\n\nif __name__ == \"__main__\":\n    quick_phase_check()","lang":"python","description":"This quickstart demonstrates how to import a class from the `PHASE` framework and attempt to instantiate a `PHASEEngine`. While a complete audio application using PHASE is complex, this example verifies that the framework bindings are correctly installed and accessible from Python. Output will appear in the macOS system log (viewable via Console.app) due to `NSLog` usage."},"warnings":[{"fix":"Upgrade to Python 3.10 or later, or pin `pyobjc-framework-phase` to a version less than 12.0 (e.g., `pip install 'pyobjc-framework-phase<12.0'`).","message":"PyObjC 12.0, which includes `pyobjc-framework-phase`, dropped support for Python 3.9. Projects targeting Python 3.9 must use `pyobjc` versions prior to 12.0.","severity":"breaking","affected_versions":">=12.0"},{"fix":"Upgrade to Python 3.9 or later, or pin `pyobjc-framework-phase` to a version less than 11.0 (e.g., `pip install 'pyobjc-framework-phase<11.0'`).","message":"PyObjC 11.0, which includes `pyobjc-framework-phase`, dropped support for Python 3.8. Projects targeting Python 3.8 must use `pyobjc` versions prior to 11.0.","severity":"breaking","affected_versions":">=11.0"},{"fix":"Review any custom Objective-C classes wrapped with PyObjC, especially `init` methods, to ensure they correctly handle reference counting under the new ARC alignment. Most pure Python usage should be unaffected.","message":"From PyObjC 11.1, the core bridge aligns with `clang`'s documentation for Automatic Reference Counting (ARC) in Objective-C initializer methods. Methods in the 'init' family now correctly model stealing a reference to `self` and returning a new one. This might subtly affect custom Objective-C classes exposed to Python or complex memory management if your code relied on older PyObjC reference counting behavior for initializers.","severity":"gotcha","affected_versions":">=11.1"},{"fix":"If bridging Python classes with custom `__new__` implementations, thoroughly test initialization. Avoid using `__init__` when instantiating through PyObjC's default class factory for new Objective-C objects if `__new__` isn't explicitly overridden in Python.","message":"Changes in PyObjC 10.3 and 10.3.1 affect how Python's `__init__` and `__new__` methods interact with bridged Objective-C classes. While 10.3.1 partially reverted 10.3's stricter behavior, if a class or its superclass defines a custom `__new__` in Python, its `__init__` can be called. However, `__init__` cannot be used if relying on the `__new__` provided by PyObjC directly for class instantiation.","severity":"gotcha","affected_versions":">=10.3"}],"env_vars":null,"last_verified":"2026-04-14T00:00:00.000Z","next_check":"2026-07-13T00:00:00.000Z"}