PyObjC AppleScriptObjC Framework

Warnings

• breaking PyObjC frequently drops support for older Python versions. PyObjC 12.0 dropped support for Python 3.9. PyObjC 11.0 dropped support for Python 3.8. Ensure your Python environment meets the `requires_python` spec (>=3.10 for version 12.1) to avoid compatibility issues.
  Fix: Upgrade to a supported Python version (3.10 or later for PyObjC 12.1) or use an older PyObjC version compatible with your Python interpreter.
• breaking The behavior of initializer methods (`init` family) was changed in PyObjC 11.1 to align with Objective-C's Automatic Reference Counting (ARC) semantics. Methods in the 'init' family now correctly steal a reference to `self` and return a new reference. This may affect custom object instantiation patterns, particularly those involving `SomeClass.alloc().init...()`.
  Fix: Review object instantiation logic in your code to ensure it correctly handles ARC semantics. PyObjC 10.4 and later also introduced a more Pythonic instantiation interface, e.g., `SomeClass(arg1=val1)` which is generally recommended.
• gotcha When subclassing Objective-C classes in Python, `__init__` behavior with a custom `__new__` can be tricky. PyObjC 10.3 introduced a regression, partially fixed in 10.3.1. While `__init__` can be used when a class or its superclasses implement a user-defined `__new__`, code relying on PyObjC's automatically provided `__new__` cannot necessarily use `__init__` in the traditional Pythonic way.
  Fix: If implementing `__new__` for Objective-C subclasses, be aware of PyObjC's two-phase instantiation. Consider using Objective-C style `init` methods directly or the Pythonic instantiation interface introduced in PyObjC 10.4. Avoid overriding `__new__` and `__init__` simultaneously without understanding the bridge's mechanics.
• gotcha While PyObjC 11 and later (including 12.x) support Python 3.13+'s experimental free-threading (PEP 703), many underlying Apple frameworks (especially GUI-related ones) are not inherently thread-safe. Concurrent access to mutable Objective-C collections (e.g., `NSMutableArray`) or GUI elements without explicit locking can lead to race conditions or crashes.
  Fix: When using PyObjC with free-threading, implement explicit locking mechanisms (e.g., `threading.Lock`) around any interactions with Objective-C objects or Cocoa APIs that are not documented as thread-safe. Prioritize main-thread interaction for GUI components.
• gotcha PyObjC is a macOS-specific library and does not function on other operating systems like Linux or Windows. Its entire purpose is to bridge Python with Objective-C frameworks available on macOS.
  Fix: Ensure your development and deployment environment is macOS. For cross-platform applications, consider alternative UI toolkits or platform-specific abstraction layers.
• gotcha Installation of PyObjC often requires the Xcode Command Line Tools to be installed, as it relies on system headers and compilers. Missing these tools can lead to compilation errors during `pip install`.
  Fix: Install Xcode Command Line Tools by running `xcode-select --install` in your terminal before attempting to install PyObjC.

Install

• pip install pyobjc-framework-applescriptobjc Install latest version

Imports

• AppleScriptObjC

  import AppleScriptObjC

  PyObjC maps macOS frameworks directly to Python package names.

Quickstart

This quickstart demonstrates how to programmatically attempt to load the AppleScriptObjC framework's bundle using `Foundation.NSBundle`. Due to its specialized nature for extending AppleScript application bundles, a simple, general-purpose functional example is not straightforward without a full application context.

import objc
from Foundation import NSBundle

# The AppleScriptObjC framework is primarily used within AppleScript-based
# application bundles to extend their functionality.
# A direct functional example outside this context is complex.
# This snippet demonstrates how to check if the framework can be loaded.

try:
    # Attempt to get the NSBundle for the AppleScriptObjC framework
    bundle = NSBundle.bundleWithPath_(
        "/System/Library/Frameworks/AppleScriptObjC.framework"
    )

    if bundle and bundle.load():
        print("AppleScriptObjC framework loaded successfully.")
        # At this point, classes and functions from the framework would be available
        # through 'AppleScriptObjC' or through runtime introspection, e.g.,
        # AppleScriptObjC.ASOCScript or similar if defined.
    else:
        print("Failed to load AppleScriptObjC framework or it's not present.")
except Exception as e:
    print(f"An error occurred: {e}")