PyObjC Framework DictionaryServices

Warnings

• deprecated The underlying macOS DictionaryServices framework is deprecated by Apple. The PyPI page for this package recommends using the 'CoreServices' package instead for modern development. While the PyObjC bindings are still maintained, users should be aware of the upstream deprecation.
  Fix: Consider migrating to functionality within the `pyobjc-framework-coreservices` package or other system APIs where applicable.
• breaking PyObjC frequently drops support for older Python versions with major releases. For instance, PyObjC 12.0 dropped support for Python 3.9, and PyObjC 11.0 dropped support for Python 3.8.
  Fix: Ensure your Python environment meets the `requires_python` specification (currently >=3.10) for the PyObjC version you are using. Always check release notes before upgrading PyObjC.
• gotcha Changes in the handling of `__init__` when a class implements `__new__` were introduced in PyObjC 10.3, leading to breaks in some projects. While partially reverted in 10.3.1 to allow `__init__` usage in certain scenarios, this remains a potential issue for custom Objective-C classes in Python.
  Fix: Review PyObjC release notes for 10.3 and 10.3.1 if encountering issues with custom class initialization. In some cases, `__init__` might not be called if `__new__` is handled by PyObjC's internal mechanisms.
• breaking PyObjC 11.1 aligned its behavior for initializer methods (those in the 'init' family) with Clang's Automatic Reference Counting (ARC) documentation. This means PyObjC now correctly models that 'init' methods steal a reference to `self` and return a new reference, which can change reference counting behavior.
  Fix: Code that manually manages Objective-C object references (e.g., calling `retain` or `release` explicitly) around 'init' methods might need adjustment to conform to the new ARC-aligned behavior.
• gotcha Using the DictionaryServices framework on macOS 10.12 with a `python.org` binary has been known to cause interpreter crashes.
  Fix: Avoid using DictionaryServices on macOS 10.12 with `python.org` binaries. Consider using a different Python distribution (e.g., Homebrew) or a newer macOS version if this functionality is critical.
• gotcha Prior to PyObjC 10.1, `os.fspath()` would not work correctly with Cocoa URLs (`NSURL`, `CFURLRef`) that refer to local filesystem paths, raising a `TypeError` for other URLs. This was fixed to enable regular Python filesystem APIs with such URLs.
  Fix: Upgrade to PyObjC 10.1 or later to ensure `os.fspath()` correctly handles Cocoa URLs for local filesystem paths.
• gotcha Instances of `bytearray` can now be used as arguments for functions or selectors expecting a null-terminated C `char` array. This is a behavioral change that might affect existing code relying on previous type handling.
  Fix: Review code passing `bytearray` to C `char` array arguments to ensure the new implicit conversion behavior is as expected.

Install

• pip install pyobjc-framework-dictionaryservices Install latest version

Imports

• DCSCopyTextDefinition

  from CoreServices import DCSCopyTextDefinition

  While 'DictionaryServices' can sometimes be imported directly, the PyObjC documentation states that these bindings are accessed through the 'CoreServices' package.
• CFRange

  from CoreServices import CFRange

  CFRange is a CoreFoundation type often used with DictionaryServices, and is available via 'CoreServices'.

Quickstart

This example demonstrates how to use the macOS DictionaryServices framework via PyObjC to look up the definition of a word. It uses `DCSCopyTextDefinition` which is accessed through the `CoreServices` package.

import Foundation
import CoreServices
import objc

word = "recursive"

# Create a CFStringRef from a Python string
string_ref = Foundation.CFString.stringWithString_(word)

# Define a range covering the entire string
full_range = CoreServices.CFRange(0, len(word))

# Look up the definition using DCSCopyTextDefinition
definition_ref = CoreServices.DCSCopyTextDefinition(string_ref, full_range)

if definition_ref:
    # Convert CFStringRef to Python string and print
    definition = str(definition_ref)
    print(f"Definition of '{word}':\n{definition}")
    # Release the CFStringRef returned by DCSCopyTextDefinition (retained by 'Copy')
    Foundation.CFRelease(definition_ref)
else:
    print(f"No definition found for '{word}'.")

# Release the input CFStringRef
Foundation.CFRelease(string_ref)