PyObjC OSAKit Framework Wrappers

Warnings

• breaking PyObjC 12.0 (and thus `pyobjc-framework-osakit` 12.0) dropped support for Python 3.9. Ensure your project uses Python 3.10 or newer.
  Fix: Upgrade your Python environment to 3.10 or later.
• breaking PyObjC 11.0 dropped support for Python 3.8. Ensure your project uses Python 3.9 or newer.
  Fix: Upgrade your Python environment to 3.9 or later.
• gotcha Objective-C method selectors with colons (e.g., `someMethod:withArgument:`) are translated to Python methods using underscores (e.g., `someMethod_withArgument_`). Remember to add a trailing underscore for single-argument methods.
  Fix: When calling Objective-C methods, replace colons in the selector with underscores and append an underscore if the original selector ends with one (i.e., takes an argument). Example: `alloc().initWithSource_(source)`.
• gotcha PyObjC 11.1 aligned the core bridge's behavior 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, which might affect reference counting in specific, complex scenarios.
  Fix: Review code that interacts closely with Objective-C object lifecycle, especially `alloc` and `init` methods, to ensure correct reference management under the new ARC model.
• gotcha In PyObjC 10.3, the ability to use `__init__` in Python classes that also implement `__new__` (or inherit from a class that implements it) was temporarily broken, but later reintroduced in 10.3.1. However, classes relying on `PyObjC`'s default `__new__` still cannot use `__init__`.
  Fix: If implementing custom `__new__` methods in PyObjC-bridged classes, be mindful of how `__init__` is called. For classes using PyObjC's `__new__`, `__init__` is generally not supported for object creation.

Install

• pip install pyobjc-framework-osakit Install framework bindings

Imports

• OSAKit

  import OSAKit

  The OSAKit framework bindings are directly imported as a top-level module named `OSAKit`.
• Foundation

  import Foundation

  Often required for basic Objective-C data types like `NSDictionary` used in error handling or other common operations.

Quickstart

This quickstart demonstrates how to use `pyobjc-framework-osakit` to programmatically compile and execute a simple AppleScript. It initializes an `OSAScript` object with source code, attempts to compile it, and if successful, executes it. Error handling follows the common PyObjC pattern using `NSDictionary` to capture Objective-C errors.

import OSAKit
import Foundation
import os

# Source for a simple AppleScript
script_source = """
display dialog "Hello from PyObjC OSAKit!" with title "PyObjC"
return "AppleScript executed successfully."
"""

try:
    # Create an OSAScript instance
    script = OSAKit.OSAScript.alloc().initWithSource_(script_source)

    # Prepare an error dictionary (Objective-C style error handling)
    error = Foundation.NSDictionary.dictionary()

    # Compile the script
    compiled = script.compileAndReturnError_(error)

    if not compiled:
        print(f"Error compiling script: {error}")
    else:
        print("Script compiled successfully.")
        # Execute the script
        result_desc, error_exec = script.executeAndReturnError_(error)
        if error_exec:
            print(f"Error executing script: {error_exec}")
        else:
            # OSADisplayResult is often an NSAppleEventDescriptor, use stringValue() to get Python string
            print(f"Script output: {result_desc.stringValue()}")

except Exception as e:
    print(f"An error occurred: {e}")