PyObjC CoreSpotlight Framework Bindings

Warnings

• breaking PyObjC 12.0 dropped support for Python 3.9. Users on Python 3.9 must use PyObjC versions prior to 12.0.
  Fix: Upgrade to Python 3.10 or newer, or pin `pyobjc` to `<12.0`.
• breaking PyObjC 11.0 dropped support for Python 3.8. Users on Python 3.8 must use PyObjC versions prior to 11.0.
  Fix: Upgrade to Python 3.9 or newer, or pin `pyobjc` to `<11.0`.
• breaking 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.
  Fix: Review and update code that manually manages object references or relies on specific `alloc`/`init` reference counting behavior, aligning with ARC conventions.
• gotcha 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__`.
  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.
• gotcha 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.
  Fix: Exercise caution when using PyObjC with free-threading Python builds. Monitor PyObjC release notes for updates on free-threading stability and full support.
• gotcha 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.
  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.

Install

• pip install pyobjc-framework-corespotlight Install `pyobjc-framework-corespotlight`
• pip install pyobjc Install all PyObjC frameworks (meta-package)

Imports

• CoreSpotlight

  import CoreSpotlight

  Classes and functions within the CoreSpotlight framework are directly accessible after this import.
• CSSearchableItem

  from CoreSpotlight import CSSearchableItem

• CSSearchableItemAttributeSet

  from CoreSpotlight import CSSearchableItemAttributeSet

Quickstart

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.

import CoreSpotlight
from Foundation import NSDate

def index_item(item_id, title, description):
    # Create an attribute set for the item
    attribute_set = CoreSpotlight.CSSearchableItemAttributeSet.alloc().initWithItemContentType_('public.text')
    attribute_set.setTitle_(title)
    attribute_set.setContentDescription_(description)
    attribute_set.setKeywords_(['pyobjc', 'spotlight', 'example'])
    attribute_set.setCreationDate_(NSDate.date())

    # Create the searchable item
    searchable_item = CoreSpotlight.CSSearchableItem.alloc().initWithUniqueIdentifier_domainIdentifier_attributeSet_(
        item_id, 'com.example.app.domain', attribute_set
    )

    # Index the item
    CoreSpotlight.CSSearchableIndex.defaultSearchableIndex().indexSearchableItems_completionHandler_(
        [searchable_item], None
    )
    print(f"Indexed item: {title} (ID: {item_id})")

if __name__ == '__main__':
    # Example usage
    index_item("my-unique-id-1", "My First PyObjC Spotlight Item", "This is a test item indexed via PyObjC CoreSpotlight.")
    index_item("my-unique-id-2", "Another Spotlight Entry", "This showcases indexing another piece of content.")