Class: QgsExpressionContext¶
- class qgis.core.QgsExpressionContext¶
Bases:
sip.wrapper
Constructor for QgsExpressionContext
QgsExpressionContext(scopes: Iterable[QgsExpressionContextScope]) 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 constructorExpression 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. AQgsExpressionContext
consists of a stack ofQgsExpressionContextScope
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 withQgsExpressionContext
objects.Methods
Returns the currently active scope from the context for a specified variable name.
Appends a scope to the end of the context.
Appends a list of scopes to the end of the context.
Returns the matching cached value, if set.
Clears all cached values from the context.
Returns a translated description string for the variable with specified
name
.Convenience function for retrieving the feature for the context, if set.
Convenience function for retrieving the fields for the context, if set.
Returns a filtered list of variables names set by all scopes in the context.
Fetches a matching function from the context.
Retrieves a list of function names contained in the context.
Returns
True
if the expression context contains a cached value with a matching key.Returns
True
if the context has a feature associated with it.Checks whether a specified function is contained in the context.
Check whether a variable is specified by any scope within the context.
Returns the current list of variables highlighted within the context.
Returns the index of the specified scope if it exists within the context.
Returns
True
if the specified functionname
is intended to be highlighted to the user.Returns
True
if the specified variablename
is intended to be highlighted to the user.Returns whether a variable is read only, and should not be modifiable by users.
Returns the last scope added to the context.
Removes the last scope from the expression context and return it.
Returns the scope at the specified index within the context.
Returns the number of scopes contained in the context.
Returns a list of scopes contained within the stack.
Sets a value to cache within the expression context.
Convenience function for setting a feature for the context.
Convenience function for setting a fields for the context.
Sets the list of function
names
intended to be highlighted to the user.Sets the list of variable names within the context intended to be highlighted to the user.
Sets the original value variable value for the context.
Fetches a matching variable from the context.
Returns a list of variables names set by all scopes in the context.
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 (str) – variable name
- Return type
- Returns
matching scope containing variable, or
None
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
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.
- Parameters
name (str) –
- Return type
str
- feature(self) → QgsFeature¶
Convenience function for retrieving the feature for the context, if set.
See also
- Return type
- fields(self) → QgsFields¶
Convenience function for retrieving the fields for the context, if set.
See also
- Return type
- 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
- 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
- Returns
function if contained by the context, otherwise
None
.
See also
- functionNames(self) → List[str]¶
Retrieves a list of function names contained in the context.
See also
See also
- 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
See also
See also
New in version 2.16.
- Return type
bool
- hasFeature(self) → bool¶
Returns
True
if the context has a feature associated with it.See also
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
- 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
See also
- highlightedVariables(self) → List[str]¶
Returns the current list of variables highlighted within the context.
See also
New in version 3.8.
- Return type
List[str]
- 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 functionname
is intended to be highlighted to the user. This is used by the expression builder to more prominently display the function.See also
See also
New in version 3.4.
- Parameters
name (str) –
- Return type
bool
- isHighlightedVariable(self, name: str) → bool¶
Returns
True
if the specified variablename
is intended to be highlighted to the user. This is used by the expression builder to more prominently display the variable.See also
See also
- 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
- Return type
- popScope(self) → QgsExpressionContextScope¶
Removes the last scope from the expression context and return it.
- Return type
- scope(self, index: int) → QgsExpressionContextScope¶
Returns the scope at the specified index within the context.
- Parameters
index (int) – index of scope
- Return type
- Returns
matching scope, or
None
if none found
See also
- 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
- 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
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 (QgsFeature) – 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 (QgsFields) – fields for context
See also
- 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.
See also
See also
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
See also
See also
- setOriginalValueVariable(self, value: Any)¶
Sets the original value variable value for the context.
- Parameters
value (Any) – value for original value variable. This usually represents 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
See also
- 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
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.
- Return type
Dict[str, Any]