Class: QgsNetworkAccessManager

QNetworkAccessManager with additional QGIS specific logic.

This class implements the QGIS network access manager. It’s a singleton that can be used across QGIS.

Plugins can insert proxy factories and thereby redirect requests to individual proxies.

If no proxy factories are there or none returns a proxy for an URL a fallback proxy can be set. There’s also a exclude list that defines URLs that the fallback proxy should not be used for, then no proxy will be used.

Class Hierarchy

Base classes

QNetworkAccessManager
QObject

Methods

abortAuthBrowser	Abort any outstanding external browser login request.
excludeList	Returns the proxy exclude list.
fallbackProxy	Returns the fallback proxy used by the manager.
insertProxyFactory	Inserts a factory into the proxy factories list.
noProxyList	Returns the no proxy list.
preprocessRequest	Preprocesses request
proxyFactories	Returns a list of proxy factories used by the manager.
removeProxyFactory	Removes a factory from the proxy factories list.
requestAuthCloseBrowser	Forwards an external browser login closure request to the authentication handler.
requestAuthOpenBrowser	Forwards an external browser login url opening request to the authentication handler.
setFallbackProxyAndExcludes	Sets the fallback proxy and URLs which shouldn't use it.
setupDefaultProxyAndCache	Setup the QgsNetworkAccessManager (NAM) according to the user's settings.
useSystemProxy	Returns whether the system proxy should be used.

Static Methods

blockingGet	Posts a GET request to obtain the contents of the target request and returns a new QgsNetworkReplyContent object for reading.
blockingPost	Posts a POST request to obtain the contents of the target request, using the given data, and returns a new QgsNetworkReplyContent object for reading.
cacheLoadControlFromName	Returns QNetworkRequest.CacheLoadControl from a name.
cacheLoadControlName	Returns the name for QNetworkRequest.CacheLoadControl.
instance	Returns a pointer to the active QgsNetworkAccessManager for the current thread.
removeAdvancedRequestPreprocessor	Removes an advanced request pre-processor function with matching id.
removeReplyPreprocessor	Removes the custom reply pre-processor function with matching id.
removeRequestPreprocessor	Removes the custom request pre-processor function with matching id.
setAdvancedRequestPreprocessor	Sets an advanced request pre-processor function, which allows manipulation of a network request before it is processed.
setReplyPreprocessor	Sets a reply pre-processor function, which allows manipulation of QNetworkReply objects after they are created (but before they are fetched).
setRequestPreprocessor	Sets a request pre-processor function, which allows manipulation of a network request before it is processed.
setTimeout	Sets the maximum timeout time for network requests, in milliseconds.
timeout	Returns the network timeout length, in milliseconds.

Signals

authBrowserAborted	Emitted when external browser logins are to be aborted.
cookiesChanged	Emitted when the cookies changed.
downloadProgress	Emitted when a network reply receives a progress report.
requestAboutToBeCreated	Emitted when a network request is about to be created.
requestAuthDetailsAdded	Emitted when network authentication details have been added to a request.
requestCreated
requestEncounteredSslErrors	Emitted when a network request encounters SSL errors.
requestRequiresAuth	Emitted when a network request prompts an authentication request.
requestTimedOut	Emitted when a request times out.

class qgis.core.QgsNetworkAccessManager

Bases: QNetworkAccessManager

abortAuthBrowser(self)

Abort any outstanding external browser login request.

Note

Background threads will listen to aborted browser request signals from the network manager on the main thread.

Added in version 3.20.

signal authBrowserAborted

Emitted when external browser logins are to be aborted.

Added in version 3.20.

static blockingGet(request: QNetworkRequest, authCfg: str | None = '', forceRefresh: bool = False, feedback: QgsFeedback | None = None) → QgsNetworkReplyContent

Posts a GET request to obtain the contents of the target request and returns a new QgsNetworkReplyContent object for reading. The current thread will be blocked until the request is returned.

This method is safe to call in either the main thread or a worker thread.

If forceRefresh is False then previously cached replies may be used for the request. If it is set to True then a new query is always performed.

If an authCfg has been specified, then that authentication configuration required will automatically be applied to request. There is no need to manually apply the authentication to the request prior to calling this method.

The optional feedback argument can be used to abort ongoing requests.

The contents of the reply will be returned after the request is completed or an error occurs.

See also

blockingPost()

Added in version 3.6.

Parameters:

• request (QNetworkRequest)

• authCfg (Optional[str] = '')

• forceRefresh (bool = False)

• feedback (Optional[QgsFeedback] = None)

Return type:

QgsNetworkReplyContent

static blockingPost(request: QNetworkRequest, data: QByteArray | bytes | bytearray, authCfg: str | None = '', forceRefresh: bool = False, feedback: QgsFeedback | None = None) → QgsNetworkReplyContent

Posts a POST request to obtain the contents of the target request, using the given data, and returns a new QgsNetworkReplyContent object for reading. The current thread will be blocked until the request is returned.

This method is safe to call in either the main thread or a worker thread.

If forceRefresh is False then previously cached replies may be used for the request. If it is set to True then a new query is always performed.

If an authCfg has been specified, then that authentication configuration required will automatically be applied to request. There is no need to manually apply the authentication to the request prior to calling this method.

The optional feedback argument can be used to abort ongoing requests.

The contents of the reply will be returned after the request is completed or an error occurs.

See also

blockingGet()

Added in version 3.6.

Parameters:

• request (QNetworkRequest)

• data (Union[QByteArray, bytes, bytearray])

• authCfg (Optional[str] = '')

• forceRefresh (bool = False)

• feedback (Optional[QgsFeedback] = None)

Return type:

QgsNetworkReplyContent

static cacheLoadControlFromName(name: str | None) → QNetworkRequest.CacheLoadControl

Returns QNetworkRequest.CacheLoadControl from a name.

See also

cacheLoadControlName()

Parameters:

name (Optional[str])

Return type:

QNetworkRequest.CacheLoadControl

static cacheLoadControlName(control: QNetworkRequest.CacheLoadControl) → str

Returns the name for QNetworkRequest.CacheLoadControl.

See also

cacheLoadControlFromName()

Parameters:

control (QNetworkRequest.CacheLoadControl)

Return type:

str

signal cookiesChanged(cookies: List[QNetworkCookie])

Emitted when the cookies changed.

Added in version 3.22.

Parameters:

cookies (List[QNetworkCookie])

signal downloadProgress(requestId: int, bytesReceived: int, bytesTotal: int)

Emitted when a network reply receives a progress report.

The requestId argument reflects the unique ID identifying the original request which the progress report relates to.

The bytesReceived parameter indicates the number of bytes received, while bytesTotal indicates the total number of bytes expected to be downloaded. If the number of bytes to be downloaded is not known, bytesTotal will be -1.

This signal is propagated to the main thread QgsNetworkAccessManager instance, so it is necessary only to connect to the main thread’s signal in order to receive notifications about requests created in any thread.

Added in version 3.6.

Parameters:

• requestId (int)

• bytesReceived (int)

• bytesTotal (int)

excludeList(self) → List[str]

Returns the proxy exclude list.

This list consists of the beginning of URL strings which will not use the fallback proxy.

See also

noProxyList()

See also

fallbackProxy()

See also

setFallbackProxyAndExcludes()

Return type:

List[str]

fallbackProxy(self) → QNetworkProxy

Returns the fallback proxy used by the manager.

The fallback proxy is used for URLs which no other proxy factory returned proxies for.

See also

proxyFactories()

See also

setFallbackProxyAndExcludes()

Return type:

QNetworkProxy

insertProxyFactory(self, factory: QNetworkProxyFactory | None)

Inserts a factory into the proxy factories list.

Ownership of factory is transferred to the manager.

See also

removeProxyFactory()

See also

proxyFactories()

Parameters:

factory (Optional[QNetworkProxyFactory])

static instance(connectionType: Qt.ConnectionType = Qt.BlockingQueuedConnection) → QgsNetworkAccessManager | None

Returns a pointer to the active QgsNetworkAccessManager for the current thread.

With the connectionType parameter it is possible to setup the default connection type that is used to handle signals that might require user interaction and therefore need to be handled on the main thread. See in-depth discussion below.

Parameters:

connectionType (Qt.ConnectionType = Qt.BlockingQueuedConnection) – In most cases the default of using a Qt.BlockingQueuedConnection is ok, to make a background thread wait for the main thread to answer such a request is fine and anything else is dangerous. However, in case the request was started on the main thread, one should execute a local event loop in a helper thread and freeze the main thread for the duration of the download. In this case, if an authentication request is sent from the background thread network access manager, the background thread should be blocked, the main thread be woken up, processEvents() executed once, the main thread frozen again and the background thread continued.

Return type:

Optional[QgsNetworkAccessManager]

noProxyList(self) → List[str]

Returns the no proxy list.

This list consists of the beginning of URL strings which will not use any proxy at all

See also

excludeList()

See also

fallbackProxy()

See also

setFallbackProxyAndExcludes()

Return type:

List[str]

preprocessRequest(self, req: QNetworkRequest | None)

Preprocesses request

Parameters:

req (Optional[QNetworkRequest]) – the request to preprocess

Added in version 3.22.

proxyFactories(self) → List[QNetworkProxyFactory]

Returns a list of proxy factories used by the manager.

See also

insertProxyFactory()

See also

proxyFactories()

Return type:

List[QNetworkProxyFactory]

static removeAdvancedRequestPreprocessor(id: str | None)

Removes an advanced request pre-processor function with matching id.

The id must correspond to a pre-processor previously added via a call to setAdvancedRequestPreprocessor().

Returns True if processor existed and was removed.

See also

setAdvancedRequestPreprocessor()

Added in version 3.44.

Parameters:

id (Optional[str])

removeProxyFactory(self, factory: QNetworkProxyFactory | None)

Removes a factory from the proxy factories list.

See also

insertProxyFactory()

See also

proxyFactories()

Parameters:

factory (Optional[QNetworkProxyFactory])

static removeReplyPreprocessor(id: str | None)

Removes the custom reply pre-processor function with matching id.

The id must correspond to a pre-processor previously added via a call to setReplyPreprocessor().

Returns True if processor existed and was removed.

See also

setReplyPreprocessor()

Added in version 3.26.

Parameters:

id (Optional[str])

static removeRequestPreprocessor(id: str | None)

Removes the custom request pre-processor function with matching id.

The id must correspond to a pre-processor previously added via a call to setRequestPreprocessor().

Returns True if processor existed and was removed.

See also

setRequestPreprocessor()

Added in version 3.22.

Parameters:

id (Optional[str])

signal requestAboutToBeCreated(request: QgsNetworkRequestParameters)

Emitted when a network request is about to be created.

This signal is propagated to the main thread QgsNetworkAccessManager instance, so it is necessary only to connect to the main thread’s signal in order to receive notifications about requests created in any thread.

See also

requestCreated()

See also

finished()

See also

requestTimedOut()

Added in version 3.6.

Parameters:

request (QgsNetworkRequestParameters)

requestAuthCloseBrowser(self)

Forwards an external browser login closure request to the authentication handler.

Note

If called by a background thread, the request will be forwarded to the network manager on the main thread.

Added in version 3.20.

signal requestAuthDetailsAdded(requestId: int, realm: str, user: str, password: str)

Emitted when network authentication details have been added to a request.

The requestId argument reflects the unique ID identifying the original request which the authentication relates to.

This signal is always sent from the main thread QgsNetworkAccessManager instance, so it is necessary only to connect to the main thread’s signal in order to receive notifications about authentication requests from any thread.

This signal is for debugging and logging purposes only, and should not be used to respond to the requests. See QgsNetworkAuthenticationHandler for details on how to handle authentication requests.

See also

requestRequiresAuth()

Added in version 3.6.

Parameters:

• requestId (int)

• realm (str)

• user (str)

• password (str)

requestAuthOpenBrowser(self, url: QUrl)

Forwards an external browser login url opening request to the authentication handler.

Note

If called by a background thread, the request will be forwarded to the network manager on the main thread.

Added in version 3.20.

Parameters:

url (QUrl)

signal requestCreated(request: QgsNetworkRequestParameters)

Deprecated since version 3.40: Use the thread-safe requestAboutToBeCreated( QgsNetworkRequestParameters ) signal instead.

Parameters:

request (QgsNetworkRequestParameters)

signal requestEncounteredSslErrors(requestId: int, errors: List[QSslError])

Emitted when a network request encounters SSL errors.

The requestId argument reflects the unique ID identifying the original request which the SSL error relates to.

This signal is propagated to the main thread QgsNetworkAccessManager instance, so it is necessary only to connect to the main thread’s signal in order to receive notifications about SSL errors from any thread.

This signal is for debugging and logging purposes only, and cannot be used to respond to the errors. See QgsSslErrorHandler for details on how to handle SSL errors and potentially ignore them.

Added in version 3.6.

Parameters:

• requestId (int)

• errors (List[QSslError])

signal requestRequiresAuth(requestId: int, realm: str)

Emitted when a network request prompts an authentication request.

The requestId argument reflects the unique ID identifying the original request which the authentication relates to.

This signal is propagated to the main thread QgsNetworkAccessManager instance, so it is necessary only to connect to the main thread’s signal in order to receive notifications about authentication requests from any thread.

This signal is for debugging and logging purposes only, and cannot be used to respond to the requests. See QgsNetworkAuthenticationHandler for details on how to handle authentication requests.

See also

requestAuthDetailsAdded()

Added in version 3.6.

Parameters:

• requestId (int)

• realm (str)

signal requestTimedOut(reply: QNetworkReply)

Emitted when a request times out.

Parameters:

reply (QNetworkReply)

static setAdvancedRequestPreprocessor(a0: Callable[..., None] | None) → str

Sets an advanced request pre-processor function, which allows manipulation of a network request before it is processed.

The processor function takes the QNetworkRequest, network operation (a QNetworkAccessManager.Operation cast to an integer value), and request data as its arguments, and can mutate the request if necessary.

It should return the desired operation (as a QNetworkAccessManager.Operation cast to an integer value) and request data as a tuple, transforming as desired.

Return type:

str

Returns:

An auto-generated string uniquely identifying the preprocessor, which can later be used to remove the preprocessor (via a call to removeAdvancedRequestPreprocessor()).

See also

removeAdvancedRequestPreprocessor()

Added in version 3.44.

Parameters:

a0 (Optional[Callable[..., None]])

setFallbackProxyAndExcludes(self, proxy: QNetworkProxy, excludes: Iterable[str | None], noProxyURLs: Iterable[str | None])

Sets the fallback proxy and URLs which shouldn’t use it.

The fallback proxy is used for URLs which no other proxy factory returned proxies for. The excludes list specifies the beginning of URL strings which will not use this fallback proxy. The noProxyURLs list specifies the beginning of URL strings which will not use any proxy at all

See also

fallbackProxy()

See also

excludeList()

See also

noProxyList()

Parameters:

• proxy (QNetworkProxy)

• excludes (Iterable[Optional[str]])

• noProxyURLs (Iterable[Optional[str]])

static setReplyPreprocessor(a0: Callable[..., None] | None) → str

Sets a reply pre-processor function, which allows manipulation of QNetworkReply objects after they are created (but before they are fetched).

The processor function takes a QNetworkRequest request and a QNetworkReply as arguments, and can connect to QNetworkReply signals directly as desired.

Return type:

str

Returns:

An auto-generated string uniquely identifying the preprocessor, which can later be used to remove the preprocessor (via a call to removeReplyPreprocessor()).

See also

removeReplyPreprocessor()

Added in version 3.26.

Parameters:

a0 (Optional[Callable[..., None]])

static setRequestPreprocessor(a0: Callable[..., None] | None) → str

Sets a request pre-processor function, which allows manipulation of a network request before it is processed.

The processor function takes the QNetworkRequest as its argument, and can mutate the request if necessary.

Return type:

str

Returns:

An auto-generated string uniquely identifying the preprocessor, which can later be used to remove the preprocessor (via a call to removeRequestPreprocessor()).

See also

removeRequestPreprocessor()

Added in version 3.22.

Parameters:

a0 (Optional[Callable[..., None]])

static setTimeout(time: int)

Sets the maximum timeout time for network requests, in milliseconds. If set to 0, no timeout is set.

See also

timeout()

Added in version 3.6.

Parameters:

time (int)

setupDefaultProxyAndCache(self, connectionType: Qt.ConnectionType = Qt.BlockingQueuedConnection)

Setup the QgsNetworkAccessManager (NAM) according to the user’s settings. The connectionType sets up the default connection type that is used to handle signals that might require user interaction and therefore need to be handled on the main thread. See in-depth discussion in the documentation for the constructor of this class.

Parameters:

connectionType (Qt.ConnectionType = Qt.BlockingQueuedConnection)

static timeout() → int

Returns the network timeout length, in milliseconds.

See also

setTimeout()

Added in version 3.6.

Return type:

int

useSystemProxy(self) → bool

Returns whether the system proxy should be used.

Return type:

bool