Registry /
type-stubs / pyobjc-framework-corespotlight
Install & Compatibility
Where this runs
tested against v? · pip install
Install × environment matrix
Each cell = how many times install + import succeeded across repeated harness runs. Partial = flaky.
glibc = Debian/Ubuntu slim · musl = Alpine Linux
muslpy 3.10–3.940 runs
build_error
glibcpy 3.10–3.940 runs
build_error
Code
Verified usage
Verified import paths — ran on the pinned version, not inferred.
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
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.")
Debug
Known issues
breakingPyObjC 12.0 dropped support for Python 3.9. Users on Python 3.9 must use PyObjC versions prior to 12.0.fixUpgrade to Python 3.10 or newer, or pin `pyobjc` to `<12.0`.
affects: >=12.0
breakingPyObjC 11.0 dropped support for Python 3.8. Users on Python 3.8 must use PyObjC versions prior to 11.0.fixUpgrade to Python 3.9 or newer, or pin `pyobjc` to `<11.0`.
affects: >=11.0
breakingPyObjC 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.fixReview and update code that manually manages object references or relies on specific `alloc`/`init` reference counting behavior, aligning with ARC conventions.
affects: >=11.1
gotchaPyObjC 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__`.fixIf 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.
affects: 10.3 - 10.3.0
gotchaExperimental 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.fixExercise caution when using PyObjC with free-threading Python builds. Monitor PyObjC release notes for updates on free-threading stability and full support.
affects: >=11.0 (with Python 3.13)
gotchaPrior 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.fixUpgrade 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.
affects: <10.1
Upgrade
Version history
12.2latest on PyPI · released May 30, 2026
Audit
Dependencies
pyobjc-corerequiredCore bridge functionality for all PyObjC frameworks. Automatically installed with any `pyobjc-framework-*` package.
PythonrequiredRequires Python 3.10 or newer (as of PyObjC 12.x).