{"id":5812,"library":"pyobjc-framework-systemconfiguration","title":"PyObjC SystemConfiguration Framework","description":"PyObjC provides Python bindings for macOS frameworks. This specific package wraps the SystemConfiguration.framework, allowing Python applications to interact with system network settings, reachability, and other system configuration details. It is actively developed, with version 12.1 being the current stable release, and follows a release cadence tied to macOS SDK updates and Python version support.","status":"active","version":"12.1","language":"en","source_language":"en","source_url":"https://github.com/ronaldoussoren/pyobjc","tags":["macos","objective-c","framework","system","network","configuration","pyobjc"],"install":[{"cmd":"pip install pyobjc-framework-systemconfiguration","lang":"bash","label":"Install latest stable version"}],"dependencies":[{"reason":"Provides the core Python to Objective-C bridge functionality, automatically installed with framework packages.","package":"pyobjc-core"}],"imports":[{"note":"Framework bindings are typically imported directly by their framework name (e.g., `SystemConfiguration`), not as submodules of the `pyobjc-framework-*` package name.","wrong":"from pyobjc_framework_systemconfiguration import SystemConfiguration","symbol":"SystemConfiguration","correct":"import SystemConfiguration"},{"note":"PyObjC wraps the C-level APIs directly, so you typically import the type name itself, not an explicit 'Ref' suffix as might be common in C. The `SCDynamicStore` object directly represents the opaque C type `SCDynamicStoreRef`.","wrong":"from SystemConfiguration import SCDynamicStoreRef","symbol":"SCDynamicStore","correct":"from SystemConfiguration import SCDynamicStore"}],"quickstart":{"code":"import SystemConfiguration\nimport socket\n\ndef is_network_reachable():\n    # Check if network is generally reachable (e.g., Wi-Fi or Ethernet connected)\n    # This is a basic check and doesn't verify internet access.\n\n    # Create a socket address for 0.0.0.0 (any address)\n    zero_address = ('0.0.0.0', 0)\n    target_address = SystemConfiguration.SCNetworkReachabilityCreateWithName(None, zero_address[0])\n\n    if not target_address:\n        print(\"Failed to create reachability reference.\")\n        return False\n\n    # Get the reachability flags\n    # The 'flags' variable will be an NSInteger, which behaves like a Python int\n    is_reachable, flags = SystemConfiguration.SCNetworkReachabilityGetFlags(target_address, None)\n\n    if not is_reachable:\n        return False\n\n    # Define common reachability flags\n    kSCNetworkReachabilityFlagsReachable = 1 << 1 # Network is reachable\n    kSCNetworkReachabilityFlagsConnectionRequired = 1 << 2 # Connection must be established first\n    kSCNetworkReachabilityFlagsTransientConnection = 1 << 3 # Connection will go away, use only for setup\n    kSCNetworkReachabilityFlagsIsWWAN = 1 << 17 # Connection is a WWAN connection\n    kSCNetworkReachabilityFlagsIsDirect = 1 << 4 # Direct connection to the target host\n\n    # Check if the 'Reachable' flag is set and 'ConnectionRequired' is not set\n    if (flags & kSCNetworkReachabilityFlagsReachable) and \\\n       not (flags & kSCNetworkReachabilityFlagsConnectionRequired):\n        return True\n    return False\n\nif __name__ == '__main__':\n    if is_network_reachable():\n        print(\"Network is reachable.\")\n    else:\n        print(\"Network is not reachable (or requires connection).\")","lang":"python","description":"This quickstart demonstrates how to use `SystemConfiguration` to check if the network is generally reachable. It uses `SCNetworkReachabilityCreateWithName` and `SCNetworkReachabilityGetFlags` to query the system's network status. Note that this check primarily indicates local network connectivity, not necessarily internet access. For full functionality, you would often interact with `SCDynamicStore` for more detailed network state."},"warnings":[{"fix":"Upgrade Python to a version supported by the desired PyObjC release (currently >=3.10 for PyObjC 12.1). Check PyPI metadata for exact `requires_python` for specific PyObjC versions.","message":"PyObjC frequently drops support for older Python versions to align with active Python maintenance. Version 12.0 dropped Python 3.9, and version 11.0 dropped Python 3.8. Users must ensure their Python version meets the `requires_python` specification for their target PyObjC version.","severity":"breaking","affected_versions":">=11.0"},{"fix":"Review custom Python `init` methods in PyObjC subclasses to ensure they correctly manage object references, especially if `super().init()` is called. Consult PyObjC documentation on reference counting and initializer methods.","message":"PyObjC 11.1 changed how reference counts are handled for 'init' family methods, aligning with `clang`'s documentation for Automatic Reference Counting. These methods now correctly 'steal' a reference to `self` and return a new one, which might alter behavior for custom `init` implementations in Python subclasses of Objective-C objects.","severity":"breaking","affected_versions":">=11.1"},{"fix":"Ensure you are using PyObjC 10.3.1 or later if you encounter issues with `__init__` not being called in classes where `__new__` is also defined, or avoid relying on `__init__` when PyObjC's default `__new__` is used for Objective-C classes.","message":"Interaction between `__init__` and `__new__` in Python subclasses of Objective-C classes can be tricky. PyObjC 10.3 initially broke `__init__` usage when PyObjC provided the `__new__` method. Version 10.3.1 fixed this, re-enabling `__init__` if `__new__` is user-implemented in the class or a superclass.","severity":"gotcha","affected_versions":"10.3.0"},{"fix":"Be aware of the experimental status. Monitor PyObjC releases and Python developments for updates on free-threading stability. Thoroughly test threaded PyObjC applications on Python 3.13 and newer.","message":"PyObjC 11.0 introduced experimental support for free-threading (PEP 703) in Python 3.13. While this is an exciting development, its experimental nature means users should be cautious and thoroughly test its impact on their applications.","severity":"gotcha","affected_versions":">=11.0 (with Python 3.13+)"},{"fix":"Before upgrading PyObjC, review the release notes for removed bindings and consult Apple's developer documentation to check for API deprecations relevant to your application. Update your code to use modern alternatives.","message":"As macOS evolves, older frameworks and APIs are deprecated and eventually removed. For example, the 'IMServicePlugIn' framework bindings were removed in PyObjC 10.0 because the framework itself was removed in macOS 14.","severity":"breaking","affected_versions":"Varies by framework/API; consult changelogs"},{"fix":"For source installations, ensure Xcode Command Line Tools are installed and up-to-date (`xcode-select --install`). For most users, using binary wheels (`pip install`) is the preferred and simpler method.","message":"When installing `pyobjc` or individual `pyobjc-framework-*` packages, `pip` typically installs pre-built binary wheels. Building from source requires Xcode Command Line Tools with a suitable SDK (often the latest for the current macOS version) to avoid build errors.","severity":"gotcha","affected_versions":"All versions when building from source"}],"env_vars":null,"last_verified":"2026-04-14T00:00:00.000Z","next_check":"2026-07-13T00:00:00.000Z"}