{"id":6182,"library":"pyobjc-framework-symbols","title":"PyObjC Framework Symbols","description":"The `pyobjc-framework-symbols` package provides Python bindings for Apple's `Symbols` framework on macOS, enabling interaction with SF Symbols. It is part of the larger PyObjC project, currently at version 12.1, with a release cadence tied to macOS SDK updates and Python version support cycles.","status":"active","version":"12.1","language":"en","source_language":"en","source_url":"https://github.com/ronaldoussoren/pyobjc","tags":["macos","objective-c","cocoa","bindings","sf-symbols","apple"],"install":[{"cmd":"pip install pyobjc-framework-symbols","lang":"bash","label":"Install latest version"}],"dependencies":[{"reason":"This package provides bindings for a specific macOS framework and relies on the core PyObjC bridge for Objective-C integration.","package":"pyobjc"}],"imports":[{"note":"The `Symbols` framework provides access to SF Symbols functionality, typically requiring macOS 11.0 or later.","symbol":"SFSymbolsLibrary","correct":"from Symbols import SFSymbolsLibrary"},{"note":"Used for configuring the appearance of SF Symbols.","symbol":"SFSymbolConfiguration","correct":"from Symbols import SFSymbolConfiguration"}],"quickstart":{"code":"import objc\nfrom Symbols import SFSymbolsLibrary, SFSymbolConfiguration\n\n# Ensure PyObjC runtime is initialized (often implicit with framework imports)\n# if not objc.isInitialized():\n#    objc.initFrameworkWrapper(\"Foundation\")\n\ntry:\n    # Get the shared library of SF Symbols\n    shared_library = SFSymbolsLibrary.sharedLibrary()\n\n    if shared_library:\n        print(\"Successfully accessed SFSymbolsLibrary.\")\n        \n        # List a few symbol names\n        all_symbol_names = shared_library.allSymbolNames()\n        if all_symbol_names:\n            print(f\"Found {len(all_symbol_names)} SF Symbols.\")\n            print(f\"First 5 symbols: {list(all_symbol_names)[:5]}\")\n\n            # Example: Create a symbol configuration (requires macOS 11.0+ typically)\n            config = SFSymbolConfiguration.configurationWithPointSize_weight_scale_(\n                24,  # Point size\n                3,   # SFSymbolWeightSemibold (use integer for simplicity in quickstart)\n                2    # SFSymbolScaleMedium (use integer for simplicity in quickstart)\n            )\n            print(f\"Created SFSymbolConfiguration: {config}\")\n        else:\n            print(\"No symbol names found in library.\")\n    else:\n        print(\"SFSymbolsLibrary.sharedLibrary() returned None.\")\nexcept Exception as e:\n    print(f\"An error occurred: {e}\")\n    print(\"Please ensure you are running on macOS 11.0+ and PyObjC is correctly installed.\")\n","lang":"python","description":"This quickstart demonstrates how to access the `SFSymbolsLibrary` and create an `SFSymbolConfiguration` object using the `pyobjc-framework-symbols` bindings. This functionality is generally available on macOS 11.0 and newer."},"warnings":[{"fix":"Upgrade to a supported Python version (currently 3.10+ for PyObjC 12.x). Pin PyObjC version if an older Python is required.","message":"PyObjC frequently drops support for older Python versions. Version 12.0 dropped support for Python 3.9, and version 11.0 dropped Python 3.8. Always check the release notes for Python compatibility.","severity":"breaking","affected_versions":"11.0, 12.0"},{"fix":"Review custom Objective-C object initialization patterns in Python subclasses, especially those involving `alloc` and `init` methods, to ensure correct reference counting and object lifecycle management.","message":"In PyObjC 11.1, the core bridge's behavior for initializer methods changed to align with `clang`'s documentation for Automatic Reference Counting (ARC). Methods in the 'init' family now correctly steal a reference to `self` and return a new reference, which can affect custom object initialization logic.","severity":"breaking","affected_versions":"11.1+"},{"fix":"Develop and test PyObjC applications on the target macOS version(s). Be mindful of API availability across different macOS releases. `pyobjc-framework-symbols` specifically targets the `Symbols` framework introduced in macOS 11.0.","message":"PyObjC framework bindings are tightly coupled to macOS SDK versions. Running code built with a newer SDK on an older macOS version, or attempting to use features not present in the runtime OS, can lead to runtime errors (e.g., missing symbols, unexpected behavior).","severity":"gotcha","affected_versions":"All"},{"fix":"If implementing custom Objective-C classes in Python, ensure your `__new__` and `__init__` methods adhere to PyObjC's object lifecycle rules, typically by performing initialization in `__new__` or using ObjC-style initialization methods rather than Python's `__init__` directly.","message":"PyObjC 10.3 introduced a change that prevented calling `__init__` when a user-implemented `__new__` was present, leading to breakage. This was partially reverted in 10.3.1 to reintroduce `__init__` support when `__new__` is user-defined, but code relying on PyObjC's default `__new__` still cannot use `__init__`.","severity":"gotcha","affected_versions":"10.3, 10.3.1"},{"fix":"Always check release notes for framework removals if using less common or deprecated macOS APIs. Plan for updates when targeting new macOS versions.","message":"Specific framework bindings can be removed in major versions. For example, `IMServicePlugIn` bindings were entirely removed in PyObjC 10.0 because the framework itself was deprecated and removed in macOS.","severity":"deprecated","affected_versions":"10.0+"}],"env_vars":null,"last_verified":"2026-04-14T00:00:00.000Z","next_check":"2026-07-13T00:00:00.000Z","problems":[]}