Class: QgsExpressionContextScope¶

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.

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 qgis.core.QgsExpressionContextScope[source]¶

Bases: object

__init__(name: str | None = '')

Constructor for QgsExpressionContextScope

Parameters:: name (Optional[str] = '') – friendly display name for the context scope

__init__(other: QgsExpressionContextScope)

Parameters:: other (QgsExpressionContextScope)

class StaticVariable¶

Bases: object

Single variable definition for use within a QgsExpressionContextScope.

description: str¶: Translated description of variable, for use within expression builder widgets.

isStatic: bool¶: A static variable can be cached for the lifetime of a context

name: str¶: Variable name

readOnly: bool¶: True if variable should not be editable by users

value: object¶: Variable value

addFunction(self, name: str | None, function: QgsScopedExpressionFunction | None)[source]¶

Adds a function to the scope.

Parameters:

name (Optional[str]) – function name
function (Optional[QgsScopedExpressionFunction]) – function to insert. Ownership is transferred to the scope.

See also

addVariable()

addHiddenVariable(self, hiddenVariable: str | None)[source]¶

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

See also

hiddenVariables()

See also

setHiddenVariables()

See also

removeHiddenVariable()

Added in version 3.28.

Parameters:: hiddenVariable (Optional[str])

addLayerStore(self, store: QgsMapLayerStore | None)[source]¶

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()

Added in version 3.30.

Parameters:: store (Optional[QgsMapLayerStore])

addVariable(self, variable: QgsExpressionContextScope.StaticVariable)[source]¶

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 | None) → str[source]¶

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

Parameters:: name (Optional[str])
Return type:: str

feature(self) → QgsFeature[source]¶

Sets the feature associated with the scope.

See also

setFeature()

See also

hasFeature()

Return type:: QgsFeature

filteredVariableNames(self) → List[str][source]¶

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 | None) → QgsExpressionFunction | None[source]¶

Retrieves a function from the scope.

Parameters:: name (Optional[str]) – function name
Return type:: Optional[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][source]¶

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

See also

function()

See also

variableNames()

Return type:: List[str]

geometry(self) → QgsGeometry[source]¶

Sets the geometry associated with the scope.

See also

setGeometry()

See also

hasGeometry()

Added in version 3.24.

Return type:: QgsGeometry

hasFeature(self) → bool[source]¶

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

See also

feature()

Return type:: bool

hasFunction(self, name: str | None) → bool[source]¶

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

Parameters:: name (Optional[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[source]¶

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

See also

geometry()

Added in version 3.24.

Return type:: bool

hasVariable(self, name: str | None) → bool[source]¶

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

Parameters:: name (Optional[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][source]¶

Returns the list of variables hidden within the scope.

See also

setHiddenVariables()

See also

addHiddenVariable()

See also

removeHiddenVariable()

Added in version 3.28.

Return type:: List[str]

isReadOnly(self, name: str | None) → bool[source]¶

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

Parameters:: name (Optional[str]) – variable name
Return type:: bool
Returns:: True if variable is read only

isStatic(self, name: str | None) → bool[source]¶

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

Parameters:: name (Optional[str])
Return type:: bool

layerStores(self) → List[QgsMapLayerStore]¶

Returns the list of layer stores associated with the scope.

See also

addLayerStore()

Added in version 3.30.

Return type:: List[QgsMapLayerStore]

name(self) → str[source]¶

Returns the friendly display name of the context scope.

Return type:: str

readXml(self, element: QDomElement, context: QgsReadWriteContext)[source]¶

Reads scope variables from an XML element.

See also

writeXml()

Added in version 3.6.

Parameters:

element (QDomElement)
context (QgsReadWriteContext)

removeFeature(self)[source]¶: Removes any feature associated with the scope.

See also

setFeature()

See also

hasFeature()

removeGeometry(self)[source]¶: Removes any geometry associated with the scope.

See also

setGeometry()

See also

hasGeometry()

Added in version 3.24.

removeHiddenVariable(self, hiddenVariable: str | None)[source]¶

Removes the passed variable from a list of hidden variables.

See also

hiddenVariables()

See also

setHiddenVariables()

See also

addHiddenVariable()

Added in version 3.28.

Parameters:: hiddenVariable (Optional[str])

removeVariable(self, name: str | None) → bool[source]¶

Removes a variable from the context scope, if found.

Parameters:: name (Optional[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)[source]¶

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)[source]¶

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)[source]¶

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()

Added in version 3.24.

Parameters:: geometry (QgsGeometry)

setHiddenVariables(self, hiddenVariables: Iterable[str | None])[source]¶

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

See also

hiddenVariables()

See also

addHiddenVariable()

See also

removeHiddenVariable()

Added in version 3.28.

Parameters:: hiddenVariables (Iterable[Optional[str]])

setVariable(self, name: str | None, value: Any, isStatic: bool = False)[source]¶

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 (Optional[str])
value (Any)
isStatic (bool = False)

variable(self, name: str | None) → Any[source]¶

Retrieves a variable’s value from the scope.

Parameters:: name (Optional[str]) – variable name
Return type:: Any
Returns:: variable value, or invalid QVariant if matching variable could not be found