PyObjC Framework SearchKit

Warnings

• breaking PyObjC v12.0 dropped support for Python 3.9. Prior to that, v11.0 dropped support for Python 3.8. Users should ensure their Python version meets the `requires_python` specification (currently `>=3.10`).
  Fix: Upgrade Python to a supported version (e.g., Python 3.10 or newer).
• deprecated The separate framework wrappers for `DictionaryServices`, `LaunchServices`, and `SearchKit` are deprecated. While `pyobjc-framework-searchkit` still exists, it is now effectively an alias for the `CoreServices` bindings. Users are encouraged to transition to using the `CoreServices` bindings directly, as they may expose more symbols and represent the current recommended approach.
  Fix: Consider importing from `CoreServices` instead of `SearchKit` for future compatibility, e.g., `from CoreServices import SKIndex`.
• gotcha Behavior of initializer methods changed in PyObjC v11.1 to align with `clang`'s Automatic Reference Counting (ARC) documentation. Methods in the 'init' family now correctly model that they steal a reference to `self` and return a new reference. This might affect custom Objective-C subclassing or complex object lifecycle management.
  Fix: Review custom Objective-C subclassing logic, especially `init` methods, for correct reference handling according to ARC guidelines. PyObjC's documentation on 'Two-phase instantiation' is relevant here.
• gotcha Changes in PyObjC v10.3 regarding the calling of `__init__` when a user implements `__new__` for Objective-C subclasses caused issues for several projects, leading to a partial reintroduction of the old behavior in v10.3.1. Code relying on custom `__new__` implementations in Objective-C subclasses might still encounter unexpected behavior if not carefully managed.
  Fix: If subclassing Objective-C classes in Python with custom `__new__` methods, be aware of `__init__` call restrictions. Refer to PyObjC documentation on 'Two-phase instantiation' for best practices.
• gotcha When working with `NSURL` objects that represent file system paths, `os.fspath(someURL)` can be used to convert them to Python filesystem paths. However, this will raise a `TypeError` if the `NSURL` does not refer to a local filesystem path.
  Fix: Always check if an `NSURL` represents a local file path before using `os.fspath()`. For non-local URLs, use other `NSURL` methods to extract components.

Install

• pip install pyobjc-framework-searchkit Install specific framework
• pip install pyobjc Install all PyObjC frameworks (including SearchKit)

Imports

• SearchKit

  from SearchKit import SKIndex, SKSearch

  Individual classes like SKIndex and SKSearch are accessed directly from the SearchKit module.
• Foundation (or Cocoa)

  from Foundation import NSURL

  NSURL from Foundation (or Cocoa) is often used for file paths with SearchKit.

Quickstart

This quickstart demonstrates how to create a basic SearchKit index in a temporary directory, add text documents, and then perform a simple query to retrieve matching documents and their relevance scores. It highlights the use of `NSURL` for path handling, the `alloc().init...` pattern for object instantiation, and basic `SKIndex` and `SKSearch` operations. Ensure you have the `Foundation` framework available (it's part of `pyobjc-framework-cocoa` or the `pyobjc` meta-package).

import os
import tempfile
import shutil
from Foundation import NSURL
from SearchKit import SKIndex, SKDocument, SKSearch, SKSearchGroup, kSKSearchOptionFindSimilar, kSKSearchOptionNone

# Create a temporary directory for the index
temp_dir = tempfile.mkdtemp()
index_path = os.path.join(temp_dir, "MySearchIndex")

print(f"Creating SearchKit index at: {index_path}")

# 1. Create an SKIndex
# Convert Python path to NSURL
index_url = NSURL.fileURLWithPath_(index_path)

# Create a new index (kSKIndexTypeInverted or kSKIndexTypeVector)
# For simplicity, using kSKIndexTypeInverted here
index = SKIndex.alloc().initForURL_create_dictionary_(
    index_url,
    True,
    None # No special options dictionary
)

if not index:
    print("Failed to create SearchKit index.")
    shutil.rmtree(temp_dir)
    exit()

# 2. Add documents to the index
doc_id_counter = 0
def add_document(content, filename):
    global doc_id_counter
    doc_id_counter += 1
    doc_name = f"doc_{doc_id_counter}"
    # Create an SKDocument from content string
    document = SKDocument.alloc().initWithURL_mimeType_textEncoding_(
        NSURL.fileURLWithPath_(filename), # URL identifies the document, can be dummy
        None, # MIME type, can be None
        None  # Text encoding, can be None
    )
    if document:
        index.addDocumentWithText_url_properties_(document, content, None, None)
        print(f"Added '{filename}' to index.")
    else:
        print(f"Failed to create SKDocument for {filename}")

add_document("The quick brown fox jumps over the lazy dog.", "file1.txt")
add_document("Lazy dogs often sleep deeply.", "file2.txt")
add_document("A quick jump is good exercise.", "file3.txt")

index.flush()
index.close()

# 3. Perform a search
search_index = SKIndex.alloc().initForURL_create_dictionary_(index_url, False, None)
if not search_index:
    print("Failed to open SearchKit index for searching.")
    shutil.rmtree(temp_dir)
    exit()

search_query = "quick dog"
print(f"\nSearching for: '{search_query}'")

search = SKSearch.alloc().initWithIndex_(
    search_index
)

if search:
    search_options = kSKSearchOptionNone
    search_group = SKSearchGroup.alloc().init()
    # You can specify the maximum number of results
    results = search.findMatchesForQuery_maxCount_(
        search_query,
        10 # Max 10 results
    )

    if results:
        for i, doc_ref in enumerate(results.objectAtIndex_(0)):
            score = results.objectAtIndex_(1)[i]
            # Get original document URL (which we used as a dummy path)
            doc_url = search_index.documentPropertiesForDocumentRef_(doc_ref).objectForKey_("kSKDocumentURL").path()
            print(f"  Match: {doc_url} (Score: {score:.2f})")
    else:
        print("  No matches found.")
else:
    print("Failed to create SKSearch object.")

search_index.close()

# 4. Clean up
shutil.rmtree(temp_dir)
print(f"\nCleaned up temporary index directory: {temp_dir}")