Class: QgsExpressionContextScope

class qgis.core.QgsExpressionContextScope(name: str = '')

Bases: sip.wrapper

Constructor for QgsExpressionContextScope

Parameters

name (str = '') – friendly display name for the context scope

QgsExpressionContextScope(other: QgsExpressionContextScope) Copy constructor

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.

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.

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.

hasVariable

Tests whether a variable with the specified name exists in 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.

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.

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.

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 (str = '') – variable name (should be unique within the QgsExpressionContextScope)

  • value (Any = None) – initial variable value

  • readOnly (bool = False) – True if variable should not be editable by users

  • isStatic (bool = False) – True if the variable will not change during the lifteime of an iterator.

  • description (str = '') – 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()

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

New in version 3.0.

Parameters

name (str) –

Return type

str

feature(self) → QgsFeature

Sets the feature associated with the scope.

See also

setFeature()

See also

hasFeature()

New in version 3.0.

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]

hasFeature(self) → bool

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

See also

feature()

New in version 3.0.

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

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

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.

New in version 3.0.

Parameters

name (str) –

Return type

bool

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

New in version 3.0.

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

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