{"id":6091,"library":"pyobjc-framework-corespotlight","title":"PyObjC CoreSpotlight Framework Bindings","description":"PyObjC is a bridge between Python and Objective-C, enabling Python scripts to use and extend existing Objective-C class libraries, most importantly the Cocoa frameworks by Apple. The `pyobjc-framework-corespotlight` package provides Python bindings for the CoreSpotlight framework, allowing Python applications to interact with macOS Spotlight indexing capabilities. The current version is 12.1, with a regular release cadence often aligning with new macOS SDKs and Python versions.","status":"active","version":"12.1","language":"en","source_language":"en","source_url":"https://github.com/ronaldoussoren/pyobjc","tags":["macos","cocoa","objective-c","spotlight","framework","apple"],"install":[{"cmd":"pip install pyobjc-framework-corespotlight","lang":"bash","label":"Install `pyobjc-framework-corespotlight`"},{"cmd":"pip install pyobjc","lang":"bash","label":"Install all PyObjC frameworks (meta-package)"}],"dependencies":[{"reason":"Core bridge functionality for all PyObjC frameworks. Automatically installed with any `pyobjc-framework-*` package.","package":"pyobjc-core","optional":false},{"reason":"Requires Python 3.10 or newer (as of PyObjC 12.x).","package":"Python","optional":false}],"imports":[{"note":"Classes and functions within the CoreSpotlight framework are directly accessible after this import.","symbol":"CoreSpotlight","correct":"import CoreSpotlight"},{"symbol":"CSSearchableItem","correct":"from CoreSpotlight import CSSearchableItem"},{"symbol":"CSSearchableItemAttributeSet","correct":"from CoreSpotlight import CSSearchableItemAttributeSet"}],"quickstart":{"code":"import CoreSpotlight\nfrom Foundation import NSDate\n\ndef index_item(item_id, title, description):\n    # Create an attribute set for the item\n    attribute_set = CoreSpotlight.CSSearchableItemAttributeSet.alloc().initWithItemContentType_('public.text')\n    attribute_set.setTitle_(title)\n    attribute_set.setContentDescription_(description)\n    attribute_set.setKeywords_(['pyobjc', 'spotlight', 'example'])\n    attribute_set.setCreationDate_(NSDate.date())\n\n    # Create the searchable item\n    searchable_item = CoreSpotlight.CSSearchableItem.alloc().initWithUniqueIdentifier_domainIdentifier_attributeSet_(\n        item_id, 'com.example.app.domain', attribute_set\n    )\n\n    # Index the item\n    CoreSpotlight.CSSearchableIndex.defaultSearchableIndex().indexSearchableItems_completionHandler_(\n        [searchable_item], None\n    )\n    print(f\"Indexed item: {title} (ID: {item_id})\")\n\nif __name__ == '__main__':\n    # Example usage\n    index_item(\"my-unique-id-1\", \"My First PyObjC Spotlight Item\", \"This is a test item indexed via PyObjC CoreSpotlight.\")\n    index_item(\"my-unique-id-2\", \"Another Spotlight Entry\", \"This showcases indexing another piece of content.\")","lang":"python","description":"This quickstart demonstrates how to index content using the CoreSpotlight framework through PyObjC. It creates two `CSSearchableItem` instances with basic attributes and adds them to the default Spotlight index."},"warnings":[{"fix":"Upgrade to Python 3.10 or newer, or pin `pyobjc` to `<12.0`.","message":"PyObjC 12.0 dropped support for Python 3.9. Users on Python 3.9 must use PyObjC versions prior to 12.0.","severity":"breaking","affected_versions":">=12.0"},{"fix":"Upgrade to Python 3.9 or newer, or pin `pyobjc` to `<11.0`.","message":"PyObjC 11.0 dropped support for Python 3.8. Users on Python 3.8 must use PyObjC versions prior to 11.0.","severity":"breaking","affected_versions":">=11.0"},{"fix":"Review and update code that manually manages object references or relies on specific `alloc`/`init` reference counting behavior, aligning with ARC conventions.","message":"PyObjC 11.1 aligned with `clang`'s Automatic Reference Counting (ARC) documentation for initializer methods. This changes how PyObjC models `init` family methods, which now correctly steal a reference to `self` and return a new one. Code that made assumptions about reference counting with `alloc`/`init` chains might break.","severity":"breaking","affected_versions":">=11.1"},{"fix":"If experiencing issues with `__init__` and custom `__new__` methods, ensure you are on PyObjC 10.3.1 or newer. For classes using PyObjC's default `__new__`, `__init__` remains unsupported for certain patterns.","message":"PyObjC 10.3 initially removed support for `__init__` when a user-implemented `__new__` was present, which broke some projects. Version 10.3.1 partially reverted this, allowing `__init__` if a user class or its superclass implements `__new__`, but `__init__` is still not supported when relying on PyObjC's provided `__new__`.","severity":"gotcha","affected_versions":"10.3 - 10.3.0"},{"fix":"Exercise caution when using PyObjC with free-threading Python builds. Monitor PyObjC release notes for updates on free-threading stability and full support.","message":"Experimental free-threading support (PEP 703) was introduced in Python 3.13 and integrated into PyObjC 11.0. While present, this was an experimental feature in Python and PyObjC, and might have limitations or stability concerns. PyObjC itself did not fully support the experimental free-threading in Python 3.13 at the time of 10.3 release.","severity":"gotcha","affected_versions":">=11.0 (with Python 3.13)"},{"fix":"Upgrade to PyObjC 10.1 or later to use `os.fspath()` reliably with Cocoa URLs representing local paths. For older versions, manual conversion or checking might be necessary.","message":"Prior to PyObjC 10.1, using `os.fspath()` with Cocoa URLs (NSURL, CFURLRef) that did not refer to local filesystem paths would raise a `TypeError`. This was fixed to enable Python filesystem APIs with local filesystem URLs.","severity":"gotcha","affected_versions":"<10.1"}],"env_vars":null,"last_verified":"2026-04-14T00:00:00.000Z","next_check":"2026-07-13T00:00:00.000Z"}