PyObjC SystemConfiguration Framework

Warnings

• breaking 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.
  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.
• breaking 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.
  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.
• gotcha 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.
  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.
• gotcha 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.
  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.
• breaking 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.
  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.
• gotcha 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.
  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.

Install

• pip install pyobjc-framework-systemconfiguration Install latest stable version

Imports

• SystemConfiguration

  import SystemConfiguration

  Framework bindings are typically imported directly by their framework name (e.g., `SystemConfiguration`), not as submodules of the `pyobjc-framework-*` package name.
• SCDynamicStore

  from SystemConfiguration import SCDynamicStore

  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`.

Quickstart

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.

import SystemConfiguration
import socket

def is_network_reachable():
    # Check if network is generally reachable (e.g., Wi-Fi or Ethernet connected)
    # This is a basic check and doesn't verify internet access.

    # Create a socket address for 0.0.0.0 (any address)
    zero_address = ('0.0.0.0', 0)
    target_address = SystemConfiguration.SCNetworkReachabilityCreateWithName(None, zero_address[0])

    if not target_address:
        print("Failed to create reachability reference.")
        return False

    # Get the reachability flags
    # The 'flags' variable will be an NSInteger, which behaves like a Python int
    is_reachable, flags = SystemConfiguration.SCNetworkReachabilityGetFlags(target_address, None)

    if not is_reachable:
        return False

    # Define common reachability flags
    kSCNetworkReachabilityFlagsReachable = 1 << 1 # Network is reachable
    kSCNetworkReachabilityFlagsConnectionRequired = 1 << 2 # Connection must be established first
    kSCNetworkReachabilityFlagsTransientConnection = 1 << 3 # Connection will go away, use only for setup
    kSCNetworkReachabilityFlagsIsWWAN = 1 << 17 # Connection is a WWAN connection
    kSCNetworkReachabilityFlagsIsDirect = 1 << 4 # Direct connection to the target host

    # Check if the 'Reachable' flag is set and 'ConnectionRequired' is not set
    if (flags & kSCNetworkReachabilityFlagsReachable) and \
       not (flags & kSCNetworkReachabilityFlagsConnectionRequired):
        return True
    return False

if __name__ == '__main__':
    if is_network_reachable():
        print("Network is reachable.")
    else:
        print("Network is not reachable (or requires connection).")