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. 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.New in version 2.12.
QgsExpressionContext() 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 constructorMethods
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.
Returns the feedback object that can be queried regularly by the expression to check if evaluation should be canceled, 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.
Convenience function for retrieving the geometry for the context, if set.
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.
Returns
True
if the context has a geometry associated with it.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.
Attach a
feedback
object that can be queried regularly by the expression engine to check if expression evaluation should be canceled.Convenience function for setting a fields for the context.
Convenience function for setting a
geometry
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_GEOMETRY_RING_NUM = 'geometry_ring_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:
- feedback(self) QgsFeedback ¶
Returns the feedback object that can be queried regularly by the expression to check if evaluation should be canceled, if set.
See also
New in version 3.20.
- 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]
- geometry(self) QgsGeometry ¶
Convenience function for retrieving the geometry for the context, if set.
See also
New in version 3.24.
- Return type:
- 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
- hasGeometry(self) bool ¶
Returns
True
if the context has a geometry associated with it.See also
New in version 3.24.
- Return type:
bool
- 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
- setFeedback(self, feedback: QgsFeedback)¶
Attach a
feedback
object that can be queried regularly by the expression engine to check if expression evaluation should be canceled.Ownership of
feedback
is NOT transferred, and the caller must take care that it exists for the lifetime of the expression context.See also
New in version 3.20.
- Parameters:
feedback (QgsFeedback) –
- 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
- setGeometry(self, geometry: QgsGeometry)¶
Convenience function for setting a
geometry
for the context. The geometry will be set within the last scope of the context, so will override any existing geometries within the context.See also
New in version 3.24.
- Parameters:
geometry (QgsGeometry) –
- 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]