PyObjC Framework Symbols

Warnings

• breaking 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.
  Fix: Upgrade to a supported Python version (currently 3.10+ for PyObjC 12.x). Pin PyObjC version if an older Python is required.
• breaking 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.
  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.
• gotcha 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).
  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.
• gotcha 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__`.
  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.
• deprecated 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.
  Fix: Always check release notes for framework removals if using less common or deprecated macOS APIs. Plan for updates when targeting new macOS versions.

Install

• pip install pyobjc-framework-symbols Install latest version

Imports

• SFSymbolsLibrary

  from Symbols import SFSymbolsLibrary

  The `Symbols` framework provides access to SF Symbols functionality, typically requiring macOS 11.0 or later.
• SFSymbolConfiguration

  from Symbols import SFSymbolConfiguration

  Used for configuring the appearance of SF Symbols.

Quickstart

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.

import objc
from Symbols import SFSymbolsLibrary, SFSymbolConfiguration

# Ensure PyObjC runtime is initialized (often implicit with framework imports)
# if not objc.isInitialized():
#    objc.initFrameworkWrapper("Foundation")

try:
    # Get the shared library of SF Symbols
    shared_library = SFSymbolsLibrary.sharedLibrary()

    if shared_library:
        print("Successfully accessed SFSymbolsLibrary.")
        
        # List a few symbol names
        all_symbol_names = shared_library.allSymbolNames()
        if all_symbol_names:
            print(f"Found {len(all_symbol_names)} SF Symbols.")
            print(f"First 5 symbols: {list(all_symbol_names)[:5]}")

            # Example: Create a symbol configuration (requires macOS 11.0+ typically)
            config = SFSymbolConfiguration.configurationWithPointSize_weight_scale_(
                24,  # Point size
                3,   # SFSymbolWeightSemibold (use integer for simplicity in quickstart)
                2    # SFSymbolScaleMedium (use integer for simplicity in quickstart)
            )
            print(f"Created SFSymbolConfiguration: {config}")
        else:
            print("No symbol names found in library.")
    else:
        print("SFSymbolsLibrary.sharedLibrary() returned None.")
except Exception as e:
    print(f"An error occurred: {e}")
    print("Please ensure you are running on macOS 11.0+ and PyObjC is correctly installed.")