Rubicon-ObjC

Warnings

• breaking Python 3.9 support was dropped in `rubicon-objc` v0.5.3. Ensure your environment uses Python 3.10 or newer.
  Fix: Upgrade your Python environment to 3.10 or higher, or pin `rubicon-objc<0.5.3`.
• breaking Starting with Python 3.14, custom `asyncio` event loop policies were deprecated. `rubicon-objc` v0.5.1 introduced `RubiconEventLoop()` as the preferred way to integrate with asyncio, replacing the older `EventLoopPolicy` mechanism.
  Fix: Instead of `asyncio.set_event_loop_policy(EventLoopPolicy())` and `asyncio.new_event_loop()`, directly instantiate and use `loop = RubiconEventLoop()` for your event loop. This change is backward compatible for older Python versions too.
• gotcha Objective-C method selectors containing colons (`:`) are translated into Python method names using either underscores (`_`) or keyword arguments. For example, `+URLWithString:relativeToURL:` can be called as `URLWithString_relativeToURL_('...', relativeToURL=...)` or sometimes `URLWithString('...', relativeToURL='...')` depending on the method signature. The keyword argument style is generally more Pythonic.
  Fix: Familiarize yourself with `rubicon-objc`'s selector translation rules. When in doubt, check the method signature in Objective-C documentation and experiment with both `_` and keyword argument styles.
• gotcha In environments where the Objective-C runtime persists (e.g., Pythonista, or repeatedly running scripts in a long-lived process), redefining an Objective-C class with the same name will cause an error. To mitigate this, set `ObjCClass.auto_rename = True` globally or pass `auto_rename=True` when defining your `ObjCClass` subclasses. This appends a unique suffix to the class name in the runtime.
  Fix: Add `ObjCClass.auto_rename = True` at the top of your script or pass `auto_rename=True` as a keyword argument when defining Objective-C classes in Python.
• deprecated Prior to v0.5.0, developers often needed to manually manage memory of Objective-C objects using `retain`, `release`, or `autorelease` calls from Python. Since v0.5.0, `rubicon-objc` automatically retains Objective-C objects when wrapped and autoreleases them on Python garbage collection, greatly simplifying memory management.
  Fix: Upgrade to `rubicon-objc` v0.5.0 or newer to benefit from automatic memory management. If on older versions, ensure correct manual retain/release calls, especially for objects returned by methods starting with 'alloc', 'new', 'copy', or 'mutableCopy'.
• gotcha While Rubicon-ObjC automatically converts basic Python types (like `str` to `NSString`, `bytes` to `NSData`) when passed as arguments, conversion of Objective-C return types back to native Python types (e.g., `NSString` to `str`) is not always automatic. You might need to explicitly use `py_from_ns()` for full Pythonic object conversion.
  Fix: For explicit conversion of Objective-C return values to their Python equivalents, use `rubicon.objc.api.py_from_ns(obj)`.

Install

• pip install rubicon-objc Install latest version

Imports

• ObjCClass

  from rubicon.objc import ObjCClass

  The primary class for wrapping existing Objective-C classes by name.
• NSObject

  from rubicon.objc import NSObject

  A common base class for defining new Objective-C classes in Python.
• ObjCBlock

  from rubicon.objc import ObjCBlock

  Used for explicitly working with Objective-C blocks (closures).
• RubiconEventLoop

  from rubicon.objc import RubiconEventLoop

  Python 3.14 deprecated custom event loop policies. Instantiate `RubiconEventLoop()` directly instead of installing `EventLoopPolicy` or calling `asyncio.new_event_loop()` after setting a policy. This is the recommended approach for all Python versions since `rubicon-objc` v0.5.1.
• objc_id

  from rubicon.objc import objc_id

  Since v0.4.7, `objc_id` and `objc_block` are exposed directly under `rubicon.objc` namespace.

Quickstart

This quickstart demonstrates how to access existing Objective-C classes like `NSURL`, create instances, call methods using Pythonic syntax (handling Objective-C selectors with colons), and access properties. It also shows how to define a new Objective-C class in Python by subclassing `NSObject`, including important considerations for interactive development environments regarding class redefinition.

from rubicon.objc import ObjCClass, NSObject
import asyncio

# Access an Objective-C class (e.g., NSURL from Foundation framework)
NSURL = ObjCClass("NSURL")

# Create an instance using a static constructor method.
# Objective-C methods with ':' are mapped to Python keyword arguments or replaced with '_' in method name.
# E.g., Objective-C's +URLWithString: becomes .URLWithString_() or .URLWithString(url_string).
base_url = NSURL.URLWithString_("https://beeware.org/")
print(f"Base URL: {base_url}")

# Call another method with multiple arguments using keyword arguments
full_url = NSURL.URLWithString_relativeToURL_("contributing/", relativeToURL=base_url)
print(f"Full URL: {full_url}")

# Access Objective-C properties using Python attribute syntax
print(f"Full URL scheme: {full_url.scheme}")

# --- Defining a new Objective-C class in Python ---
# In interactive environments (like Pythonista) or when re-running code, 
# Objective-C class redefinition can cause errors. auto_rename avoids this.
ObjCClass.auto_rename = True # Set globally or pass auto_rename=True to ObjCClass() constructor

class MyPythonDelegate(NSObject):
    # Initialize the Objective-C object. Must call super().init()
    def init(self):
        self = super().init()
        if self:
            print("MyPythonDelegate initialized!")
        return self

    # Define an Objective-C method (e.g., a delegate callback)
    # Argument types should generally be annotated for clarity and correctness.
    def myDelegateMethod_withValue_(self, sender: 'id', value: int):
        print(f"Delegate method called by {sender} with value: {value}")
        return None # Objective-C methods often return `void` or `id` (None for Python)

# Instantiate the Python-defined Objective-C class
delegate_instance = MyPythonDelegate.alloc().init()

# Example of calling its method (simulating an Objective-C call)
delegate_instance.myDelegateMethod_withValue_(NSObject.alloc().init(), 42)