Class: QgsExpressionContext

class qgis.core.QgsExpressionContext

Bases: sip.wrapper

Constructor for QgsExpressionContext

QgsExpressionContext(scopes: object) Initializes the context with given list of scopes. Ownership of the scopes is transferred to the stack.

New in version 3.0.

QgsExpressionContext(other: QgsExpressionContext) Copy constructor

Expression contexts are used to encapsulate the parameters around which a QgsExpression should be evaluated. QgsExpressions can then utilize the information stored within a context to contextualise their evaluated result. A QgsExpressionContext consists of a stack of QgsExpressionContextScope objects, where scopes added later to the stack will override conflicting variables and functions from scopes lower in the stack.

See QgsExpressionContextUtils for helper methods for working with QgsExpressionContext objects.

Methods

activeScopeForVariable

Returns the currently active scope from the context for a specified variable name.

appendScope

Appends a scope to the end of the context.

appendScopes

Appends a list of scopes to the end of the context.

cachedValue

Returns the matching cached value, if set.

clearCachedValues

Clears all cached values from the context.

description

Returns a translated description string for the variable with specified name.

feature

Convenience function for retrieving the feature for the context, if set.

fields

Convenience function for retrieving the fields for the context, if set.

filteredVariableNames

Returns a filtered list of variables names set by all scopes in the context.

function

Fetches a matching function from the context.

functionNames

Retrieves a list of function names contained in the context.

hasCachedValue

Returns true if the expression context contains a cached value with a matching key.

hasFeature

Returns true if the context has a feature associated with it.

hasFunction

Checks whether a specified function is contained in the context.

hasVariable

Check whether a variable is specified by any scope within the context.

indexOfScope

Returns the index of the specified scope if it exists within the context.

isHighlightedFunction

Returns true if the specified function name is intended to be highlighted to the user.

isHighlightedVariable

Returns true if the specified variable name is intended to be highlighted to the user.

isReadOnly

Returns whether a variable is read only, and should not be modifiable by users.

lastScope

Returns the last scope added to the context.

popScope

Removes the last scope from the expression context and return it.

scope

Returns the scope at the specified index within the context.

scopeCount

Returns the number of scopes contained in the context.

scopes

Returns a list of scopes contained within the stack.

setCachedValue

Sets a value to cache within the expression context.

setFeature

Convenience function for setting a feature for the context.

setFields

Convenience function for setting a fields for the context.

setHighlightedFunctions

Sets the list of function names intended to be highlighted to the user.

setHighlightedVariables

Sets the list of variable names within the context intended to be highlighted to the user.

setOriginalValueVariable

Sets the original value variable value for the context.

variable

Fetches a matching variable from the context.

variableNames

Returns a list of variables names set by all scopes in the context.

variablesToMap

Returns a map of variable name to value representing all the expression variables contained by the context.

Attributes

EXPR_CLUSTER_COLOR

EXPR_CLUSTER_SIZE

EXPR_FIELDS

EXPR_GEOMETRY_PART_COUNT

EXPR_GEOMETRY_PART_NUM

EXPR_GEOMETRY_POINT_COUNT

EXPR_GEOMETRY_POINT_NUM

EXPR_ORIGINAL_VALUE

EXPR_SYMBOL_ANGLE

EXPR_SYMBOL_COLOR

EXPR_CLUSTER_COLOR = 'cluster_color'
EXPR_CLUSTER_SIZE = 'cluster_size'
EXPR_FIELDS = '_fields_'
EXPR_GEOMETRY_PART_COUNT = 'geometry_part_count'
EXPR_GEOMETRY_PART_NUM = 'geometry_part_num'
EXPR_GEOMETRY_POINT_COUNT = 'geometry_point_count'
EXPR_GEOMETRY_POINT_NUM = 'geometry_point_num'
EXPR_ORIGINAL_VALUE = 'value'
EXPR_SYMBOL_ANGLE = 'symbol_angle'
EXPR_SYMBOL_COLOR = 'symbol_color'
activeScopeForVariable(self, name: str) → QgsExpressionContextScope

Returns the currently active scope from the context for a specified variable name. As scopes later in the stack override earlier contexts, this will be the last matching scope which contains a matching variable.

Parameters

name (str) – variable name

Return type

QgsExpressionContextScope

Returns

matching scope containing variable, or null if none found

appendScope(self, scope: QgsExpressionContextScope)

Appends a scope to the end of the context. This scope will override any matching variables or functions provided by existing scopes within the context. Ownership of the scope is transferred to the stack.

Parameters

scope (QgsExpressionContextScope) – expression context to append to context

appendScopes(self, scopes: Iterable[QgsExpressionContextScope])

Appends a list of scopes to the end of the context. This scopes will override any matching variables or functions provided by existing scopes within the context. Ownership of the scopes is transferred to the stack.

Parameters

scopes (Iterable[QgsExpressionContextScope]) – scopes to append to context

New in version 3.0.

cachedValue(self, key: str) → Any

Returns the matching cached value, if set. This can be used to retrieve the previously stored results of an expensive expression sub-calculation.

Parameters

key (str) – unique key used to store cached value

Return type

Any

Returns

matching cached value, or invalid QVariant if not set

See also

setCachedValue()

See also

hasCachedValue()

New in version 2.16.

clearCachedValues(self)

Clears all cached values from the context.

See also

setCachedValue()

See also

hasCachedValue()

See also

cachedValue()

New in version 2.16.

description(self, name: str) → str

Returns a translated description string for the variable with specified name.

If no specific description has been provided for the variable, the value from QgsExpression.variableHelpText() will be returned.

New in version 3.0.

Parameters

name (str) –

Return type

str

feature(self) → QgsFeature

Convenience function for retrieving the feature for the context, if set.

See also

setFeature()

Return type

QgsFeature

fields(self) → QgsFields

Convenience function for retrieving the fields for the context, if set.

See also

setFields()

Return type

QgsFields

filteredVariableNames(self) → List[str]

Returns a filtered list of variables names set by all scopes in the context. The included variables are those which should be seen by users.

Return type

List[str]

Returns

filtered list of unique variable names

See also

variableNames()

function(self, name: str) → QgsExpressionFunction

Fetches a matching function from the context. The function will be fetched from the last scope contained within the context which has a matching function set.

Parameters

name (str) – function name

Return type

QgsExpressionFunction

Returns

function if contained by the context, otherwise null.

See also

hasFunction()

functionNames(self) → List[str]

Retrieves a list of function names contained in the context.

See also

function()

See also

variableNames()

Return type

List[str]

hasCachedValue(self, key: str) → bool

Returns true if the expression context contains a cached value with a matching key.

Parameters

key (str) – unique key used to store cached value

See also

setCachedValue()

See also

cachedValue()

New in version 2.16.

Return type

bool

hasFeature(self) → bool

Returns true if the context has a feature associated with it.

See also

feature()

New in version 3.0.

Return type

bool

hasFunction(self, name: str) → bool

Checks whether a specified function is contained in the context.

Parameters

name (str) – function name

Return type

bool

Returns

true if context provides a matching function

See also

function()

hasVariable(self, name: str) → bool

Check whether a variable is specified by any scope within the context.

Parameters

name (str) – variable name

Return type

bool

Returns

true if variable is set

See also

variable()

See also

variableNames()

indexOfScope(self, scope: QgsExpressionContextScope) → int

Returns the index of the specified scope if it exists within the context.

Parameters

scope (QgsExpressionContextScope) – scope to find

Returns

index of scope, or -1 if scope was not found within the context.

indexOfScope(self, scopeName: str) -> int Returns the index of the first scope with a matching name within the context.

Parameters

scopeName – name of scope to find

Return type

int

Returns

index of scope, or -1 if scope was not found within the context.

New in version 3.0.

isHighlightedFunction(self, name: str) → bool

Returns true if the specified function name is intended to be highlighted to the user. This is used by the expression builder to more prominently display the function.

New in version 3.4.

Parameters

name (str) –

Return type

bool

isHighlightedVariable(self, name: str) → bool

Returns true if the specified variable name is intended to be highlighted to the user. This is used by the expression builder to more prominently display the variable.

Parameters

name (str) –

Return type

bool

isReadOnly(self, name: str) → bool

Returns whether a variable is read only, and should not be modifiable by users.

Parameters

name (str) – variable name

Return type

bool

Returns

true if variable is read only. Read only status will be taken from last matching scope which contains a matching variable.

lastScope(self) → QgsExpressionContextScope

Returns the last scope added to the context.

See also

scope()

Return type

QgsExpressionContextScope

popScope(self) → QgsExpressionContextScope

Removes the last scope from the expression context and return it.

Return type

QgsExpressionContextScope

scope(self, index: int) → QgsExpressionContextScope

Returns the scope at the specified index within the context.

Parameters

index (int) – index of scope

Return type

QgsExpressionContextScope

Returns

matching scope, or null if none found

See also

lastScope()

scopeCount(self) → int

Returns the number of scopes contained in the context.

Return type

int

scopes(self) → List[QgsExpressionContextScope]

Returns a list of scopes contained within the stack.

Return type

List[QgsExpressionContextScope]

Returns

list of pointers to scopes

setCachedValue(self, key: str, value: Any)

Sets a value to cache within the expression context. This can be used to cache the results of expensive expression sub-calculations, to speed up future evaluations using the same expression context.

Parameters
  • key (str) – unique key for retrieving cached value

  • value (Any) – value to cache

See also

hasCachedValue()

See also

cachedValue()

New in version 2.16.

setFeature(self, feature: QgsFeature)

Convenience function for setting a feature for the context. The feature will be set within the last scope of the context, so will override any existing features within the context.

Parameters

feature (QgsFeature) – feature for context

See also

feature()

setFields(self, fields: QgsFields)

Convenience function for setting a fields for the context. The fields will be set within the last scope of the context, so will override any existing fields within the context.

Parameters

fields (QgsFields) – fields for context

See also

fields()

setHighlightedFunctions(self, names: Iterable[str])

Sets the list of function names intended to be highlighted to the user. This is used by the expression builder to more prominently display these functions.

Note that these function names may include standard functions which are not functions specific to this context, and these standard functions will also be highlighted to users.

New in version 3.4.

Parameters

names (Iterable[str]) –

setHighlightedVariables(self, variableNames: Iterable[str])

Sets the list of variable names within the context intended to be highlighted to the user. This is used by the expression builder to more prominently display these variables.

Parameters

variableNames (Iterable[str]) – variable names to highlight

setOriginalValueVariable(self, value: Any)

Sets the original value variable value for the context.

Parameters

value (Any) – value for original value variable. This usually represents the an original widget value before any data defined overrides have been applied.

New in version 2.12.

variable(self, name: str) → Any

Fetches a matching variable from the context. The variable will be fetched from the last scope contained within the context which has a matching variable set.

Parameters

name (str) – variable name

Return type

Any

Returns

variable value if matching variable exists in the context, otherwise an invalid QVariant

See also

hasVariable()

See also

variableNames()

variableNames(self) → List[str]

Returns a list of variables names set by all scopes in the context.

Return type

List[str]

Returns

list of unique variable names

See also

functionNames()

See also

hasVariable()

See also

variable()

variablesToMap(self) → Dict[str, Any]

Returns a map of variable name to value representing all the expression variables contained by the context.

New in version 3.0.

Return type

Dict[str, Any]