Class: QgsDataProvider

Abstract base class for spatial data provider implementations.

Note

This is an abstract class, with methods which must be implemented by a subclass.

The following methods must be implemented: crs(), description(), extent(), isValid(), name()

Class Hierarchy

Base classes

QObject

Subclasses

QgsMeshDataProvider	Base class for providing data for QgsMeshLayer.
QgsPointCloudDataProvider	Base class for providing data for QgsPointCloudLayer.
QgsRasterDataProvider	Base class for raster data providers.
QgsTiledSceneDataProvider	Base class for data providers for QgsTiledSceneLayer.
QgsVectorDataProvider	Base class for vector data providers.

Enums

DataCapability	alias of DataItemProviderCapability
ReadFlag	alias of DataProviderReadFlag

Abstract Methods

crs	Returns the coordinate system for the data source.
description	Returns description
extent	Returns the extent of the layer.
isValid	Returns True if this is a valid layer.
name	Returns a provider name

Methods

appendError	Add error message
providerProperty	Gets the current value of a certain provider property.
setError	Sets error message
setProviderProperty	Allows setting arbitrary properties on the provider.
setUri	Set the data source specification.
uri	Gets the data source specification.

Virtual Methods

In PyQGIS, only methods marked as virtual can be safely overridden in a Python subclass of QgsDataProvider. See the FAQ for more details.

dataComment	Returns a short comment for the data that this provider is providing access to (e.g. the comment for postgres table).
dataSourceUri	Gets the data source specification.
dataTimestamp	Current time stamp of data source
elevationProperties	Returns the provider's elevation properties.
enterUpdateMode	Enter update mode.
error	Gets current status error.
extent3D	Returns the 3D extent of the layer.
fileRasterFilters	Returns raster file filter string
fileVectorFilters	Returns vector file filter string
flags	Returns the generic data provider flags.
htmlMetadata	Obtain a formatted HTML string containing assorted metadata for this data provider.
invalidateConnections	Invalidate connections corresponding to specified name
layerMetadata	Returns layer metadata collected from the provider's source.
leaveUpdateMode	Leave update mode.
reloadData	Reloads the data from the source for providers with data caches to synchronize, changes in the data source, feature counts and other specific actions.
setDataSourceUri	Set the data source specification.
setLayerOrder	Reorder the list of layer names to be rendered by this provider (in order from bottom to top)
setListening	Set whether the provider will listen to datasource notifications If set, the provider will issue notify signals.
setSubLayerVisibility	Set the visibility of the given sublayer name
setSubsetString	Set the subset string used to create a subset of features in the layer.
styleStorageCapabilities	Returns the style storage capabilities.
subLayerCount	Returns the number of layers for the current data source
subLayerStyles	Sub-layer styles for each sub-layer handled by this provider, in order from bottom to top
subLayers	Sub-layers handled by this provider, in order from bottom to top
subsetString	Returns the subset definition string currently in use by the layer and used by the provider to limit the feature set.
subsetStringDialect	Returns a user-friendly string describing the dialect which is supported for subset strings by the provider.
subsetStringHelpUrl	Returns a URL pointing to documentation describing the dialect which is supported for subset strings by the provider.
supportsSubsetString	Returns True if the provider supports setting of subset strings.
temporalCapabilities	Returns the provider's temporal capabilities.
timestamp	Time stamp of data source in the moment when data/metadata were loaded by provider
updateExtents	Update the extents of the layer.
writeLayerMetadata	Writes layer metadata to the underlying provider source.

Static Methods

sublayerSeparator

String sequence used for separating components of sublayers strings.

Signals

dataChanged	Emitted whenever a change is made to the data provider which may have caused changes in the provider's data OUTSIDE of QGIS.
fullExtentCalculated	Emitted whenever a deferred extent calculation is completed by the provider.
notify	Emitted when the datasource issues a notification.

Attributes

CustomData
EvaluateDefaultValues
SUBLAYER_SEPARATOR

class qgis.core.QgsDataProvider

Bases: QObject

__init__(uri: str | None = '', providerOptions: QgsDataProvider.ProviderOptions = QgsDataProvider.ProviderOptions(), flags: Qgis.DataProviderReadFlags | Qgis.DataProviderReadFlag = Qgis.DataProviderReadFlags())

Create a new dataprovider with the specified in the uri.

Additional creation options are specified within the options value and since QGIS 3.16 creation flags are specified within the flags value.

Parameters:

• uri (Optional[str] = '')

• providerOptions (QgsDataProvider.ProviderOptions = QgsDataProvider.ProviderOptions())

• flags (Union[Qgis.DataProviderReadFlags, Qgis.DataProviderReadFlag] = Qgis.DataProviderReadFlags())

CustomData = 3000

DataCapabilities

alias of DataItemProviderCapabilities

DataCapability

alias of DataItemProviderCapability

EvaluateDefaultValues = 0

class ProviderOptions

Bases: object

Setting options for creating vector data providers.

Note

coordinateTransformContext was added in QGIS 3.8

Added in version 3.2.

transformContext: QgsCoordinateTransformContext

Coordinate transform context

class ProviderProperty

Bases: int

ReadFlag

alias of DataProviderReadFlag

ReadFlags

alias of DataProviderReadFlags

SUBLAYER_SEPARATOR = '!!::!!'

appendError(self, message: QgsErrorMessage)

Add error message

Parameters:

message (QgsErrorMessage)

abstract crs(self) → QgsCoordinateReferenceSystem

Returns the coordinate system for the data source. If the provider isn’t capable of returning its projection then an invalid QgsCoordinateReferenceSystem will be returned.

Return type:

QgsCoordinateReferenceSystem

signal dataChanged

Emitted whenever a change is made to the data provider which may have caused changes in the provider’s data OUTSIDE of QGIS.

When emitted from a QgsVectorDataProvider, any cached information such as feature ids should be invalidated.

Warning

This signal is NOT emitted when changes are made to a provider from INSIDE QGIS – e.g. when adding features to a vector layer, deleting features or modifying existing features. Instead, the specific QgsVectorLayer signals should be used to detect these operations.

virtual dataComment(self) → str

Returns a short comment for the data that this provider is providing access to (e.g. the comment for postgres table).

Note

The default implementation returns an empty string.

Added in version 3.14.

Return type:

str

virtual dataSourceUri(self, expandAuthConfig: bool = False) → str

Gets the data source specification. This may be a path or database connection string

Parameters:

expandAuthConfig (bool = False) – Whether to expand any assigned authentication configuration

Return type:

str

Returns:

data source specification

Note

The default authentication configuration expansion is False. This keeps credentials out of layer data source URIs and project files. Expansion should be specifically done only when needed within a provider

virtual dataTimestamp(self) → QDateTime

Current time stamp of data source

Return type:

QDateTime

abstract description(self) → str

Returns description

Returns a terse string describing what the provider is.

Return type:

str

virtual elevationProperties(self) → QgsDataProviderElevationProperties | None

Returns the provider’s elevation properties.

This may be None, depending on the data provider.

Added in version 3.32.

Return type:

Optional[QgsDataProviderElevationProperties]

virtual enterUpdateMode(self) → bool

Enter update mode.

This is aimed at providers that can open differently the connection to the datasource, according it to be in update mode or in read-only mode. A call to this method shall be balanced with a call to leaveUpdateMode(), if this method returns True.

Most providers will have an empty implementation for that method.

For backward compatibility, providers that implement enterUpdateMode() should still make sure to allow editing operations to work even if enterUpdateMode() is not explicitly called.

Several successive calls to enterUpdateMode() can be done. So there is a concept of stack of calls that must be handled by the provider. Only the first call to enterUpdateMode() will really turn update mode on.

Return type:

bool

Returns:

True in case of success (or no-op implementation), False in case of failure.

virtual error(self) → QgsError

Gets current status error. This error describes some principal problem for which provider cannot work and thus is not valid. It is not last error after accessing data by block(), identify() etc.

Return type:

QgsError

abstract extent(self) → QgsRectangle

Returns the extent of the layer.

Warning

This may be expensive to calculate for some data providers, as it may involve additional network requests or in some cases, iterating through all the features in a layer. If the provider returns the Qgis.DataProviderFlag.FastExtent2D flag from the flags() method then the call to extent() is guaranteed to ALWAYS be fast and not involve any additional work.

Return type:

QgsRectangle

virtual extent3D(self) → QgsBox3D

Returns the 3D extent of the layer.

Warning

This may be expensive to calculate for some data providers, as it may involve additional network requests or in some cases, iterating through all the features in a layer. If the provider returns the Qgis.DataProviderFlag.FastExtent3D flag from the flags() method then the call to extent3D() is guaranteed to ALWAYS be fast and not involve any additional work.

Added in version 3.36.

Return type:

QgsBox3D

virtual fileRasterFilters(self) → str

Returns raster file filter string

Returns a string suitable for a QFileDialog of raster file formats supported by the data provider. Naturally this will be an empty string for those data providers that do not deal with plain files, such as databases and servers.

Return type:

str

virtual fileVectorFilters(self) → str

Returns vector file filter string

Returns a string suitable for a QFileDialog of vector file formats supported by the data provider. Naturally this will be an empty string for those data providers that do not deal with plain files, such as databases and servers.

Return type:

str

virtual flags(self) → Qgis.DataProviderFlags

Returns the generic data provider flags.

Added in version 3.26.

Return type:

Qgis.DataProviderFlags

signal fullExtentCalculated

Emitted whenever a deferred extent calculation is completed by the provider.

Layers should connect to this signal and update their cached extents whenever it is emitted.

virtual htmlMetadata(self) → str

Obtain a formatted HTML string containing assorted metadata for this data provider.

Added in version 3.36.

Return type:

str

virtual invalidateConnections(self, connection: str | None)

Invalidate connections corresponding to specified name

Parameters:

connection (Optional[str])

abstract isValid(self) → bool

Returns True if this is a valid layer. It is up to individual providers to determine what constitutes a valid layer.

Return type:

bool

virtual layerMetadata(self) → QgsLayerMetadata

Returns layer metadata collected from the provider’s source.

Individual data providers must implement this method if they support collecting metadata.

See also

writeLayerMetadata()

Return type:

QgsLayerMetadata

virtual leaveUpdateMode(self) → bool

Leave update mode.

This is aimed at providers that can open differently the connection to the datasource, according it to be in update mode or in read-only mode. This method shall be balanced with a successful call to enterUpdateMode().

Most providers will have an empty implementation for that method.

Several successive calls to enterUpdateMode() can be done. So there is a concept of stack of calls that must be handled by the provider. Only the last call to leaveUpdateMode() will really turn update mode off.

Return type:

bool

Returns:

True in case of success (or no-op implementation), False in case of failure.

abstract name(self) → str

Returns a provider name

Essentially just returns the provider key. Should be used to build file dialogs so that providers can be shown with their supported types. Thus if more than one provider supports a given format, the user is able to select a specific provider to open that file.

Return type:

str

signal notify(msg: str)

Emitted when the datasource issues a notification.

See also

setListening()

Parameters:

msg (str)

providerProperty(self, property: QgsDataProvider.ProviderProperty, defaultValue: Any = None) → Any

Gets the current value of a certain provider property. It depends on the provider which properties are supported.

Parameters:

• property (QgsDataProvider.ProviderProperty)

• defaultValue (Any = None)

Return type:

Any

virtual reloadData(self)

Reloads the data from the source for providers with data caches to synchronize, changes in the data source, feature counts and other specific actions. Emits the dataChanged signal

Note

only available for providers which implement the reloadProviderData() method.

virtual setDataSourceUri(self, uri: str | None)

Set the data source specification. This may be a path or database connection string

Parameters:

uri (Optional[str]) – source specification

setError(self, error: QgsError)

Sets error message

Parameters:

error (QgsError)

virtual setLayerOrder(self, layers: Iterable[str | None])

Reorder the list of layer names to be rendered by this provider (in order from bottom to top)

Note

layers must have been previously added.

Parameters:

layers (Iterable[Optional[str]])

virtual setListening(self, isListening: bool)

Set whether the provider will listen to datasource notifications If set, the provider will issue notify signals.

The default implementation does nothing.

See also

notify()

Parameters:

isListening (bool)

setProviderProperty(self, property: QgsDataProvider.ProviderProperty, value: Any)

Allows setting arbitrary properties on the provider. It depends on the provider which properties are supported.

Parameters:

• property (QgsDataProvider.ProviderProperty)

• value (Any)

virtual setSubLayerVisibility(self, name: str | None, vis: bool)

Set the visibility of the given sublayer name

Parameters:

• name (Optional[str])

• vis (bool)

virtual setSubsetString(self, subset: str | None, updateFeatureCount: bool = True) → bool

Set the subset string used to create a subset of features in the layer.

This may be a SQL where clause, or any other string that can be used by the data provider to create a subset. See subsetStringDialect() and subsetStringHelpUrl() for additional metadata on the dialect supported by the subset string.

Must be implemented in the data provider.

See also

subsetString()

See also

subsetStringDialect()

See also

subsetStringHelpUrl()

See also

supportsSubsetString()

Parameters:

• subset (Optional[str])

• updateFeatureCount (bool = True)

Return type:

bool

setUri(self, uri: QgsDataSourceUri)

Set the data source specification.

Parameters:

uri (QgsDataSourceUri)

setUri(self, uri: str | None)

Set the data source specification.

Added in version 3.38.

Parameters:

uri (Optional[str])

virtual styleStorageCapabilities(self) → Qgis.ProviderStyleStorageCapabilities

Returns the style storage capabilities.

Added in version 3.34.

Return type:

Qgis.ProviderStyleStorageCapabilities

virtual subLayerCount(self) → int

Returns the number of layers for the current data source

Return type:

int

virtual subLayerStyles(self) → List[str]

Sub-layer styles for each sub-layer handled by this provider, in order from bottom to top

Sub-layer styles are used to abstract the way the provider’s source can symbolise layers in some way at the server, before it serves them to the provider.

Return type:

List[str]

virtual subLayers(self) → List[str]

Sub-layers handled by this provider, in order from bottom to top

Sub-layers are used when the provider’s source can combine layers it knows about in some way before it hands them off to the provider.

See also

SUBLAYER_SEPARATOR

Return type:

List[str]

static sublayerSeparator() → str

String sequence used for separating components of sublayers strings.

Note

Replaces the static const SUBLAYER_SEPARATOR

See also

subLayers()

Added in version 3.12.

Return type:

str

virtual subsetString(self) → str

Returns the subset definition string currently in use by the layer and used by the provider to limit the feature set.

This may be a SQL where clause, or any other string that can be used by the data provider to create a subset. See subsetStringDialect() and subsetStringHelpUrl() for additional metadata on the dialect supported by the subset string.

Must be overridden in the data provider, otherwise returns an empty string.

See also

setSubsetString()

See also

subsetStringDialect()

See also

subsetStringHelpUrl()

See also

supportsSubsetString()

Return type:

str

virtual subsetStringDialect(self) → str

Returns a user-friendly string describing the dialect which is supported for subset strings by the provider.

See also

subsetStringHelpUrl()

See also

supportsSubsetString()

See also

setSubsetString()

See also

subsetString()

Added in version 3.40.

Return type:

str

virtual subsetStringHelpUrl(self) → str

Returns a URL pointing to documentation describing the dialect which is supported for subset strings by the provider.

See also

subsetStringDialect()

See also

supportsSubsetString()

See also

setSubsetString()

See also

subsetString()

Added in version 3.40.

Return type:

str

virtual supportsSubsetString(self) → bool

Returns True if the provider supports setting of subset strings.

See also

subsetString()

See also

setSubsetString()

Return type:

bool

virtual temporalCapabilities(self) → QgsDataProviderTemporalCapabilities | None

Returns the provider’s temporal capabilities.

This may be None, depending on the data provider.

Added in version 3.14.

Return type:

Optional[QgsDataProviderTemporalCapabilities]

virtual timestamp(self) → QDateTime

Time stamp of data source in the moment when data/metadata were loaded by provider

Return type:

QDateTime

virtual updateExtents(self)

Update the extents of the layer. Not implemented by default.

uri(self) → QgsDataSourceUri

Gets the data source specification.

Return type:

QgsDataSourceUri

virtual writeLayerMetadata(self, metadata: QgsLayerMetadata) → bool

Writes layer metadata to the underlying provider source. Support depends on individual provider capabilities.

Returns True if metadata was successfully written to the data provider.

See also

layerMetadata()

Parameters:

metadata (QgsLayerMetadata)

Return type:

bool