{"id":6063,"library":"pyobjc-framework-accessibility","title":"PyObjC Accessibility Framework","description":"The `pyobjc-framework-accessibility` library provides Python wrappers for the macOS Accessibility framework, enabling programmatic interaction with user interface elements and assistive technologies. Currently at version 12.1, it is part of the broader PyObjC project, which typically releases updates in close synchronicity with new macOS versions and Python support cycles.","status":"active","version":"12.1","language":"en","source_language":"en","source_url":"https://github.com/ronaldoussoren/pyobjc","tags":["macos","objective-c","accessibility","gui","automation"],"install":[{"cmd":"pip install pyobjc-framework-accessibility","lang":"bash","label":"Install `pyobjc-framework-accessibility`"}],"dependencies":[{"reason":"Provides the core bridge between Python and Objective-C runtimes.","package":"pyobjc-core"}],"imports":[{"symbol":"Accessibility","correct":"import Accessibility"},{"note":"Commonly used functions can be imported directly for brevity.","symbol":"AXUIElementCreateSystemWide","correct":"from Accessibility import AXUIElementCreateSystemWide"}],"quickstart":{"code":"import Accessibility\nimport AppKit\n\n# IMPORTANT: This code requires granting accessibility permissions to the\n# Python process (e.g., Terminal.app or your IDE) in macOS System Settings >\n# Privacy & Security > Accessibility. Without permissions, most Accessibility\n# functions will fail or return None.\n\ndef get_accessibility_info():\n    # Get the system-wide accessibility element\n    system_wide_element = Accessibility.AXUIElementCreateSystemWide()\n\n    if not system_wide_element:\n        print(\"Could not create system-wide accessibility element. Check permissions.\")\n        return\n\n    print(f\"System-wide element description: {system_wide_element.description()}\")\n\n    # Get the currently focused application\n    workspace = AppKit.NSWorkspace.sharedWorkspace()\n    frontmost_app = workspace.frontmostApplication()\n\n    if frontmost_app:\n        app_name = frontmost_app.localizedName()\n        app_pid = frontmost_app.processIdentifier()\n        print(f\"\\nFrontmost Application: {app_name} (PID: {app_pid})\")\n\n        # Create an accessibility element for the frontmost application\n        app_ax_element = Accessibility.AXUIElementCreateApplication(app_pid)\n\n        if app_ax_element:\n            try:\n                # Attempt to get common attributes\n                role = app_ax_element.attributeForKey_(Accessibility.kAXRoleAttribute)\n                title = app_ax_element.attributeForKey_(Accessibility.kAXTitleAttribute)\n\n                print(f\"  Role: {role if role else 'N/A'}\")\n                print(f\"  Title: {title if title else 'N/A'}\")\n\n            except Exception as e:\n                print(f\"  Error accessing app attributes (permissions?): {e}\")\n        else:\n            print(f\"  Could not create AXUIElement for {app_name}.\")\n    else:\n        print(\"No frontmost application found.\")\n\n# Call the function, ensuring it's wrapped to explain permissions\nprint(\"Attempting to get Accessibility information...\")\nget_accessibility_info()\nprint(\"\\nRemember to grant Accessibility permissions to your Python environment in macOS System Settings > Privacy & Security > Accessibility.\")","lang":"python","description":"This quickstart demonstrates how to obtain the system-wide accessibility element and query basic information about the frontmost application. Running this code requires granting specific Accessibility permissions to your Python process in macOS System Settings."},"warnings":[{"fix":"Ensure your Python environment meets the minimum requirement for your PyObjC version (e.g., Python 3.10+ for PyObjC 12.x).","message":"PyObjC releases frequently drop support for older Python versions to align with CPython's end-of-life cycle. PyObjC 12.0 dropped support for Python 3.9, and PyObjC 11.0 dropped Python 3.8. Always check the `requires_python` metadata for your target PyObjC version.","severity":"breaking","affected_versions":"PyObjC 11.0, 12.0+"},{"fix":"Manually navigate to macOS System Settings > Privacy & Security > Accessibility and add the application or terminal emulator running your Python script to the list of allowed applications.","message":"Accessing macOS Accessibility features programmatically requires explicit user permission. The Python process running your script (e.g., Terminal, VS Code, or a standalone application) must be granted 'Accessibility' access in macOS System Settings > Privacy & Security > Accessibility. Without these permissions, most Accessibility API calls will fail or return `None`.","severity":"gotcha","affected_versions":"All versions"},{"fix":"Carefully review `__new__` and `__init__` implementations when subclassing Objective-C classes, especially for `init` methods, and test thoroughly. Consider explicit Objective-C style initializers if encountering issues.","message":"From PyObjC 10.3 onwards, there were changes to how `__init__` and `__new__` interact when subclassing Objective-C classes. If you implement `__new__` in your Python subclass and *do not* explicitly call `super().__new__`, `__init__` may not be called, or its behavior may be unexpected. Version 10.3.1 partially re-enabled `__init__` for cases where user-defined `__new__` exists.","severity":"gotcha","affected_versions":"PyObjC 10.3+"},{"fix":"Review code interacting with Objective-C initializers, especially if using explicit `release`/`retain` or custom memory management approaches, to ensure compatibility with the updated ARC semantics.","message":"Starting with PyObjC 11.1, the core bridge's behavior for 'init' family methods (initializers) aligns more strictly with `clang`'s Automatic Reference Counting (ARC) documentation. This means `init` methods now correctly model stealing a reference to `self` and returning a new reference. Code relying on previous PyObjC memory management assumptions for initializers may need adjustment.","severity":"gotcha","affected_versions":"PyObjC 11.1+"}],"env_vars":null,"last_verified":"2026-04-14T00:00:00.000Z","next_check":"2026-07-13T00:00:00.000Z"}