PyObjC GameplayKit

Warnings

• breaking PyObjC 12.0 dropped support for Python 3.9, and PyObjC 11.0 dropped support for Python 3.8. Users upgrading should ensure their Python environment meets the new minimum requirement (currently Python 3.10+).
  Fix: Upgrade to Python 3.10 or newer, or pin pyobjc-framework-gameplaykit to an older version compatible with your Python environment.
• gotcha PyObjC 11.1 changed how initializer methods (like `init`) handle reference counting, aligning with `clang`'s ARC documentation. Methods in the 'init' family now correctly steal a reference to `self` and return a new one. This could subtly affect memory management or object lifecycle in applications directly interacting with low-level Objective-C object creation.
  Fix: Review code that directly calls `alloc().init()` or other `init` family methods, especially if custom memory management or unusual object lifecycles are involved. Most high-level usage should be unaffected.
• gotcha Experimental free-threading support (PEP 703) in Python 3.13 is *not fully stable or supported* in PyObjC 11. While changes were made to enable it, relying on it for production or performance-critical applications is not recommended.
  Fix: Avoid using PyObjC with Python 3.13's experimental free-threading features until explicitly announced as stable. If free-threading is critical, consider using PyObjC 12.x or later with a Python version where free-threading is stable, or use traditional threading models.
• gotcha In PyObjC 10.3, direct calls to `__init__` were restricted when a class used PyObjC's `__new__` implementation. Version 10.3.1 reintroduced the ability to use `__init__` if the user provided their own `__new__` or a superclass did. Code relying on PyObjC's default `__new__` still cannot use `__init__`.
  Fix: If experiencing issues with `__init__` not being called, ensure your class or its superclasses provide a custom `__new__` if you intend to use `__init__`. Otherwise, adapt your object initialization to Objective-C patterns (e.g., using factory methods or designated initializers).
• gotcha The `os.fspath()` function in Python will raise a `TypeError` when used with Cocoa URLs (`NSURL`, `CFURLRef`) that do not refer to local filesystem paths (e.g., web URLs). This change in behavior ensures `os.fspath()` correctly reflects only local filesystem paths.
  Fix: If you need to work with `NSURL` objects that might not represent local filesystem paths, avoid `os.fspath()`. Use `NSURL`'s methods (e.g., `absoluteString()`, `path()`) or convert to a Python string explicitly, verifying it's a local path first if needed.

Install

• pip install pyobjc-framework-gameplaykit Install pyobjc-framework-gameplaykit

Imports

• GameplayKit

  import GameplayKit

• GKRandomSource

  from GameplayKit import GKRandomSource

Quickstart

This quickstart demonstrates how to import and use a basic GameplayKit feature, `GKARC4RandomSource`, to generate random numbers and shuffle arrays. It highlights the `alloc().init()` pattern for Objective-C object instantiation via PyObjC.

import GameplayKit
import objc # For general PyObjC operations, though not explicitly used here beyond object instantiation

# Initialize a basic random number generator from GameplayKit
# The alloc().init() pattern is common for Objective-C object creation
random_source = GameplayKit.GKARC4RandomSource.alloc().init()

# Generate a random integer within a bound (0 to 99)
random_int = random_source.nextIntWithUpperBound_(100)
print(f"Generated random number (0-99): {random_int}")

# Example using a different random distribution
shuffled_array = random_source.arrayByShufflingObjectsInArray_(["apple", "banana", "cherry", "date"])
print(f"Shuffled array: {shuffled_array}")