PySide6.QtNetwork.QNetworkInformation¶

class QNetworkInformation¶

QNetworkInformation exposes various network information through native backends.

Details

Warning

This section contains snippets that were automatically translated from C++ to Python and may contain errors.

QNetworkInformation provides a cross-platform interface to network-related information through plugins.

Various plugins can have various functionality supported, and so you can load plugins based on which features are needed.

In most cases, the recommended approach is to load the platform-specific backend by calling loadDefaultBackend() . This will automatically select the most appropriate backend available on the current platform and is suitable for the majority of applications.

from PySide6.QtCore import QCoreApplication


def onReachabilityChanged(reachability):

    if reachability == QNetworkInformation.Reachability.Unknown:
        print("Network reachability is unknown.")
        break
    elif reachability == QNetworkInformation.Reachability.Disconnected:
        print("Network is disconnected.")
        break
    elif reachability == QNetworkInformation.Reachability.Local:
        print("Network is locally reachable.")
        break
    elif reachability == QNetworkInformation.Reachability.Site:
        print("Network can reach the site.")
        break
    elif reachability == QNetworkInformation.Reachability.Online:
        print("Network is online.")
        break


if __name__ == "__main__":
    a = QCoreApplication(argc, argv)
    # Check if QNetworkInformation is supported
    if not QNetworkInformation.loadDefaultBackend():
        qWarning() << "QNetworkInformation is not supported on self platform or backend."
        return 1

    QNetworkInformation* netInfo = QNetworkInformation.instance()
    # Connect to the reachabilityChanged signal
    netInfo.reachabilityChanged.connect(
                     onReachabilityChanged)
    # Print initial status
    onReachabilityChanged(netInfo.reachability())
    return a.exec()

For more advanced uses cases, developers may prefer to load a backend based on specific capabilities or preferences. loadBackendByFeatures() allows selecting a backend that supports a specific set of features, such as reporting the transport mediom or signal strength. Alternatively, loadBackendByName() allows loading a plugin by its name, which can include platform-specific or custom backend implementations.

QNetworkInformation is a singleton and stays alive from the first successful load until destruction of the QCoreApplication object. If you destroy and re-create the QCoreApplication object you must load it again to reinitialize the plugin.

Note

Because the class is a singleton while also relying on QCoreApplication, QNetworkInformation should always first be loaded in the same thread as the QCoreApplication object. This is because the object will also be destroyed in this thread, and various backend-specific components may rely on being destroyed in the same thread as it is created.

One possible use case for QNetworkInformation is to monitor network connectivity status. reachability() provides an indication of whether the system is considered online, based on information reported by the underlying operating system or plugin. However, this information may not always be accurate. For example, on Windows, the online check may rely on connectivity to a Microsoft-owned server; if that server is unreachable (e.g., due to firewall rules), the system may incorrectly report that it is offline. As such, reachability() should not be used as a definitive pre-check before attempting a network connection, but rather as a general signal of connectivity state.

To use reachability() effectively, the application must also understand what kind of destination it is trying to reach. For example, if the target is a local IP address, then Local or Site may be sufficient. If the destination is on the public internet, then Online is required. Without this context, interpretring the reported reachability may lead to incorrect assumptions about actual network access.

Warning

Only Linux and Windows provide support for the finer-grained Site and Local options. On Android and Apple platforms reachability() is limited to reporting only Online, Offline or Unknown. Therefore, any logic that relies on detecting Local or Site level connectivity must include appropriate platform checks or fallbacks.

# Simple helper to decide whether an IP address is "local"
def isLocalAddress(address):

    return address.isInSubnet(QHostAddress("192.168.0.0"), 16) or
           address.isInSubnet(QHostAddress("10.0.0.0"), 8) or
           address.isInSubnet(QHostAddress("172.16.0.0"), 12) or
           address.isLoopback()

if __name__ == "__main__":            ...

# Target IP address (default: Google DNS)
targetIpStr = argc > 1 if argv[1] else "8.8.8.8"
targetIp = QHostAddress(targetIpStr)
if targetIp.isNull():
    qWarning() << "Invalid IP address:" << targetIpStr
    return 1

# Decide what level of reachability is needed for the target
QNetworkInformation.Reachability requiredReachability =
    isLocalAddress(targetIp)
        ? QNetworkInformation.Reachability.Local
super().__init__()
# Fetch the current system-reported reachability
QNetworkInformation.Reachability currentReachability = networkInfo.reachability()
print("Target IP:", targetIp.toString())
print("Target is considered")
         << (isLocalAddress(targetIp) if "local/site." else "external/online.")
print("Required reachability level:", requiredReachability)
print("Current reachability:", currentReachability)
if currentReachability < requiredReachability:
    qWarning() << "Current network state may not allow reaching the target address."
else:
    print("Target may be reachable based on current network state.")            ...

Synopsis¶

Properties¶

isBehindCaptivePortalᅟ - Lets you know if the user’s device is behind a captive portal
isMeteredᅟ - Check if the current connection is metered
reachabilityᅟ - Current state of the system’s network connectivity
transportMediumᅟ - Currently active transport medium for the application

Note

This documentation may contain snippets that were automatically translated from C++ to Python. We always welcome contributions to the snippet translation. If you see an issue with the translation, you can also let us know by creating a ticket on https:/bugreports.qt.io/projects/PYSIDE

class Reachability¶

Constant	Description
QNetworkInformation.Reachability.Reachability.Unknown	If this value is returned then we may be connected but the OS has still not confirmed full connectivity, or this feature is not supported.
QNetworkInformation.Reachability.Reachability.Disconnected	Indicates that the system may have no connectivity at all.
QNetworkInformation.Reachability.Reachability.Local	Indicates that the system is connected to a network, but it might only be able to access devices on the local network.
QNetworkInformation.Reachability.Reachability.Site	Indicates that the system is connected to a network, but it might only be able to access devices on the local subnet or an intranet.
QNetworkInformation.Reachability.Reachability.Online	Indicates that the system is connected to a network and able to access the Internet.

See also

reachability

class TransportMedium¶

Lists the currently recognized media with which one can connect to the internet.

Constant

Description

QNetworkInformation.TransportMedium.TransportMedium.Unknown

Returned if either the OS reports no active medium, the active medium is not recognized by Qt, or the TransportMedium feature is not supported.

QNetworkInformation.TransportMedium.TransportMedium.Ethernet

Indicates that the currently active connection is using ethernet. Note: This value may also be returned when Windows is connected to a Bluetooth personal area network.

QNetworkInformation.TransportMedium.TransportMedium.Cellular

Indicates that the currently active connection is using a cellular network.

QNetworkInformation.TransportMedium.TransportMedium.WiFi

Indicates that the currently active connection is using Wi-Fi.

QNetworkInformation.TransportMedium.TransportMedium.Bluetooth

Indicates that the currently active connection is connected using Bluetooth.

See also

transportMedium

Constant	Description
QNetworkInformation.TransportMedium.TransportMedium.Unknown	Returned if either the OS reports no active medium, the active medium is not recognized by Qt, or the TransportMedium feature is not supported.
QNetworkInformation.TransportMedium.TransportMedium.Ethernet	Indicates that the currently active connection is using ethernet. Note: This value may also be returned when Windows is connected to a Bluetooth personal area network.
QNetworkInformation.TransportMedium.TransportMedium.Cellular	Indicates that the currently active connection is using a cellular network.
QNetworkInformation.TransportMedium.TransportMedium.WiFi	Indicates that the currently active connection is using Wi-Fi.
QNetworkInformation.TransportMedium.TransportMedium.Bluetooth	Indicates that the currently active connection is connected using Bluetooth.

Added in version 6.3.

class Feature¶

(inherits enum.Flag) Lists all of the features that a plugin may currently support. This can be used in loadBackendByFeatures() .

Constant

Description

QNetworkInformation.Feature.Feature.Reachability

If the plugin supports this feature then the reachability property will provide useful results. Otherwise it will always return Reachability::Unknown. See also Reachability .

QNetworkInformation.Feature.Feature.CaptivePortal

If the plugin supports this feature then the isBehindCaptivePortal property will provide useful results. Otherwise it will always return false.

QNetworkInformation.Feature.Feature.TransportMedium

If the plugin supports this feature then the transportMedium property will provide useful results. Otherwise it will always return TransportMedium::Unknown. See also TransportMedium .

QNetworkInformation.Feature.Feature.Metered

If the plugin supports this feature then the isMetered property will provide useful results. Otherwise it will always return false.

Constant	Description
QNetworkInformation.Feature.Feature.Reachability	If the plugin supports this feature then the `reachability` property will provide useful results. Otherwise it will always return `Reachability::Unknown`. See also `Reachability` .
QNetworkInformation.Feature.Feature.CaptivePortal	If the plugin supports this feature then the `isBehindCaptivePortal` property will provide useful results. Otherwise it will always return `false`.
QNetworkInformation.Feature.Feature.TransportMedium	If the plugin supports this feature then the `transportMedium` property will provide useful results. Otherwise it will always return `TransportMedium::Unknown`. See also `TransportMedium` .
QNetworkInformation.Feature.Feature.Metered	If the plugin supports this feature then the `isMetered` property will provide useful results. Otherwise it will always return `false`.

Note

Properties can be used directly when from __feature__ import true_property is used or via accessor functions otherwise.

property isBehindCaptivePortalᅟ: bool¶

This property holds Lets you know if the user’s device is behind a captive portal..

This property indicates if the user’s device is currently known to be behind a captive portal. This functionality relies on the operating system’s detection of captive portals and is not supported on systems that don’t report this. On systems where this is not supported this will always return false.

Access functions:

isBehindCaptivePortal()
Signal isBehindCaptivePortalChanged()

property isMeteredᅟ: bool¶

Warning

This section contains snippets that were automatically translated from C++ to Python and may contain errors.

This property holds Check if the current connection is metered.

This property returns whether the current connection is (known to be) metered or not. You can use this as a guiding factor to decide whether your application should perform certain network requests or uploads. For instance, you may not want to upload logs or diagnostics while this property is true.

def uploadLogFile():            ...


if __name__ == "__main__":

    app = QCoreApplication(argc, argv)            ...

if netInfo.isMetered():
    qWarning() << "Log upload skipped: Current network is metered."
    app.quit()
else:
    uploadLogFile()            ...

Access functions:

isMetered()
Signal isMeteredChanged()

property reachabilityᅟ: QNetworkInformation.Reachability¶

This property holds The current state of the system’s network connectivity..

Indicates the level of connectivity that can be expected. Do note that this is only based on what the plugin/operating system reports. In certain scenarios this is known to be wrong. For example, on Windows the ‘Online’ check, by default, is performed by Windows connecting to a Microsoft-owned server. If this server is for any reason blocked then it will assume it does not have Online reachability. Because of this you should not use this as a pre-check before attempting to make a connection.

Access functions:

reachability()
Signal reachabilityChanged()

property transportMediumᅟ: QNetworkInformation.TransportMedium¶

This property holds The currently active transport medium for the application.

This property returns the currently active transport medium for the application, on operating systems where such information is available.

When the current transport medium changes a signal is emitted, this can, for instance, occur when a user leaves the range of a WiFi network, unplugs their ethernet cable or enables Airplane mode.

Access functions:

transportMedium()
Signal transportMediumChanged()

static availableBackends()¶

Return type:: list of strings

Returns a list of the names of all currently available backends.

backendName()¶

Return type:: str

Returns the name of the currently loaded backend.

static instance()¶

Return type:: QNetworkInformation

Returns a pointer to the instance of the QNetworkInformation , if any. If this method is called before a backend is loaded, it returns a null pointer.

See also

loadBackendByName() loadDefaultBackend() loadBackendByFeatures()

isBehindCaptivePortal()¶

Return type:: bool

Getter of property isBehindCaptivePortalᅟ .

isBehindCaptivePortalChanged(state)¶

Parameters:: state – bool

Notification signal of property isBehindCaptivePortalᅟ .

isMetered()¶

Return type:: bool

Getter of property isMeteredᅟ .

isMeteredChanged(isMetered)¶

Parameters:: isMetered – bool

Notification signal of property isMeteredᅟ .

static load(features)¶

Parameters:: features – Combination of Feature
Return type:: bool

Note

This function is deprecated.

Use loadBackendByFeatures() instead.

See also

loadBackendByName() loadDefaultBackend() loadBackendByFeatures()

static load(backend)

Parameters:: backend – str
Return type:: bool

Note

This function is deprecated.

Use loadBackendByName() instead.

See also

loadBackendByName() loadDefaultBackend() loadBackendByFeatures()

static loadBackendByFeatures(features)¶

Parameters:: features – Combination of Feature
Return type:: bool

Load a backend which supports features.

Returns true if it managed to load the requested backend or if it was already loaded. Returns false otherwise.

See also

instance

static loadBackendByName(backend)¶

Parameters:: backend – str
Return type:: bool

Attempts to load a backend whose name matches backend (case insensitively).

Returns true if it managed to load the requested backend or if it was already loaded. Returns false otherwise.

See also

instance

static loadDefaultBackend()¶

Return type:: bool

Attempts to load the platform-default backend.

Note

Starting with 6.7 this tries to load any backend that supports Reachability if the platform-default backend is not available or fails to load. If this also fails it will fall back to a backend that only returns the default values for all properties.

This platform-to-plugin mapping is as follows:

Platform

Plugin-name

Windows

networklistmanager

Apple (macOS/iOS)

applenetworkinformation

Android

android

Linux

networkmanager

Platform	Plugin-name
Windows	networklistmanager
Apple (macOS/iOS)	applenetworkinformation
Android	android
Linux	networkmanager

This function is provided for convenience where the logic earlier is good enough. If you require a specific plugin then you should call loadBackendByName() or loadBackendByFeatures() directly instead.

Determines a suitable backend to load and returns true if this backend is already loaded or on successful loading of it. Returns false if any other backend has already been loaded, or if loading of the selected backend fails.

See also

instance() loadBackendByName() loadBackendByFeatures()

reachability()¶

Return type:: Reachability

Getter of property reachabilityᅟ .

reachabilityChanged(newReachability)¶

Parameters:: newReachability – Reachability

Notification signal of property reachabilityᅟ .

supportedFeatures()¶

Return type:: Combination of Feature

Returns all the supported features of the current backend.

supports(features)¶

Parameters:: features – Combination of Feature
Return type:: bool

Returns true if the currently loaded backend supports features.

transportMedium()¶

Return type:: TransportMedium

Getter of property transportMediumᅟ .

transportMediumChanged(current)¶

Parameters:: current – TransportMedium

Notification signal of property transportMediumᅟ .

PySide6.QtNetwork.QNetworkInformation¶

Synopsis¶

Properties¶

Methods¶

Signals¶

Static functions¶