Class: QgsAuxiliaryLayer¶

Allows managing the auxiliary storage for a vector layer.

Such auxiliary data are data used mostly for the needs of QGIS (symbology) and have no real interest in being stored with the native raw geospatial data.

The need arises from the restrictions existing in the manual placement of labels. Manual placement of labels are possible in QGIS by setting some labeling properties (X and Y position, and rotation angle optionally) as being “data-defined”, meaning that values come from a column (or an expression). But setting this up on an existing layer requires either to add new columns to the source layer, while it is not always possible or desirable.

This QgsAuxiliaryLayer provides the solution to this limitation. Actually it’s an editable join to the original vector layer with some synchronisation mechanisms activated such as “Upsert On Edit” or “Delete Cascade”. Thus, auxiliary fields are editable even if the source layer is not and edition of a joined field is also possible.

Note

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

The following methods must be implemented: QgsFeatureSink.addFeatures(), QgsExpressionContextGenerator.createExpressionContext(), QgsExpressionContextScopeGenerator.createExpressionContextScope(), QgsMapLayer.createMapRenderer(), QgsFeatureSource.featureCount(), QgsFeatureSource.fields(), QgsFeatureSource.getFeatures(), QgsMapLayer.readSymbology(), QgsFeatureSource.sourceCrs(), QgsFeatureSource.sourceName(), QgsFeatureSource.wkbType(), QgsMapLayer.writeSymbology()

Class Hierarchy¶

Base classes¶

`QgsVectorLayer`	Represents a vector layer which manages a vector based dataset.
`QgsMapLayer`	Base class for all map layer types.
QObject
`QgsExpressionContextGenerator`	Abstract interface for generating an expression context.
`QgsExpressionContextScopeGenerator`	Abstract interface for generating an expression context scope.
`QgsFeatureSink`	An interface for objects which accept features via addFeature(s) methods.
`QgsFeatureSource`	An interface for objects which provide features via a getFeatures method.
`QgsAbstractProfileSource`	Interface for classes which can generate elevation profiles.

Abstract Methods

clone

Returns a new instance equivalent to this one.

Methods

`addAuxiliaryField`	Adds an auxiliary field for the given property.
`auxiliaryFields`	Returns a list of all auxiliary fields currently managed by the layer.
`clear`	Deletes all features from the layer.
`exists`	Returns `True` if the property is stored in the layer already, `False` otherwise.
`indexOfPropertyDefinition`	Returns the index of the auxiliary field for a specific property definition.
`isHiddenProperty`	Returns `True` if the underlying field has to be hidden from editing tools like attribute table, `False` otherwise.
`joinInfo`	Returns information to use for joining with primary key and so on.
`propertyDefinitionFromIndex`	Returns the property definition for the underlying field index.
`propertyFromIndex`	Returns the underlying property key for the field index.
`save`	Commits changes and starts editing then.
`toSpatialLayer`	An auxiliary layer is not spatial.

Virtual Methods

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

deleteAttribute

Removes attribute from the layer and commits changes.

Static Methods

`createAuxiliaryField`	Creates a new auxiliary field from a property definition.
`createProperty`	Creates if necessary a new auxiliary field for a PAL property and activates this property in settings.
`nameFromProperty`	Returns the name of the auxiliary field for a property definition.
`propertyDefinitionFromField`	Returns the property definition from an auxiliary field.

class qgis.core.QgsAuxiliaryLayer[source]¶

Bases: QgsVectorLayer

__init__(pkField: str | None, filename: str | None, table: str | None, vlayer: QgsVectorLayer | None)

Constructor

Parameters:

pkField (Optional[str]) – The primary key to use for joining
filename (Optional[str]) – The database path
table (Optional[str]) – The table name
vlayer (Optional[QgsVectorLayer]) – The target vector layer in join definition

addAuxiliaryField(self, definition: QgsPropertyDefinition) → bool[source]¶

Adds an auxiliary field for the given property. Setup for widget editors are updated in the target layer as well as the attribute table config to hide auxiliary fields by default.

Parameters:: definition (QgsPropertyDefinition) – The definition of the property to add
Return type:: bool
Returns:: True if the auxiliary field is well added, False otherwise

auxiliaryFields(self) → QgsFields[source]¶

Returns a list of all auxiliary fields currently managed by the layer.

Return type:: QgsFields

clear(self) → bool[source]¶

Deletes all features from the layer. Changes are automatically committed and the layer remains editable.

Return type:: bool
Returns:: True if changes are committed without error, False otherwise.

abstract clone(self, layer: QgsVectorLayer | None) → QgsAuxiliaryLayer | None[source]¶

Returns a new instance equivalent to this one. The underlying table is duplicate for the layer given in parameter. Note that the current auxiliary layer should be saved to have a proper duplicated table.

Parameters:: layer (Optional[QgsVectorLayer]) – The layer for which the clone is made
Return type:: Optional[QgsAuxiliaryLayer]

static createAuxiliaryField(definition: QgsPropertyDefinition) → QgsField[source]¶

Creates a new auxiliary field from a property definition.

Parameters:: definition (QgsPropertyDefinition) – The property definition of the auxiliary field to create
Return type:: QgsField

static createAuxiliaryField(field: QgsField) → QgsField[source]

Creates a new auxiliary field from a field.

Parameters:: field (QgsField) – The field to use to create the auxiliary field
Return type:: QgsField

static createProperty(property: QgsPalLayerSettings.Property, vlayer: QgsVectorLayer | None, overwriteExisting: bool = True) → int[source]¶

Creates if necessary a new auxiliary field for a PAL property and activates this property in settings.

Parameters:

property (QgsPalLayerSettings.Property) – The property to create
vlayer (Optional[QgsVectorLayer]) – The vector layer
overwriteExisting (bool = True) – since QGIS 3.22, controls whether an existing property should be completely overwritten or upgraded to a coalesce(“new aux field”, ‘existing’ || ‘property’ || ‘expression’) type property

Return type:

int

Returns:

The index of the auxiliary field or -1

static createProperty(property: QgsDiagramLayerSettings.Property, vlayer: QgsVectorLayer | None, overwriteExisting: bool = True) → int[source]

Creates if necessary a new auxiliary field for a diagram’s property and activates this property in settings.

Parameters:

property (QgsDiagramLayerSettings.Property) – The property to create
vlayer (Optional[QgsVectorLayer]) – The vector layer
overwriteExisting (bool = True) – since QGIS 3.22, controls whether an existing property should be completely overwritten or upgraded to a coalesce(“new aux field”, ‘existing’ || ‘property’ || ‘expression’) type property

Return type:

int

Returns:

The index of the auxiliary field or -1

static createProperty(property: QgsCallout.Property, vlayer: QgsVectorLayer | None, overwriteExisting: bool = True) → int[source]

Creates if necessary a new auxiliary field for a callout’s property and activates this property in settings.

Parameters:

property (QgsCallout.Property) – The property to create
vlayer (Optional[QgsVectorLayer]) – The vector layer
overwriteExisting (bool = True) – since QGIS 3.22, controls whether an existing property should be completely overwritten or upgraded to a coalesce(“new aux field”, ‘existing’ || ‘property’ || ‘expression’) type property

Return type:

int

Returns:

The index of the auxiliary field or -1

Added in version 3.20.

virtual deleteAttribute(self, attr: int) → bool[source]¶

Removes attribute from the layer and commits changes. The layer remains editable.

Parameters:: attr (int) – The index of the attribute to remove
Return type:: bool
Returns:: True if the attribute is well deleted, False otherwise

exists(self, definition: QgsPropertyDefinition) → bool[source]¶

Returns True if the property is stored in the layer already, False otherwise.

Parameters:: definition (QgsPropertyDefinition) – The property definition to check
Return type:: bool
Returns:: True if the property is stored, False otherwise

indexOfPropertyDefinition(self, definition: QgsPropertyDefinition) → int[source]¶

Returns the index of the auxiliary field for a specific property definition.

Parameters:: definition (QgsPropertyDefinition) – The property definition
Return type:: int
Returns:: The index of the field corresponding to the property or -1

isHiddenProperty(self, index: int) → bool[source]¶

Returns True if the underlying field has to be hidden from editing tools like attribute table, False otherwise.

Parameters:: index (int) – The index of the field for which visibility is checked
Return type:: bool

joinInfo(self) → QgsVectorLayerJoinInfo[source]¶

Returns information to use for joining with primary key and so on.

Return type:: QgsVectorLayerJoinInfo

static nameFromProperty(def_: QgsPropertyDefinition, joined: bool = False) → str[source]¶

Returns the name of the auxiliary field for a property definition.

Parameters:

def (QgsPropertyDefinition) – The property definition
joined (bool = False) – The join prefix is taken into account if True
def

Return type:

str

static propertyDefinitionFromField(field: QgsField) → QgsPropertyDefinition[source]¶

Returns the property definition from an auxiliary field.

Parameters:: field (QgsField) – The auxiliary field
Return type:: QgsPropertyDefinition

propertyDefinitionFromIndex(self, index: int) → QgsPropertyDefinition[source]¶

Returns the property definition for the underlying field index.

Parameters:: index (int) – The index of the field
Return type:: QgsPropertyDefinition

propertyFromIndex(self, index: int) → int[source]¶

Returns the underlying property key for the field index. The key may be a PAL, diagram or symbology property according to the underlying property definition of the field. The key -1 is returned if an error happened.

Parameters:: index (int) – The index of the field
Return type:: int

save(self) → bool[source]¶

Commits changes and starts editing then.

Return type:: bool
Returns:: True if commit step passed, False otherwise

toSpatialLayer(self) → QgsVectorLayer | None[source]¶

An auxiliary layer is not spatial. This method returns a spatial representation of auxiliary data.

Return type:: Optional[QgsVectorLayer]
Returns:: A new spatial vector layer