{"id":6161,"library":"pyobjc-framework-safariservices","title":"PyObjC SafariServices Framework","description":"pyobjc-framework-safariservices provides Python bindings for Apple's SafariServices.framework on macOS, enabling Python applications to integrate with Safari functionalities like content blockers and shared web credentials. It is part of the larger PyObjC project, which wraps many macOS frameworks. The current version is 12.1, with releases typically aligning with 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","cocoa","bindings","framework","safari","safariservices"],"install":[{"cmd":"pip install pyobjc-framework-safariservices","lang":"bash","label":"Install SafariServices bindings"},{"cmd":"pip install pyobjc","lang":"bash","label":"Install all PyObjC frameworks (recommended)"}],"dependencies":[{"reason":"Provides the core bridge between Python and Objective-C.","package":"pyobjc-core","optional":false}],"imports":[{"note":"Frameworks are typically imported directly after importing `objc` if needed, not usually from AppKit.","wrong":"from AppKit import SafariServices","symbol":"SafariServices","correct":"import SafariServices"}],"quickstart":{"code":"import objc\nfrom Foundation import NSURL\nimport SafariServices\n\n# Get the Python class for SFSafariViewController\n# This class is part of SafariServices.framework\nSFSafariViewController = SafariServices.SFSafariViewController\n\n# Create a sample URL\nurl = NSURL.URLWithString_(\"https://www.example.com\")\n\n# Instantiate SFSafariViewController\n# In a real macOS application, this controller would need to be\n# initialized on the main thread and presented by an NSViewController.\n# For this quickstart, we just demonstrate instantiation.\ntry:\n    controller = SFSafariViewController.alloc().initWithURL_entersReaderIfAvailable_(url, False)\n    print(f\"Successfully created SFSafariViewController instance: {controller}\")\n    # Example of accessing a property (if available and safe outside main thread)\n    # if hasattr(controller, 'URL'):\n    #     print(f\"Controller URL: {controller.URL()}\")\nexcept Exception as e:\n    print(f\"Error instantiating SFSafariViewController (may require main thread/application context): {e}\")\n    print(\"Note: SFSafariViewController typically requires a running Cocoa application and main thread for full functionality.\")\n","lang":"python","description":"This example demonstrates how to import the SafariServices framework and instantiate a basic object like `SFSafariViewController`. In a full macOS application, UI-related objects like `SFSafariViewController` must be created and managed on the main thread within an `NSApplication` context."},"warnings":[{"fix":"Upgrade Python to a supported version for your PyObjC release, or use an older PyObjC version compatible with your Python environment. Always check `requires_python` on PyPI.","message":"PyObjC major versions frequently drop support for older Python versions. For example, v12.0 dropped Python 3.9, and v11.0 dropped Python 3.8. Ensure your Python environment meets the `requires_python` specification for the PyObjC version you are using.","severity":"breaking","affected_versions":"All major versions (e.g., v11.0+, v12.0+)"},{"fix":"Keep PyObjC updated with your macOS version. Check PyObjC release notes for targeted macOS SDK support. For critical applications, pin PyObjC to a version known to work with your specific macOS release.","message":"PyObjC releases are tightly coupled with macOS SDK versions. Upgrading macOS might require upgrading PyObjC to a version that includes updated framework bindings for the new SDK, or vice-versa. Using an incompatible combination can lead to missing symbols or unexpected behavior.","severity":"breaking","affected_versions":"All versions, especially when crossing major macOS updates"},{"fix":"When implementing `init` methods in Python subclasses of Cocoa objects, be aware of the ARC semantics. Ensure proper reference management, especially if porting code from older PyObjC versions or if encountering unexpected deallocations.","message":"PyObjC v11.1 introduced significant changes to how initializer (`init` family) methods handle automatic reference counting (ARC). Previously, PyObjC might not have correctly modeled that `init` methods steal a reference to `self` and return a new reference. This can lead to memory management issues if not handled correctly when implementing custom Cocoa classes in Python.","severity":"gotcha","affected_versions":"v11.1+"},{"fix":"When subclassing Cocoa objects and providing custom `__new__` or `__init__` methods, thoroughly test object lifecycle. Prefer using standard Cocoa initializer patterns where possible. Refer to PyObjC documentation for best practices on subclassing and initialization.","message":"PyObjC's handling of `__init__` and `__new__` for user-defined subclasses of Cocoa objects can be tricky. In v10.3, `__init__` was disabled when a user-defined `__new__` was present, causing breakage. While v10.3.1 re-enabled `__init__` for specific `__new__` scenarios, it highlights a potential footgun when customizing object creation.","severity":"gotcha","affected_versions":"v10.3 - v10.3.1, potentially earlier versions with complex `__new__` implementations."},{"fix":"Regularly check Apple's developer documentation for framework deprecations and removals. Be prepared to update your code to use modern APIs if a framework you rely on becomes unavailable in a newer PyObjC version.","message":"Frameworks can be deprecated or removed by Apple in newer macOS versions. PyObjC will drop bindings for such frameworks when they can no longer be built against the latest SDK (e.g., IMServicePlugIn in v10.0). Code relying on deprecated frameworks may stop working unexpectedly.","severity":"gotcha","affected_versions":"All versions, dependent on macOS updates"}],"env_vars":null,"last_verified":"2026-04-14T00:00:00.000Z","next_check":"2026-07-13T00:00:00.000Z"}