{"id":6118,"library":"pyobjc-framework-intents","title":"PyObjC Intents Framework","description":"PyObjC-framework-intents provides Python wrappers for Apple's Intents framework on macOS, enabling developers to integrate Python applications with system services like Siri and Shortcuts. It is part of the larger PyObjC project, a bridge between Python and Objective-C. The library is actively maintained, with releases often coinciding with new macOS SDK updates to ensure compatibility and introduce new features.","status":"active","version":"12.1","language":"en","source_language":"en","source_url":"https://github.com/ronaldoussoren/pyobjc","tags":["macOS","Objective-C","Cocoa","Intents","Apple","bridge","GUI"],"install":[{"cmd":"pip install pyobjc-framework-intents","lang":"bash","label":"Install latest version"}],"dependencies":[{"reason":"Provides the core bridge between Python and Objective-C, essential for all PyObjC framework wrappers.","package":"pyobjc-core"}],"imports":[{"note":"Framework classes are imported directly from their corresponding Python package, not as top-level modules.","wrong":"import INIntent","symbol":"INIntent","correct":"from Intents import INIntent"}],"quickstart":{"code":"from Intents import INIntent\nfrom Foundation import NSObject\nimport objc\n\n# PyObjC often requires an application context for full functionality.\n# This is a minimal example demonstrating class access.\n\n# Instantiate a basic INIntent object (typically a subclass would be used)\n# Note: Actual use of Intents often involves a complex app setup and definition\n# through Xcode's project capabilities for proper system integration.\n\ntry:\n    # Attempt to create a generic INIntent instance\n    # In a real scenario, you'd subclass INIntent or use a specific IN*Intent class\n    intent = INIntent.alloc().init()\n    print(f\"Successfully created INIntent instance: {intent}\")\n    print(f\"Intent identifier: {intent.identifier()}\")\nexcept objc.nosuchclass_error:\n    print(\"Intents framework classes are not available or Intents is not properly linked.\")\nexcept Exception as e:\n    print(f\"An error occurred: {e}\")\n\n# Example of how to define a simple Python class that could interact with Intents\n# (though direct INIntent subclassing in Python for full functionality might be limited\n# without Xcode-generated intent definitions)\n\nclass MySimpleIntentHandler(NSObject):\n    def init(self):\n        self = super().init()\n        if self is None:\n            return None\n        print(\"MySimpleIntentHandler initialized.\")\n        return self\n\n    @objc.python_method\n    def handleMyCustomIntent_(self, intent):\n        print(f\"Handling custom intent: {intent.identifier()}\")\n        # In a real app, this would process the intent\n        return None # Or return an INIntentResponse\n\n\nif __name__ == '__main__':\n    # This part would usually run within an application main loop (e.g., AppKit.NSApplication.sharedApplication().run())\n    # For a simple script, it demonstrates object creation.\n    handler = MySimpleIntentHandler.alloc().init()\n    # Simulate calling the handler with a basic intent (won't actually do anything useful without a real intent from the system)\n    # For demonstration, we'll create a dummy INIntent\n    dummy_intent = INIntent.alloc().init()\n    dummy_intent.setValue_forKey_(f\"com.example.myintent.{id(dummy_intent)}\", \"identifier\") # Set a dummy identifier\n    handler.handleMyCustomIntent_(dummy_intent)\n","lang":"python","description":"This quickstart demonstrates how to import a class from the `Intents` framework and instantiate a basic `INIntent` object using PyObjC. Full integration with Apple's Intents system (e.g., for Siri or Shortcuts) typically requires defining and configuring intents within an Xcode project and running within an application context. The example also shows a minimal Objective-C class definition pattern in Python."},"warnings":[{"fix":"Upgrade Python to 3.10 or later. For Python 3.9, use PyObjC 11.1; for Python 3.8, use PyObjC 10.3.","message":"PyObjC 12.0 dropped support for Python 3.9, and PyObjC 11.0 dropped support for Python 3.8. PyObjC 12.1 requires Python >=3.10.","severity":"breaking","affected_versions":"<12.1 for Python 3.9, <11.0 for Python 3.8"},{"fix":"Review and update code that explicitly manages object lifetimes or relies on specific reference counting behavior in `init` methods, following ARC principles. Use `SomeClass(...)` or `SomeClass.alloc().init(...)` for object creation instead of patterns that accidentally worked previously.","message":"PyObjC 11.1 introduced significant changes to how initializer methods (`init...`) handle reference counts, aligning with `clang`'s Automatic Reference Counting (ARC) documentation. This means `init` family methods now correctly model stealing a reference to `self` and returning a new one. Code relying on previous behavior regarding partially initialized objects or manual reference counting in initializers may exhibit bugs.","severity":"breaking","affected_versions":">=11.1"},{"fix":"If implementing `__new__`, ensure `__init__` is compatible or carefully manage object initialization. Avoid relying on `__init__` when using PyObjC's default `__new__` mechanism.","message":"PyObjC (v10.3) initially removed support for `__init__` when a class or its superclasses provided a user-defined `__new__` method, causing breaks in existing projects. While v10.3.1 partially restored this for user-implemented `__new__`, code relying on PyObjC's provided `__new__` still cannot use `__init__`.","severity":"gotcha","affected_versions":">=10.3"},{"fix":"Stay updated with macOS changes and PyObjC release notes to anticipate framework deprecations. Adjust your application if a required framework's bindings are removed.","message":"PyObjC may drop support for framework bindings if Apple deprecates or removes the underlying macOS framework. For example, PyObjC 10 removed `IMServicePlugIn` bindings as the framework was deprecated in macOS 10.13 and removed in macOS 14.","severity":"breaking","affected_versions":"All versions (future risk)"},{"fix":"Exercise caution when using PyObjC with free-threading. Thoroughly test thread-safe code and be aware of potential limitations or unsupported thread-unsafe functionalities mentioned in PyObjC documentation.","message":"PyObjC 11.0 introduced experimental support for free-threading (PEP 703) in Python 3.13, requiring significant internal changes. While supported, users should be aware of its experimental nature and potential for concurrency-related issues.","severity":"gotcha","affected_versions":">=11.0 when using Python 3.13+"},{"fix":"Ensure you are running on macOS. Install the latest Xcode Command Line Tools via `xcode-select --install` before attempting source builds. Match your Python version and PyObjC wheel to compatible macOS versions.","message":"PyObjC is exclusively for macOS. Installing from source requires Xcode or the Command Line Tools with the *latest* macOS SDK. Using an older SDK can lead to build errors. Binary wheels also have specific macOS version support depending on the Python version.","severity":"gotcha","affected_versions":"All versions"},{"fix":"Always translate Objective-C selectors by replacing colons with underscores in Python method calls (e.g., `myObject.methodWithArg_otherArg_(arg1, arg2)`).","message":"Objective-C method names (selectors) containing colons (e.g., `doSomething:withSomethingElse:`) are mapped to Python method names with underscores replacing colons (e.g., `doSomething_withSomethingElse_`). Forgetting this convention is a common source of `AttributeError`.","severity":"gotcha","affected_versions":"All versions"}],"env_vars":null,"last_verified":"2026-04-14T00:00:00.000Z","next_check":"2026-07-13T00:00:00.000Z","problems":[]}