Subgroup: Expression
Class: QgsExpressionContext¶
-
class
qgis.core.
QgsExpressionContext
¶ Bases:
sip.wrapper
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.
New in version 2.12: 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. 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. 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
= '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 – variable name 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 – 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 – 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 – unique key used to store cached value Returns: matching cached value, or invalid QVariant if not set See also
See also
See also
New in version 2.16.
-
clearCachedValues
(self)¶ Clears all cached values from the context.
See also
See also
See also
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.
-
feature
(self) → QgsFeature¶ Convenience function for retrieving the feature for the context, if set.
See also
-
fields
(self) → QgsFields¶ Convenience function for retrieving the fields for the context, if set.
See also
-
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.
Returns: filtered list of unique variable names See also
-
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 – function name Returns: function if contained by the context, otherwise null. See also
-
functionNames
(self) → List[str]¶ Retrieves a list of function names contained in the context.
See also
See also
-
hasCachedValue
(self, key: str) → bool¶ Returns true if the expression context contains a cached value with a matching key.
Parameters: key – unique key used to store cached value See also
See also
See also
New in version 2.16.
-
hasFeature
(self) → bool¶ Returns true if the context has a feature associated with it.
New in version 3.0.
See also
-
hasFunction
(self, name: str) → bool¶ Checks whether a specified function is contained in the context.
Parameters: name – function name Returns: true if context provides a matching function See also
-
hasVariable
(self, name: str) → bool¶ Check whether a variable is specified by any scope within the context.
Parameters: name – variable name Returns: true if variable is set See also
See also
-
indexOfScope
(self, scope: QgsExpressionContextScope) → int¶ Returns the index of the specified scope if it exists within the context.
Parameters: scope – 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 Returns: index of scope, or -1 if scope was not found within the context. New in version 3.0.
-
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 – variable name See also
-
isReadOnly
(self, name: str) → bool¶ Returns whether a variable is read only, and should not be modifiable by users.
Parameters: name – variable name 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
-
popScope
(self) → QgsExpressionContextScope¶ Removes the last scope from the expression context and return it.
-
scope
(self, index: int) → QgsExpressionContextScope¶ Returns the scope at the specified index within the context.
Parameters: index – index of scope Returns: matching scope, or null if none found See also
-
scopeCount
(self) → int¶ Returns the number of scopes contained in the context.
-
scopes
(self) → List[QgsExpressionContextScope]¶ Returns a list of scopes contained within the stack.
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 – unique key for retrieving cached value
- value – value to cache
See also
See also
See also
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 – feature for context See also
-
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 – fields for context See also
-
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 – variable names to highlight See also
-
setOriginalValueVariable
(self, value: Any)¶ Sets the original value variable value for the context.
Parameters: value – 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 – variable name Returns: variable value if matching variable exists in the context, otherwise an invalid QVariant See also
See also
-
variableNames
(self) → List[str]¶ Returns a list of variables names set by all scopes in the context.
Returns: list of unique variable names See also
See also
See also
See also
-
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.
-