{"id":6096,"library":"pyobjc-framework-dictionaryservices","title":"PyObjC Framework DictionaryServices","description":"pyobjc-framework-dictionaryservices provides Python wrappers for the macOS DictionaryServices framework, enabling Python applications to interact with the system's dictionary and thesaurus. It is part of the larger PyObjC project, which actively maintains bindings for various macOS frameworks, with releases typically tied to new macOS SDKs and Python version support. The current version is 12.1.","status":"active","version":"12.1","language":"en","source_language":"en","source_url":"https://github.com/ronaldoussoren/pyobjc","tags":["macos","pyobjc","framework","dictionary","apple","coreservices"],"install":[{"cmd":"pip install pyobjc-framework-dictionaryservices","lang":"bash","label":"Install latest version"}],"dependencies":[{"reason":"Provides the core bridge between Python and Objective-C, required by all PyObjC framework bindings.","package":"pyobjc-core"},{"reason":"The DictionaryServices framework bindings are primarily accessed through the CoreServices package, and the underlying framework is suggested to be used via CoreServices.","package":"pyobjc-framework-coreservices","optional":false}],"imports":[{"note":"While 'DictionaryServices' can sometimes be imported directly, the PyObjC documentation states that these bindings are accessed through the 'CoreServices' package.","wrong":"from DictionaryServices import DCSCopyTextDefinition","symbol":"DCSCopyTextDefinition","correct":"from CoreServices import DCSCopyTextDefinition"},{"note":"CFRange is a CoreFoundation type often used with DictionaryServices, and is available via 'CoreServices'.","wrong":"from DictionaryServices import CFRange","symbol":"CFRange","correct":"from CoreServices import CFRange"}],"quickstart":{"code":"import Foundation\nimport CoreServices\nimport objc\n\nword = \"recursive\"\n\n# Create a CFStringRef from a Python string\nstring_ref = Foundation.CFString.stringWithString_(word)\n\n# Define a range covering the entire string\nfull_range = CoreServices.CFRange(0, len(word))\n\n# Look up the definition using DCSCopyTextDefinition\ndefinition_ref = CoreServices.DCSCopyTextDefinition(string_ref, full_range)\n\nif definition_ref:\n    # Convert CFStringRef to Python string and print\n    definition = str(definition_ref)\n    print(f\"Definition of '{word}':\\n{definition}\")\n    # Release the CFStringRef returned by DCSCopyTextDefinition (retained by 'Copy')\n    Foundation.CFRelease(definition_ref)\nelse:\n    print(f\"No definition found for '{word}'.\")\n\n# Release the input CFStringRef\nFoundation.CFRelease(string_ref)","lang":"python","description":"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."},"warnings":[{"fix":"Consider migrating to functionality within the `pyobjc-framework-coreservices` package or other system APIs where applicable.","message":"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.","severity":"deprecated","affected_versions":"All versions (upstream Apple deprecation)"},{"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.","message":"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.","severity":"breaking","affected_versions":"11.0+"},{"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.","message":"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.","severity":"gotcha","affected_versions":"10.3, 10.3.1"},{"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.","message":"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.","severity":"breaking","affected_versions":"11.1+"},{"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.","message":"Using the DictionaryServices framework on macOS 10.12 with a `python.org` binary has been known to cause interpreter crashes.","severity":"gotcha","affected_versions":"macOS 10.12 (with python.org binaries)"},{"fix":"Upgrade to PyObjC 10.1 or later to ensure `os.fspath()` correctly handles Cocoa URLs for local filesystem paths.","message":"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.","severity":"gotcha","affected_versions":"<10.1"},{"fix":"Review code passing `bytearray` to C `char` array arguments to ensure the new implicit conversion behavior is as expected.","message":"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.","severity":"gotcha","affected_versions":"12.1+"}],"env_vars":null,"last_verified":"2026-04-14T00:00:00.000Z","next_check":"2026-07-13T00:00:00.000Z"}