Class: QgsExpressionContextScope

class qgis.core.QgsExpressionContextScope

Bases: sip.wrapper

Single scope for storing variables and functions for use within a QgsExpressionContext. Examples include a project’s scope, which could contain information about the current project such as the project file’s location. QgsExpressionContextScope can encapsulate both variables (static values) and functions(which are calculated only when an expression is evaluated).

See QgsExpressionContextUtils for helper methods for working with QgsExpressionContextScope objects.

QgsExpressionContextScope(name: str = ‘’) Constructor for QgsExpressionContextScope

Parameters:

name – friendly display name for the context scope

QgsExpressionContextScope(other: QgsExpressionContextScope) Copy constructor

Methods

addFunction

Adds a function to the scope.

addHiddenVariable

Adds the passed variable to a list of hidden variables that won't be visible in the expression builder dialog and widget.

addLayerStore

Adds a layer store to the scope.

addVariable

Adds a variable into the context scope.

description

Returns the translated description for the variable with the specified name (if set).

feature

Sets the feature associated with the scope.

filteredVariableNames

Returns a filtered and sorted list of variable names contained within the scope.

function

Retrieves a function from the scope.

functionNames

Retrieves a list of names of functions contained in the scope.

geometry

Sets the geometry associated with the scope.

hasFeature

Returns True if the scope has a feature associated with it.

hasFunction

Tests whether a function with the specified name exists in the scope.

hasGeometry

Returns True if the scope has a geometry associated with it.

hasVariable

Tests whether a variable with the specified name exists in the scope.

hiddenVariables

Returns the list of variables hidden within the scope.

isReadOnly

Tests whether the specified variable is read only and should not be editable by users.

isStatic

Tests whether the variable with the specified name is static and can be cached.

layerStores

Returns the list of layer stores associated with the scope.

name

Returns the friendly display name of the context scope.

readXml

Reads scope variables from an XML element.

removeFeature

Removes any feature associated with the scope.

removeGeometry

Removes any geometry associated with the scope.

removeHiddenVariable

Removes the passed variable from a list of hidden variables.

removeVariable

Removes a variable from the context scope, if found.

setFeature

Convenience function for setting a feature for the scope.

setFields

Convenience function for setting a fields for the scope.

setGeometry

Convenience function for setting a geometry for the scope.

setHiddenVariables

Sets the list of variables intended to be hidden in the expression builder dialog and widget.

setVariable

Convenience method for setting a variable in the context scope by name name and value.

variable

Retrieves a variable's value from the scope.

variableCount

Returns the count of variables contained within the scope.

variableNames

Returns a list of variable names contained within the scope.

writeXml

Writes scope variables to an XML element.

class StaticVariable(name: str = '', value: Any = None, readOnly: bool = False, isStatic: bool = False, description: str = '')

Bases: sip.wrapper

Constructor for StaticVariable.

Parameters:
  • name – variable name (should be unique within the QgsExpressionContextScope)

  • value – initial variable value

  • readOnlyTrue if variable should not be editable by users

  • isStaticTrue if the variable will not change during the lifteime of an iterator.

  • description – optional translated description of variable, for use in expression builder widgets

QgsExpressionContextScope.StaticVariable(QgsExpressionContextScope.StaticVariable)

description
isStatic
name
readOnly
value
addFunction(self, name: str, function: QgsScopedExpressionFunction)

Adds a function to the scope.

Parameters:

See also

addVariable()

addHiddenVariable(self, hiddenVariable: str)

Adds the passed variable to a list of hidden variables that won’t be visible in the expression builder dialog and widget.

New in version 3.28.

Parameters:

hiddenVariable (str) –

addLayerStore(self, store: QgsMapLayerStore)

Adds a layer store to the scope.

Ownership of the store is not transferred to the scope, it is the caller’s responsibility to ensure that the store remains alive for the duration of the expression context.

See also

layerStores()

New in version 3.30.

Parameters:

store (QgsMapLayerStore) –

addVariable(self, variable: QgsExpressionContextScope.StaticVariable)

Adds a variable into the context scope. If a variable with the same name is already set then its value is overwritten, otherwise a new variable is added to the scope.

Parameters:

variable (QgsExpressionContextScope.StaticVariable) – definition of variable to insert

See also

setVariable()

See also

addFunction()

description(self, name: str) str

Returns the translated description for the variable with the specified name (if set).

Parameters:

name (str) –

Return type:

str

feature(self) QgsFeature

Sets the feature associated with the scope.

See also

setFeature()

See also

hasFeature()

Return type:

QgsFeature

filteredVariableNames(self) List[str]

Returns a filtered and sorted list of variable names contained within the scope. Hidden variable names will be excluded, and the list will be sorted so that read only variables are listed first.

See also

variableNames()

Return type:

List[str]

function(self, name: str) QgsExpressionFunction

Retrieves a function from the scope.

Parameters:

name (str) – function name

Return type:

QgsExpressionFunction

Returns:

function, or None if matching function could not be found

See also

hasFunction()

See also

functionNames()

See also

variable()

functionNames(self) List[str]

Retrieves a list of names of functions contained in the scope.

See also

function()

See also

variableNames()

Return type:

List[str]

geometry(self) QgsGeometry

Sets the geometry associated with the scope.

See also

setGeometry()

See also

hasGeometry()

New in version 3.24.

Return type:

QgsGeometry

hasFeature(self) bool

Returns True if the scope has a feature associated with it.

See also

feature()

Return type:

bool

hasFunction(self, name: str) bool

Tests whether a function with the specified name exists in the scope.

Parameters:

name (str) – function name

Return type:

bool

Returns:

True if matching function was found in the scope

See also

function()

See also

hasFunction()

hasGeometry(self) bool

Returns True if the scope has a geometry associated with it.

See also

geometry()

New in version 3.24.

Return type:

bool

hasVariable(self, name: str) bool

Tests whether a variable with the specified name exists in the scope.

Parameters:

name (str) – variable name

Return type:

bool

Returns:

True if matching variable was found in the scope

See also

variable()

See also

hasFunction()

hiddenVariables(self) List[str]

Returns the list of variables hidden within the scope.

New in version 3.28.

Return type:

List[str]

isReadOnly(self, name: str) bool

Tests whether the specified variable is read only and should not be editable by users.

Parameters:

name (str) – variable name

Return type:

bool

Returns:

True if variable is read only

isStatic(self, name: str) bool

Tests whether the variable with the specified name is static and can be cached.

Parameters:

name (str) –

Return type:

bool

layerStores(self) List[QgsMapLayerStore]

Returns the list of layer stores associated with the scope.

See also

addLayerStore()

New in version 3.30.

Return type:

List[QgsMapLayerStore]

name(self) str

Returns the friendly display name of the context scope.

Return type:

str

readXml(self, element: QDomElement, context: QgsReadWriteContext)

Reads scope variables from an XML element.

See also

writeXml()

New in version 3.6.

Parameters:
removeFeature(self)

Removes any feature associated with the scope.

See also

setFeature()

See also

hasFeature()

removeGeometry(self)

Removes any geometry associated with the scope.

See also

setGeometry()

See also

hasGeometry()

New in version 3.24.

removeHiddenVariable(self, hiddenVariable: str)

Removes the passed variable from a list of hidden variables.

New in version 3.28.

Parameters:

hiddenVariable (str) –

removeVariable(self, name: str) bool

Removes a variable from the context scope, if found.

Parameters:

name (str) – name of variable to remove

Return type:

bool

Returns:

True if variable was removed from the scope, False if matching variable was not found within the scope

setFeature(self, feature: QgsFeature)

Convenience function for setting a feature for the scope. Any existing feature set by the scope will be overwritten.

Parameters:

feature (QgsFeature) – feature for scope

See also

removeFeature()

See also

feature()

setFields(self, fields: QgsFields)

Convenience function for setting a fields for the scope. Any existing fields set by the scope will be overwritten.

Parameters:

fields (QgsFields) – fields for scope

setGeometry(self, geometry: QgsGeometry)

Convenience function for setting a geometry for the scope. Any existing geometry set by the scope will be overwritten.

See also

removeGeometry()

See also

geometry()

New in version 3.24.

Parameters:

geometry (QgsGeometry) –

setHiddenVariables(self, hiddenVariables: Iterable[str])

Sets the list of variables intended to be hidden in the expression builder dialog and widget.

New in version 3.28.

Parameters:

hiddenVariables (Iterable[str]) –

setVariable(self, name: str, value: Any, isStatic: bool = False)

Convenience method for setting a variable in the context scope by name name and value. If a variable with the same name is already set then its value is overwritten, otherwise a new variable is added to the scope. If the isStatic parameter is set to True, this variable can be cached during the execution of QgsExpression.prepare().

See also

addVariable()

Parameters:
  • name (str) –

  • value (Any) –

  • isStatic (bool = False) –

variable(self, name: str) Any

Retrieves a variable’s value from the scope.

Parameters:

name (str) – variable name

Return type:

Any

Returns:

variable value, or invalid QVariant if matching variable could not be found

See also

hasVariable()

See also

function()

variableCount(self) int

Returns the count of variables contained within the scope.

Return type:

int

variableNames(self) List[str]

Returns a list of variable names contained within the scope.

See also

functionNames()

Return type:

List[str]

writeXml(self, element: QDomElement, document: QDomDocument, context: QgsReadWriteContext) bool

Writes scope variables to an XML element.

See also

readXml()

New in version 3.6.

Parameters:
Return type:

bool