PyObjC AppleScriptKit

Warnings

• breaking Python 3.9 and earlier are no longer supported by recent PyObjC versions. PyObjC 12.0 dropped support for Python 3.9, and PyObjC 11.0 dropped support for Python 3.8. Ensure your environment meets the `requires_python` spec (currently `>=3.10`).
  Fix: Upgrade to Python 3.10 or newer, or use an older PyObjC version (not recommended).
• breaking PyObjC 11.1 aligned its behavior for initializer methods (e.g., `init` family methods) with `clang`'s Automatic Reference Counting (ARC) documentation. This change affects how references to `self` are handled and returned, potentially altering memory management in custom Objective-C classes implemented in Python.
  Fix: Review custom Objective-C classes implemented in Python, especially `init` methods, for potential changes in reference counting behavior. Consult `clang`'s ARC documentation.
• gotcha PyObjC (and therefore `pyobjc-framework-applescriptkit`) is exclusively for macOS. It relies heavily on macOS-specific Objective-C frameworks and the Cocoa bridge.
  Fix: This library is not portable to other operating systems like Windows or Linux. Use platform-specific solutions for cross-platform applications.
• gotcha PyObjC 11 introduced *experimental* support for free-threading (PEP 703) in Python 3.13. While progress has been made, users attempting to leverage free-threading might still encounter stability issues or unexpected behavior due to the complexity of the Objective-C runtime interacting with Python's new threading model.
  Fix: If encountering issues with free-threading, consider running without `PYTHON_GIL=0` (i.e., with the GIL enabled) or sticking to an older Python version until free-threading support is more mature in PyObjC.
• breaking Older frameworks or bindings may be removed in major releases. For example, PyObjC 10.0 removed the `IMServicePlugIn` bindings as the framework was deprecated in macOS 10.13 and removed in macOS 14. Always check release notes for framework removals when upgrading major versions.
  Fix: Consult the release notes for `pyobjc` and specific framework packages when upgrading major versions to identify removed or deprecated bindings.

Install

• pip install pyobjc-framework-applescriptkit Install the framework

Imports

• AppleScriptKit

  import AppleScriptKit

  Framework symbols are typically imported directly at the top level after installation.
• ASAppleScript

  from AppleScriptKit import ASAppleScript

  Specific classes within the framework can be imported directly if preferred.

Quickstart

This quickstart demonstrates how to initialize and execute a simple AppleScript string using the `AppleScriptKit` framework. It shows the typical pattern of allocating an Objective-C object, calling an initializer, and handling potential errors.

import AppleScriptKit
import Foundation # For common Objective-C types like NSError

# Define a simple AppleScript
script_source = '''
display dialog "Hello from PyObjC AppleScriptKit!"
return "Script executed successfully."
'''

# Create an ASAppleScript instance
# Note: In PyObjC, None is used for 'nil' or 'NULL' in Objective-C
error_ptr = None # We'll pass None and check the returned tuple for errors
script = AppleScriptKit.ASAppleScript.alloc().initWithSource_error_(script_source, error_ptr)

if script:
    # Execute the script
    result, error = script.executeAndReturnError_(error_ptr)
    if error:
        print(f"Error executing script: {error.localizedDescription()}")
    elif result:
        print(f"Script result: {result.stringValue()}")
    else:
        print("Script executed, no result or error reported.")
else:
    print("Failed to initialize ASAppleScript object.")