Class: QgsExpressionContextUtils

class qgis.core.QgsExpressionContextUtils

Bases: sip.wrapper

Contains utilities for working with QgsExpressionContext objects, including methods for creating scopes for specific uses (e.g., project scopes, layer scopes).

Added in version 2.12:

Methods

atlasScope

Creates a new scope which contains variables and functions relating to a QgsLayoutAtlas.

createFeatureBasedContext

Helper function for creating an expression context which contains just a feature and fields collection.

formScope

Creates a new scope which contains functions and variables from the current attribute form/table formFeature.

globalProjectLayerScopes

Creates a list of three scopes: global, layer's project and layer.

globalScope

Creates a new scope which contains variables and functions relating to the global QGIS context.

layerScope

Creates a new scope which contains variables and functions relating to a QgsMapLayer.

layoutItemScope

Creates a new scope which contains variables and functions relating to a QgsLayoutItem.

layoutScope

Creates a new scope which contains variables and functions relating to a QgsLayout layout.

mapLayerPositionScope

Sets the expression context variables which are available for expressions triggered by moving the mouse over a feature of the currently selected layer.

mapSettingsScope

Creates a new scope which contains variables and functions relating to a QgsMapSettings object.

mapToolCaptureScope

Sets the expression context variables which are available for expressions triggered by a map tool capture like add feature.

meshExpressionScope

Creates a new scope which contains functions relating to mesh layer element elementType

multiFrameScope

Creates a new scope which contains variables and functions relating to a QgsLayoutMultiFrame.

notificationScope

Creates a new scope which contains variables and functions relating to provider notifications

parentFormScope

Creates a new scope which contains functions and variables from the current parent attribute form/table formFeature.

processingAlgorithmScope

Creates a new scope which contains variables and functions relating to a processing algorithm, when used with the specified parameters and context.

processingModelAlgorithmScope

Creates a new scope which contains variables and functions relating to a processing model algorithm, when used with the specified parameters and context.

projectScope

Creates a new scope which contains variables and functions relating to a QGIS project.

registerContextFunctions

Registers all known core functions provided by QgsExpressionContextScope objects.

removeGlobalVariable

Remove a global context variable.

removeProjectVariable

Remove project context variable.

setGlobalVariable

Sets a global context variable.

setGlobalVariables

Sets all global context variables.

setLayerVariable

Sets a layer context variable.

setLayerVariables

Sets all layer context variables.

setLayoutItemVariable

Sets a layout item context variable, with the given name and value.

setLayoutItemVariables

Sets all layout item context variables for an item.

setLayoutMultiFrameVariable

Sets a layout multi frame context variable, with the given name and value.

setLayoutMultiFrameVariables

Sets all layout multiframe context variables for an frame.

setLayoutVariable

Sets a layout context variable.

setLayoutVariables

Sets all layout context variables.

setProjectVariable

Sets a project context variable.

setProjectVariables

Sets all project context variables.

updateSymbolScope

Updates a symbol scope related to a QgsSymbol to an expression context.
atlasScope(atlas: QgsLayoutAtlas | None) → QgsExpressionContextScope | None

Creates a new scope which contains variables and functions relating to a QgsLayoutAtlas. For instance, current page name and number.

Parameters:

atlas (Optional[QgsLayoutAtlas]) – source atlas. If None, a set of default atlas variables will be added to the scope.

Return type:

Optional[QgsExpressionContextScope]

createFeatureBasedContext(feature: QgsFeature, fields: QgsFields) → QgsExpressionContext

Helper function for creating an expression context which contains just a feature and fields collection. Generally this method should not be used as the created context does not include standard scopes such as the global and project scopes.

Parameters:
Return type:

QgsExpressionContext

formScope(formFeature: QgsFeature = QgsFeature(), formMode: str | None = '') → QgsExpressionContextScope | None

Creates a new scope which contains functions and variables from the current attribute form/table formFeature. The variables and values in this scope will reflect the current state of the form/row being edited. The formMode (SingleEditMode etc.) is passed as text

Added in version 3.2.

Parameters:

  • formFeature (QgsFeature = QgsFeature())

  • formMode (Optional[str] = '')

Return type:

Optional[QgsExpressionContextScope]

globalProjectLayerScopes(layer: QgsMapLayer | None) → List[QgsExpressionContextScope]

Creates a list of three scopes: global, layer’s project and layer.

Added in version 3.0.

Parameters:

layer (Optional[QgsMapLayer])

Return type:

List[QgsExpressionContextScope]

globalScope() → QgsExpressionContextScope | None

Creates a new scope which contains variables and functions relating to the global QGIS context. For instance, QGIS version numbers and variables specified through QGIS options.

See also

setGlobalVariable()

Return type:

Optional[QgsExpressionContextScope]

layerScope(layer: QgsMapLayer | None) → QgsExpressionContextScope | None

Creates a new scope which contains variables and functions relating to a QgsMapLayer. For instance, layer name, id and fields.

Parameters:

layer (Optional[QgsMapLayer])

Return type:

Optional[QgsExpressionContextScope]

layoutItemScope(item: QgsLayoutItem | None) → QgsExpressionContextScope | None

Creates a new scope which contains variables and functions relating to a QgsLayoutItem. For instance, item size and position.

See also

setLayoutItemVariable()

See also

setLayoutItemVariables()

Added in version 3.0.

Parameters:

item (Optional[QgsLayoutItem])

Return type:

Optional[QgsExpressionContextScope]

layoutScope(layout: QgsLayout | None) → QgsExpressionContextScope | None

Creates a new scope which contains variables and functions relating to a QgsLayout layout. For instance, number of pages and page sizes.

Added in version 3.0.

Parameters:

layout (Optional[QgsLayout])

Return type:

Optional[QgsExpressionContextScope]

mapLayerPositionScope(position: QgsPointXY) → QgsExpressionContextScope | None

Sets the expression context variables which are available for expressions triggered by moving the mouse over a feature of the currently selected layer.

Parameters:

position (QgsPointXY) – map coordinates of the current pointer position in the CRS of the layer which triggered the action.

Added in version 3.30.

Return type:

Optional[QgsExpressionContextScope]

mapSettingsScope(mapSettings: QgsMapSettings) → QgsExpressionContextScope | None

Creates a new scope which contains variables and functions relating to a QgsMapSettings object. For instance, map scale and rotation.

Parameters:

mapSettings (QgsMapSettings)

Return type:

Optional[QgsExpressionContextScope]

mapToolCaptureScope(matches: Iterable[QgsPointLocator.Match]) → QgsExpressionContextScope | None

Sets the expression context variables which are available for expressions triggered by a map tool capture like add feature.

Added in version 3.0.

Parameters:

matches (Iterable[QgsPointLocator.Match])

Return type:

Optional[QgsExpressionContextScope]

meshExpressionScope(elementType: QgsMesh.ElementType) → QgsExpressionContextScope | None

Creates a new scope which contains functions relating to mesh layer element elementType

Added in version 3.22.

Parameters:

elementType (QgsMesh.ElementType)

Return type:

Optional[QgsExpressionContextScope]

multiFrameScope(frame: QgsLayoutMultiFrame | None) → QgsExpressionContextScope | None

Creates a new scope which contains variables and functions relating to a QgsLayoutMultiFrame.

See also

setLayoutMultiFrameVariable()

See also

setLayoutMultiFrameVariables()

Added in version 3.10.

Parameters:

frame (Optional[QgsLayoutMultiFrame])

Return type:

Optional[QgsExpressionContextScope]

notificationScope(message: str | None = '') → QgsExpressionContextScope | None

Creates a new scope which contains variables and functions relating to provider notifications

Parameters:

message (Optional[str] = '') – the notification message

Return type:

Optional[QgsExpressionContextScope]

parentFormScope(formFeature: QgsFeature = QgsFeature(), formMode: str | None = '') → QgsExpressionContextScope | None

Creates a new scope which contains functions and variables from the current parent attribute form/table formFeature. The variables and values in this scope will reflect the current state of the parent form/row being edited. The formMode (SingleEditMode etc.) is passed as text

Added in version 3.14.

Parameters:

  • formFeature (QgsFeature = QgsFeature())

  • formMode (Optional[str] = '')

Return type:

Optional[QgsExpressionContextScope]

processingAlgorithmScope(algorithm: QgsProcessingAlgorithm | None, parameters: Dict[str, Any], context: QgsProcessingContext) → QgsExpressionContextScope | None

Creates a new scope which contains variables and functions relating to a processing algorithm, when used with the specified parameters and context. For instance, algorithm name and parameter functions.

See also

processingModelAlgorithmScope()

Parameters:
Return type:

Optional[QgsExpressionContextScope]

processingModelAlgorithmScope(model: QgsProcessingModelAlgorithm | None, parameters: Dict[str, Any], context: QgsProcessingContext) → QgsExpressionContextScope | None

Creates a new scope which contains variables and functions relating to a processing model algorithm, when used with the specified parameters and context. For instance, model name and path variables.

Added in version 3.6.

Parameters:
Return type:

Optional[QgsExpressionContextScope]

projectScope(project: QgsProject | None) → QgsExpressionContextScope | None

Creates a new scope which contains variables and functions relating to a QGIS project. For instance, project path and title, and variables specified through the project properties.

Parameters:

project (Optional[QgsProject]) – What project to use

See also

setProjectVariable()

Return type:

Optional[QgsExpressionContextScope]

registerContextFunctions()

Registers all known core functions provided by QgsExpressionContextScope objects.

removeGlobalVariable(name: str | None)

Remove a global context variable.

Parameters:

name (Optional[str]) – variable name

See also

setGlobalVariable()

See also

setGlobalVariables()

See also

globalScope()

removeProjectVariable(project: QgsProject | None, name: str | None)

Remove project context variable.

Parameters:

  • project (Optional[QgsProject]) – Project to apply changes to

  • name (Optional[str]) – variable name

See also

setProjectVariable()

See also

setProjectVariables()

See also

projectScope()

setGlobalVariable(name: str | None, value: Any)

Sets a global context variable. This variable will be contained within scopes retrieved via globalScope().

Parameters:

  • name (Optional[str]) – variable name

  • value (Any) – variable value

See also

setGlobalVariable()

See also

globalScope()

See also

removeGlobalVariable()

setGlobalVariables(variables: Dict[str, Any])

Sets all global context variables. Existing global variables will be removed and replaced with the variables specified.

Parameters:

variables (Dict[str) – new set of global variables

See also

setGlobalVariable()

See also

globalScope()

See also

removeGlobalVariable()

setLayerVariable(layer: QgsMapLayer | None, name: str | None, value: Any)

Sets a layer context variable. This variable will be contained within scopes retrieved via layerScope().

Parameters:

  • layer (Optional[QgsMapLayer]) – map layer

  • name (Optional[str]) – variable name

  • value (Any) – variable value

See also

setLayerVariables()

See also

layerScope()

setLayerVariables(layer: QgsMapLayer | None, variables: Dict[str, Any])

Sets all layer context variables. Existing layer variables will be removed and replaced with the variables specified.

Parameters:

  • layer (Optional[QgsMapLayer]) – map layer

  • variables (Dict[str) – new set of layer variables

See also

setLayerVariable()

See also

layerScope()

setLayoutItemVariable(item: QgsLayoutItem | None, name: str | None, value: Any)

Sets a layout item context variable, with the given name and value. This variable will be contained within scopes retrieved via layoutItemScope().

See also

setLayoutItemVariables()

See also

layoutItemScope()

Added in version 3.0.

Parameters:

  • item (Optional[QgsLayoutItem])

  • name (Optional[str])

  • value (Any)

setLayoutItemVariables(item: QgsLayoutItem | None, variables: Dict[str, Any])

Sets all layout item context variables for an item. Existing variables will be removed and replaced with the variables specified.

See also

setLayoutItemVariable()

See also

layoutItemScope()

Added in version 3.0.

Parameters:
setLayoutMultiFrameVariable(frame: QgsLayoutMultiFrame | None, name: str | None, value: Any)

Sets a layout multi frame context variable, with the given name and value. This variable will be contained within scopes retrieved via multiFrameScope().

See also

setLayoutItemVariables()

See also

multiFrameScope()

Added in version 3.10.

Parameters:
setLayoutMultiFrameVariables(frame: QgsLayoutMultiFrame | None, variables: Dict[str, Any])

Sets all layout multiframe context variables for an frame. Existing variables will be removed and replaced with the variables specified.

See also

setLayoutMultiFrameVariable()

See also

multiFrameScope()

Added in version 3.10.

Parameters:
setLayoutVariable(layout: QgsLayout | None, name: str | None, value: Any)

Sets a layout context variable. This variable will be contained within scopes retrieved via layoutScope().

Parameters:

  • layout (Optional[QgsLayout]) – target layout

  • name (Optional[str]) – variable name

  • value (Any) – variable value

See also

setLayoutVariables()

See also

layoutScope()

Added in version 3.0.

setLayoutVariables(layout: QgsLayout | None, variables: Dict[str, Any])

Sets all layout context variables. Existing layout variables will be removed and replaced with the variables specified.

Parameters:

  • layout (Optional[QgsLayout]) – target layout

  • variables (Dict[str) – new set of layer variables

See also

setLayoutVariable()

See also

layoutScope()

Added in version 3.0.

setProjectVariable(project: QgsProject | None, name: str | None, value: Any)

Sets a project context variable. This variable will be contained within scopes retrieved via projectScope().

Parameters:

  • project (Optional[QgsProject]) – Project to apply changes to

  • name (Optional[str]) – variable name

  • value (Any) – variable value

See also

setProjectVariables()

See also

removeProjectVariable()

See also

projectScope()

setProjectVariables(project: QgsProject | None, variables: Dict[str, Any])

Sets all project context variables. Existing project variables will be removed and replaced with the variables specified.

Parameters:

  • project (Optional[QgsProject]) – Project to apply changes to

  • variables (Dict[str) – new set of project variables

See also

setProjectVariable()

See also

removeProjectVariable()

See also

projectScope()

updateSymbolScope(symbol: QgsSymbol | None, symbolScope: QgsExpressionContextScope | None = None) → QgsExpressionContextScope | None

Updates a symbol scope related to a QgsSymbol to an expression context.

Parameters:

Added in version 2.14.

Return type:

Optional[QgsExpressionContextScope]