Class: QgsProviderRegistry

class qgis.core.QgsProviderRegistry

Bases: sip.wrapper

A registry / canonical manager of data providers.

This is a Singleton class that manages data provider access.

Providers can be either loaded via libraries or native providers that are included in the core QGIS installation and accessed through function pointers.

Loaded providers may be restricted using QGIS_PROVIDER_FILE environment variable. QGIS_PROVIDER_FILE is regexp pattern applied to provider file name (not provider key). For example, if the variable is set to gdal|ogr|postgres it will load only providers gdal, ogr and postgres.

Methods

absoluteToRelativeUri

Converts absolute path(s) to relative path(s) in the given provider-specific URI.

createDb

Creates database by the provider on the path

createProvider

Creates a new instance of a provider.

createProviderLibrary

Returns a new QLibrary for the specified providerKey.

createRasterDataProvider

Creates new instance of raster data provider

createSelectionWidget

Returns a new widget for selecting layers from a provider.

createTransaction

Returns new instance of transaction.

dataItemProviders

Returns list of data item providers of the provider

databaseDrivers

Returns a string containing the available database drivers

decodeUri

Breaks a provider data source URI into its component paths (e.g.

deleteStyleById

Deletes a layer style defined by styleId

directoryDrivers

Returns a string containing the available directory drivers

encodeUri

Reassembles a provider data source URI from its component paths (e.g.

fileMeshDatasetFilters

Returns a file filter string for supported mesh dataset files.

fileMeshFilters

Returns a file filter string for supported mesh files.

filePointCloudFilters

Returns a file filter string for supported point clouds.

fileRasterFilters

Returns a file filter string for supported raster files.

fileVectorFilters

Returns a file filter string for supported vector files.

fileVectorTileFilters

Returns a file filter string for supported vector tile files.

function

Gets pointer to provider function

getStyleById

Gets a layer style defined by styleId.

handleUnusableUri

Returns True if the specified uri can potentially be handled by QGIS, if additional dependencies or build-time requirements are present.

instance

Means of accessing canonical single instance

library

Returns path for the library of the provider.

libraryDirectory

Returns the library directory where plugins are found.

listStyles

Lists stored layer styles in the provider defined by providerKey and uri

loadStoredStyle

Loads a layer style from the provider storage, reporting its name.

loadStyle

Loads a layer style defined by uri

pluginList

Returns list of provider plugins found

preferredProvidersForUri

Returns the details for the preferred provider(s) for opening the specified uri.

protocolDrivers

Returns a string containing the available protocol drivers

providerCapabilities

Returns the provider capabilities

providerList

Returns list of available providers by their keys

providerMetadata

Returns metadata of the provider or None if not found

providersForLayerType

Returns a list of the provider keys for available providers which handle the specified layer type.

pyramidResamplingMethods

Returns list of raster pyramid resampling methods

querySublayers

Queries the specified uri and returns a list of any valid sublayers found in the dataset which can be handled by any registered data provider.

registerGuis

Deprecated since version QGIS: 3.10

registerProvider

register a new vector data provider from its providerMetadata

registerUnusableUriHandler

Registers an unusable URI handler, used to handle unusable URIs which aren't handled by any registered providers, and construct user-friendly warnings as to why the URI is unusable.

relativeToAbsoluteUri

Converts relative path(s) to absolute path(s) in the given provider-specific URI.

saveLayerMetadata

Saves metadata to the layer corresponding to the specified uri.

saveStyle

Saves a layer style to provider

setLibraryDirectory

Sets library directory where to search for plugins

shouldDeferUriForOtherProviders

Returns True if the provider with matching providerKey should defer handling of the specified uri to another provider.

styleExists

Returns True if a layer style with the specified styleId exists in the provider defined by providerKey and uri.

uriIsBlocklisted

Returns True if the specified uri is known by any registered provider to be something which should be blocklisted from the QGIS interface, e.g.

Attributes

Embedded

Manager

None

Embedded = 1
Manager = 2
None = 0
class ProviderCandidateDetails

Bases: sip.wrapper

Contains information pertaining to a candidate provider.

New in version 3.18.

QgsProviderRegistry.ProviderCandidateDetails(metadata: QgsProviderMetadata, layerTypes: Iterable[Qgis.LayerType]) Constructor for ProviderCandidateDetails, with the specified provider metadata and valid candidate layerTypes.

QgsProviderRegistry.ProviderCandidateDetails(QgsProviderRegistry.ProviderCandidateDetails)

layerTypes(self) → List[Qgis.LayerType]

Returns a list of map layer types which are valid options for opening the target using this candidate provider.

Return type:

List[Qgis.LayerType]

metadata(self) → QgsProviderMetadata

Returns the candidate provider metadata.

Return type:

QgsProviderMetadata

class UnusableUriDetails

Bases: sip.wrapper

Contains information about unusable URIs which aren’t handled by any registered providers.

For example, if a QGIS install is built without the PDAL library then las/laz files are unusable. This class can then be used to construct friendly warnings to users advising them why the las/laz files cannot be used on their QGIS build.

New in version 3.18.1.

QgsProviderRegistry.UnusableUriDetails(uri: str = ‘’, warning: str = ‘’, layerTypes: Iterable[Qgis.LayerType] = []) Constructor for UnusableUriDetails for the given uri, with the specified user-friendly, translated warning.

The optional layerTypes argument can be used to specify layer types which are usually valid options for opening the URI.

QgsProviderRegistry.UnusableUriDetails(QgsProviderRegistry.UnusableUriDetails)

detailedWarning
layerTypes
uri
warning
class UnusableUriHandlerInterface

Bases: sip.wrapper

An interface used to handle unusable URIs which aren’t handled by any registered providers, and construct user-friendly warnings as to why the URI is unusable.

For example, if a QGIS install is built without the PDAL library then las/laz files are unusable. This class can then be used to construct friendly warnings to users advising them why the las/laz files cannot be used on their QGIS build.

New in version 3.18.1.

details(self, uri: str) → QgsProviderRegistry.UnusableUriDetails

Returns the details for advising the user why the uri is not usable.

Parameters:

uri (str) –

Return type:

QgsProviderRegistry.UnusableUriDetails

matchesUri(self, uri: str) → bool

Returns True if the handle is an unusable URI handler for the specified uri.

Parameters:

uri (str) –

Return type:

bool

class WidgetMode

Bases: int

absoluteToRelativeUri(self, providerKey: str, uri: str, context: QgsReadWriteContext) → str

Converts absolute path(s) to relative path(s) in the given provider-specific URI. and returns modified URI according to the context object’s configuration. This is commonly used when writing project files. If a provider does not work with paths, unmodified URI will be returned.

Return type:

str

Returns:

modified URI with relative path(s)

Note

this function may not be supported by all providers. The default implementation uses QgsPathResolver.writePath() on the whole URI.

See also

relativeToAbsoluteUri()

New in version 3.30.

Parameters:
createDb(self, providerKey: str, dbPath: str, errCause: str) → bool

Creates database by the provider on the path

New in version 3.10.

Parameters:

  • providerKey (str) –

  • dbPath (str) –

  • errCause (str) –

Return type:

bool

createProvider(self, providerKey: str, dataSource: str, options: QgsDataProvider.ProviderOptions = QgsDataProvider.ProviderOptions(), flags: QgsDataProvider.ReadFlags | QgsDataProvider.ReadFlag = QgsDataProvider.ReadFlags()) → QgsDataProvider

Creates a new instance of a provider.

Parameters:

  • providerKey (str) – identifier of the provider

  • dataSource (str) – string containing data source for the provider

  • options (QgsDataProvider.ProviderOptions = QgsDataProvider.ProviderOptions()) – provider options

  • flags (Union[QgsDataProvider.ReadFlags) – provider flags since QGIS 3.16

Return type:

QgsDataProvider

Returns:

new instance of provider or None on error

See also

createRasterDataProvider()

createProviderLibrary(self, providerKey: str) → QLibrary

Returns a new QLibrary for the specified providerKey. Ownership of the returned object is transferred to the caller and the caller is responsible for deleting it.

If the provider uses direct provider function pointers instead of a library None will be returned.

Deprecated since version QGIS: 3.10 - providers may not need to be loaded from a library

Parameters:

providerKey (str) –

Return type:

QLibrary

createRasterDataProvider(self, providerKey: str, uri: str, format: str, nBands: int, type: Qgis.DataType, width: int, height: int, crs: QgsCoordinateReferenceSystem, createOptions: Iterable[str] = []) → Tuple[QgsRasterDataProvider, float]

Creates new instance of raster data provider

See also

createProvider()

New in version 3.10.

Parameters:

  • providerKey (str) –

  • uri (str) –

  • format (str) –

  • nBands (int) –

  • type (Qgis.DataType) –

  • width (int) –

  • height (int) –

  • crs (QgsCoordinateReferenceSystem) –

  • createOptions (Iterable[str] = []) –

Return type:

Tuple[QgsRasterDataProvider, float]

createSelectionWidget(self, providerKey: str, parent: QWidget = None, fl: Union[Qt.WindowFlags, Qt.WindowType] = Qt.WindowFlags(), widgetMode: QgsProviderRegistry.WidgetMode = QgsProviderRegistry.WidgetMode.None) → QWidget

Returns a new widget for selecting layers from a provider. Either the parent widget must be set or the caller becomes responsible for deleting the returned widget.

Deprecated since version QGIS: 3.10 - use QgsGui.sourceSelectProviderRegistry()->:py:func:~QgsProviderRegistry.createDataSourceWidget instead

Parameters:

  • providerKey (str) –

  • parent (QWidget = None) –

  • fl (Union[Qt.WindowFlags) –

  • widgetMode (QgsProviderRegistry.WidgetMode = QgsProviderRegistry.WidgetMode.None) –

Return type:

QWidget

createTransaction(self, providerKey: str, connString: str) → QgsTransaction

Returns new instance of transaction. Ownership is transferred to the caller

New in version 3.10.

Parameters:

  • providerKey (str) –

  • connString (str) –

Return type:

QgsTransaction

dataItemProviders(self, providerKey: str) → List[QgsDataItemProvider]

Returns list of data item providers of the provider

Note

Ownership of created data item providers is passed to the caller.

New in version 3.10.

Parameters:

providerKey (str) –

Return type:

List[QgsDataItemProvider]

databaseDrivers(self) → str

Returns a string containing the available database drivers

Return type:

str

decodeUri(self, providerKey: str, uri: str) → Dict[str, Any]

Breaks a provider data source URI into its component paths (e.g. file path, layer name).

Parameters:

  • providerKey (str) – identifier of the provider

  • uri (str) – uri string

Return type:

Dict[str, Any]

Returns:

map containing components. Standard components include “path”, “layerName”, “url”.

Note

this function may not be supported by all providers, an empty map will be returned in such case

New in version 3.4.

deleteStyleById(self, providerKey: str, uri: str, styleId: str, errCause: str) → bool

Deletes a layer style defined by styleId

New in version 3.10.

Parameters:

  • providerKey (str) –

  • uri (str) –

  • styleId (str) –

  • errCause (str) –

Return type:

bool

directoryDrivers(self) → str

Returns a string containing the available directory drivers

Return type:

str

encodeUri(self, providerKey: str, parts: Dict[str, Any]) → str

Reassembles a provider data source URI from its component paths (e.g. file path, layer name).

Parameters:

  • providerKey (str) – identifier of the provider

  • parts (Dict[str) – parts as returned by decodeUri

Return type:

str

Returns:

datasource uri string

Note

this function may not be supported by all providers, an empty string will be returned in such case

See also

decodeUri()

New in version 3.12.

fileMeshDatasetFilters(self) → str

Returns a file filter string for supported mesh dataset files.

Returns a string suitable for a QFileDialog of mesh datasets file formats supported by all data providers.

See also

fileMeshFilters()

New in version 3.6.

Return type:

str

fileMeshFilters(self) → str

Returns a file filter string for supported mesh files.

Returns a string suitable for a QFileDialog of mesh file formats supported by all data providers.

See also

fileMeshDatasetFilters()

See also

fileRasterFilters()

See also

fileVectorFilters()

See also

filePointCloudFilters()

See also

fileVectorTileFilters()

New in version 3.6.

Return type:

str

filePointCloudFilters(self) → str

Returns a file filter string for supported point clouds.

Returns a string suitable for a QFileDialog of point cloud file formats supported by all data providers.

See also

fileMeshFilters()

See also

fileRasterFilters()

See also

fileVectorFilters()

See also

fileVectorTileFilters()

New in version 3.18.

Return type:

str

fileRasterFilters(self) → str

Returns a file filter string for supported raster files.

Returns a string suitable for a QFileDialog of raster file formats supported by all data providers.

Note

This replaces QgsRasterLayer.buildSupportedRasterFileFilter()

See also

fileVectorFilters()

See also

fileMeshFilters()

See also

filePointCloudFilters()

See also

fileVectorTileFilters()

Return type:

str

fileVectorFilters(self) → str

Returns a file filter string for supported vector files.

Returns a string suitable for a QFileDialog of vector file formats supported by all data providers.

See also

fileRasterFilters()

See also

fileMeshFilters()

See also

filePointCloudFilters()

See also

fileVectorTileFilters()

Return type:

str

fileVectorTileFilters(self) → str

Returns a file filter string for supported vector tile files.

Returns a string suitable for a QFileDialog of vector tile file formats supported by all data providers.

See also

fileMeshFilters()

See also

fileRasterFilters()

See also

fileVectorFilters()

See also

filePointCloudFilters()

New in version 3.32.

Return type:

str

function(self, providerKey: str, functionName: str) → sip.voidptr

Gets pointer to provider function

Parameters:

  • providerKey (str) – identifier of the provider

  • functionName (str) – name of function

Return type:

sip.voidptr

Returns:

pointer to function or None on error. If the provider uses direct provider function pointers instead of a library None will be returned.

Deprecated since version QGIS: 3.10 - any provider functionality should be accessed through QgsProviderMetadata

getStyleById(self, providerKey: str, uri: str, styleId: str, errCause: str) → str

Gets a layer style defined by styleId.

See also

styleExists()

New in version 3.10.

Parameters:

  • providerKey (str) –

  • uri (str) –

  • styleId (str) –

  • errCause (str) –

Return type:

str

handleUnusableUri(self, uri: str) → Tuple[bool, QgsProviderRegistry.UnusableUriDetails]

Returns True if the specified uri can potentially be handled by QGIS, if additional dependencies or build-time requirements are present.

This can be used to show user-friendly warning messages advising them why a particular uri cannot be opened on their QGIS install. For example, if a QGIS install is built without the PDAL library then las/laz files are unusable, and this method can be used to retrieve a user-friendly warning as to why the las/laz files cannot be used on their QGIS build.

Warning

This method does not perform the test to actually determine if the given uri can be handled by any registered provider. It is assumed that prior to calling this method the caller has already determined in advance that the uri could not be handled.

Parameters:

uri (str) – URI to test

Return type:

Tuple[bool, QgsProviderRegistry.UnusableUriDetails]

Returns:

  • True if the uri was matched to a registered QgsProviderRegistry.UnusableUriHandlerInterface.

  • details: will be populated with details allowing construction of a user-friendly warning message

See also

registerUnusableUriHandler()

New in version 3.18.1.

instance(pluginPath: str = '') → QgsProviderRegistry

Means of accessing canonical single instance

Parameters:

pluginPath (str = '') –

Return type:

QgsProviderRegistry

library(self, providerKey: str) → str

Returns path for the library of the provider.

If the provider uses direct provider function pointers instead of a library an empty string will be returned.

Deprecated since version QGIS: 3.10 - providers may not need to be loaded from a library (empty string returned)

Parameters:

providerKey (str) –

Return type:

str

libraryDirectory(self) → QDir

Returns the library directory where plugins are found.

Return type:

QDir

listStyles(self, providerKey: str, uri: str, ids: Iterable[str], names: Iterable[str], descriptions: Iterable[str], errCause: str) → int

Lists stored layer styles in the provider defined by providerKey and uri

Return type:

int

Returns:

-1 if not implemented by provider, otherwise number of styles stored

New in version 3.10.

Parameters:

  • providerKey (str) –

  • uri (str) –

  • ids (Iterable[str]) –

  • names (Iterable[str]) –

  • descriptions (Iterable[str]) –

  • errCause (str) –

loadStoredStyle(self, providerKey: str, uri: str, styleName: str, errCause: str) → str

Loads a layer style from the provider storage, reporting its name.

Parameters:

  • providerKey (str) – name of the data provider

  • uri (str) – data source uri

  • styleName (str) – the name of the style if available, empty otherwise

  • errCause (str) – report errors

Return type:

str

Returns:

the style QML (XML)

New in version 3.30.

loadStyle(self, providerKey: str, uri: str, errCause: str) → str

Loads a layer style defined by uri

Return type:

str

Returns:

the style QML (XML)

New in version 3.10.

Parameters:

  • providerKey (str) –

  • uri (str) –

  • errCause (str) –

pluginList(self, asHtml: bool = False) → str

Returns list of provider plugins found

Parameters:

asHtml (bool = False) –

Return type:

str

preferredProvidersForUri(self, uri: str) → List[QgsProviderRegistry.ProviderCandidateDetails]

Returns the details for the preferred provider(s) for opening the specified uri.

The preferred provider is determined by comparing the priority returned by QgsProviderMetadata.priorityForUri() for all registered providers, and selecting the provider with the largest non-zero priority.

An empty list may be returned, which indicates that no providers are available which returned a non-zero priority for the specified URI.

In the case that multiple providers returned the same priority for the URI then all of these providers will be returned.

See also

shouldDeferUriForOtherProviders()

New in version 3.18.

Parameters:

uri (str) –

Return type:

List[QgsProviderRegistry.ProviderCandidateDetails]

protocolDrivers(self) → str

Returns a string containing the available protocol drivers

Return type:

str

providerCapabilities(self, providerKey: str) → int

Returns the provider capabilities

Parameters:

providerKey (str) – identifier of the provider

New in version 2.6.

Deprecated since version QGIS: 3.10 (use instead capabilities() method of individual data item provider)

Return type:

int

providerList(self) → List[str]

Returns list of available providers by their keys

Return type:

List[str]

providerMetadata(self, providerKey: str) → QgsProviderMetadata

Returns metadata of the provider or None if not found

Parameters:

providerKey (str) –

Return type:

QgsProviderMetadata

providersForLayerType(self, type: Qgis.LayerType) → Set[str]

Returns a list of the provider keys for available providers which handle the specified layer type.

New in version 3.26.

Parameters:

type (Qgis.LayerType) –

Return type:

Set[str]

pyramidResamplingMethods(self, providerKey: str) → List[Tuple[str, str]]

Returns list of raster pyramid resampling methods

New in version 3.10.

Parameters:

providerKey (str) –

Return type:

List[Tuple[str, str]]

querySublayers(self, uri: str, flags: Qgis.SublayerQueryFlags | Qgis.SublayerQueryFlag = Qgis.SublayerQueryFlags(), feedback: QgsFeedback = None) → List[QgsProviderSublayerDetails]

Queries the specified uri and returns a list of any valid sublayers found in the dataset which can be handled by any registered data provider.

This method iteratively queries each registered data provider and returns the complete collated list of all valid sublayers found in the dataset which can be opened by the data providers.

The optional flags argument can be used to control the behavior of the query.

The optional feedback argument can be used to provide cancellation support for long-running queries.

New in version 3.22.

Parameters:
Return type:

List[QgsProviderSublayerDetails]

registerGuis(self, widget: QWidget)

Deprecated since version QGIS: 3.10 - does nothing - use QgsGui.providerGuiRegistry()

Parameters:

widget (QWidget) –

registerProvider(self, providerMetadata: QgsProviderMetadata) → bool

register a new vector data provider from its providerMetadata

Return type:

bool

Returns:

True on success, False if a provider with the same key was already registered

Note

ownership of the QgsProviderMetadata instance is transferred to the registry

New in version 3.2.

Parameters:

providerMetadata (QgsProviderMetadata) –

registerUnusableUriHandler(self, handler: QgsProviderRegistry.UnusableUriHandlerInterface) → bool

Registers an unusable URI handler, used to handle unusable URIs which aren’t handled by any registered providers, and construct user-friendly warnings as to why the URI is unusable.

Return type:

bool

Returns:

True on success

Note

ownership of the UnusableUriHandlerInterface instance is transferred to the registry

New in version 3.18.1.

Parameters:

handler (QgsProviderRegistry.UnusableUriHandlerInterface) –

relativeToAbsoluteUri(self, providerKey: str, uri: str, context: QgsReadWriteContext) → str

Converts relative path(s) to absolute path(s) in the given provider-specific URI. and returns modified URI according to the context object’s configuration. This is commonly used when reading project files. If a provider does not work with paths, unmodified URI will be returned.

Return type:

str

Returns:

modified URI with absolute path(s)

Note

this function may not be supported by all providers. The default implementation uses QgsPathResolver.readPath() on the whole URI.

See also

absoluteToRelativeUri()

New in version 3.30.

Parameters:
saveLayerMetadata(self, providerKey: str, uri: str, metadata: QgsLayerMetadata) → Tuple[bool, str]

Saves metadata to the layer corresponding to the specified uri.

Parameters:

  • providerKey (str) – identifier of the provider

  • uri (str) – uri of layer to store metadata for

  • metadata (QgsLayerMetadata) – layer metadata

Return type:

Tuple[bool, str]

Returns:

  • True if the metadata was successfully saved.

  • errorMessage: descriptive string of error if encountered

Raises:

QgsNotSupportedException – if the provider does not support saving layer metadata for the specified uri.

New in version 3.20.

saveStyle(self, providerKey: str, uri: str, qmlStyle: str, sldStyle: str, styleName: str, styleDescription: str, uiFileContent: str, useAsDefault: bool, errCause: str) → bool

Saves a layer style to provider

New in version 3.10.

Parameters:

  • providerKey (str) –

  • uri (str) –

  • qmlStyle (str) –

  • sldStyle (str) –

  • styleName (str) –

  • styleDescription (str) –

  • uiFileContent (str) –

  • useAsDefault (bool) –

  • errCause (str) –

Return type:

bool

setLibraryDirectory(self, path: QDir)

Sets library directory where to search for plugins

Parameters:

path (QDir) –

shouldDeferUriForOtherProviders(self, uri: str, providerKey: str) → bool

Returns True if the provider with matching providerKey should defer handling of the specified uri to another provider.

This method tests whether any providers are listed as the preferred provider for uri (see preferredProvidersForUri()), and if so tests whether the specified provider is included in that preferred providers list. Returns True only if the specified provider is calculated as one of the preferred providers for the URI.

In the case that there is no registered preferred provider for the URI then False will be returned, and the provider must use another metric to determine whether it should handle the URI.

See also

preferredProvidersForUri()

New in version 3.18.

Parameters:

  • uri (str) –

  • providerKey (str) –

Return type:

bool

styleExists(self, providerKey: str, uri: str, styleId: str) → Tuple[bool, str]

Returns True if a layer style with the specified styleId exists in the provider defined by providerKey and uri.

Parameters:

  • providerKey (str) – provider key

  • uri (str) – provider URI

  • styleId (str) – style ID to test for

Return type:

Tuple[bool, str]

Returns:

  • True if the layer style already exists

  • errorCause: will be set to a descriptive error message, if an error occurs while checking if the style exists

See also

getStyleById()

New in version 3.24.

uriIsBlocklisted(self, uri: str) → bool

Returns True if the specified uri is known by any registered provider to be something which should be blocklisted from the QGIS interface, e.g. an internal detail only.

Specifically, this method can be utilized by the browser panel to hide noisy internal details for URIs which are known to be sidecar files only, such as “.aux.xml” files or “.shp.xml” files, or the “ept-build.json” files which sit alongside Entwine “ept.json” point cloud sources.

This method tests whether any of the registered providers return True for the their QgsProviderMetadata.uriIsBlocklisted() implementation for the specified URI.

New in version 3.18.

Parameters:

uri (str) –

Return type:

bool