{"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":"python","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,"search_vec":"'12.1':36 'appl':14,60 'bind':12,56 'c':54 'cadenc':40 'cocoa':55 'current':33 'cycl':50 'enabl':20 'framework':2,7,17 'interact':21 'larger':30 'maco':19,43,51 'object':53 'objective-c':52 'packag':9 'part':27 'project':32 'provid':10 'pyobjc':1,6,31 'pyobjc-framework-symbol':5 'python':11,47 'releas':39 'sdk':44 'sf':23,58 'sf-symbol':57 'support':49 'symbol':3,8,16,24,59 'tie':41 'updat':45 'version':35,48","created_at":"2026-04-14T18:45:32.827918+00:00","updated_at":"2026-04-16T19:33:50.766762+00:00","problems":{"verify_error":"× Failed to build `pyobjc-framework-cocoa==12.2.1`\n  ├─▶ The build backend returned an error\n  ╰─▶ Call to `setuptools.build_meta.build_wheel` failed (exit status: 1)\n\n      [stderr]\n      Traceback (most recent call last):\n        File \"<string>\", line 14, in <module>\n        File\n      \"/home/xor/"},"ecosystem":"pypi","meta_description":null,"install_score":null,"quickstart_score":null,"quickstart_tag":null,"pypi_latest":"12.2","cli_name":"","cli_version":null,"type":"library","homepage":null,"github":"https://github.com/ronaldoussoren/pyobjc","docs":"https://pyobjc.readthedocs.io/en/latest/","changelog":null,"pypi":"https://pypi.org/project/pyobjc-framework-symbols/","npm":null,"openapi_spec":null,"status_page":null,"smithery":null,"categories":["type-stubs"],"base_url":null,"auth_type":null,"provenance":{"verified_status":"install_fail","verified_at":"2026-06-28","last_verified":"2026-06-28","next_check":"2026-07-05","install_tag":null}}