Class: QgsExpressionFunction¶
-
class
qgis.core.
QgsExpressionFunction
(fnname: str, params: int, group: str, helpText: str = '', lazyEval: bool = False, handlesNull: bool = False, isContextual: bool = False)¶ Bases:
sip.wrapper
Constructor for function which uses unnamed parameters
QgsExpressionFunction(fnname: str, params: int, groups: Iterable[str], helpText: str = ‘’, lazyEval: bool = False, handlesNull: bool = False, isContextual: bool = False) Constructor for function which uses unnamed parameters and group list
New in version 3.0.
QgsExpressionFunction(fnname: str, params: Iterable[QgsExpressionFunction.Parameter], group: str, helpText: str = ‘’, lazyEval: bool = False, handlesNull: bool = False, isContextual: bool = False) Constructor for function which uses named parameter list.
New in version 2.16.
QgsExpressionFunction(fnname: str, params: Iterable[QgsExpressionFunction.Parameter], groups: Iterable[str], helpText: str = ‘’, lazyEval: bool = False, handlesNull: bool = False, isContextual: bool = False) Constructor for function which uses named parameter list and group list.
New in version 3.0.
QgsExpressionFunction(
QgsExpressionFunction
)A abstract base class for defining
QgsExpression
functions.- Parameters
fnname (str) –
params (int) –
group (str) –
helpText (str = '') –
lazyEval (bool = False) –
handlesNull (bool = False) –
isContextual –
-
class
Parameter
(name: str, optional: bool = False, defaultValue: Any = None, isSubExpression: bool = False)¶ Bases:
sip.wrapper
Constructor for Parameter.
- Parameters
name (str) – parameter name, used when named parameter are specified in an expression
optional (bool = False) – set to
True
if parameter should be optionaldefaultValue (Any = None) – default value to use for optional parameters
isSubExpression (bool = False) – set to
True
if this parameter is a sub-expression
QgsExpressionFunction.Parameter(QgsExpressionFunction.Parameter)
Represents a single parameter passed to a function.
New in version 2.16.
-
defaultValue
(self) → Any¶ Returns the default value for the parameter.
- Return type
Any
-
isSubExpression
(self) → bool¶ Returns
True
if parameter argument is a separate sub-expression, and should not be checked while determining referenced columns for the expression.New in version 3.2.
- Return type
bool
-
name
(self) → str¶ Returns the name of the parameter.
- Return type
str
-
optional
(self) → bool¶ Returns
True
if the parameter is optional.- Return type
bool
-
aliases
(self) → List[str]¶ Returns a list of possible aliases for the function. These include other permissible names for the function, e.g., deprecated names.
- Return type
List[str]
- Returns
list of known aliases
New in version 2.9.
-
allParamsStatic
(node: QgsExpressionNodeFunction, parent: QgsExpression, context: QgsExpressionContext) → bool¶ This will return
True
if all the params for the provided functionnode
are static within the constraints imposed by thecontext
within the givenparent
.This can be used as callback for custom implementations of subclasses. It is the default for implementation for StaticFunction.isStatic.
New in version 3.0.
- Parameters
node (QgsExpressionNodeFunction) –
parent (QgsExpression) –
context (QgsExpressionContext) –
- Return type
bool
-
func
(self, values: Iterable[Any], context: QgsExpressionContext, parent: QgsExpression, node: QgsExpressionNodeFunction) → Any¶ Returns result of evaluating the function.
- Parameters
values (Iterable[Any]) – list of values passed to the function
context (QgsExpressionContext) – context expression is being evaluated against
parent (QgsExpression) – parent expression
node (QgsExpressionNodeFunction) – expression node
- Return type
Any
- Returns
result of function
-
group
(self) → str¶ Returns the first group which the function belongs to.
Note
consider using groups() instead, as some functions naturally belong in multiple groups
- Return type
str
-
groups
(self) → List[str]¶ Returns a list of the groups the function belongs to.
See also
New in version 3.0.
- Return type
List[str]
-
handlesNull
(self) → bool¶ Returns
True
if the function handles NULL values in arguments by itself, and the default NULL value handling should be skipped.- Return type
bool
-
helpText
(self) → str¶ The help text for the function.
- Return type
str
-
isContextual
(self) → bool¶ Returns whether the function is only available if provided by a
QgsExpressionContext
object.New in version 2.12.
- Return type
bool
-
isDeprecated
(self) → bool¶ Returns
True
if the function is deprecated and should not be presented as a valid option to users in expression builders.New in version 3.0.
- Return type
bool
-
isStatic
(self, node: QgsExpressionNodeFunction, parent: QgsExpression, context: QgsExpressionContext) → bool¶ Will be called during prepare to determine if the function is static. A function is static if it will return the same value for every feature with different attributes and/or geometry.
By default this will return
True
, if all arguments that have been passed to the function are also static.New in version 3.0.
- Parameters
node (QgsExpressionNodeFunction) –
parent (QgsExpression) –
context (QgsExpressionContext) –
- Return type
bool
-
lazyEval
(self) → bool¶ True
if this function should use lazy evaluation. Lazy evaluation functions take QgsExpression.Node objects rather than the node results when called. You can use node->eval(parent, feature) to evaluate the node and return the result Functions are non lazy default and will be given the node return value when called.- Return type
bool
-
minParams
(self) → int¶ The minimum number of parameters this function takes.
- Return type
int
-
name
(self) → str¶ The name of the function.
- Return type
str
-
parameters
(self) → List[QgsExpressionFunction.Parameter]¶ Returns the list of named parameters for the function, if set.
New in version 2.16.
- Return type
-
params
(self) → int¶ The number of parameters this function takes.
- Return type
int
-
prepare
(self, node: QgsExpressionNodeFunction, parent: QgsExpression, context: QgsExpressionContext) → bool¶ This will be called during the prepare step() of an expression if it is not static.
This can be used by functions to do any preparation steps that might help to speedup the upcoming evaluation.
New in version 3.0.
- Parameters
node (QgsExpressionNodeFunction) –
parent (QgsExpression) –
context (QgsExpressionContext) –
- Return type
bool
-
referencedColumns
(self, node: QgsExpressionNodeFunction) → Set[str]¶ Returns a set of field names which are required for this function. May contain QgsFeatureRequest.AllAttributes to signal that all attributes are required. If in doubt this will return more fields than strictly required.
New in version 3.0.
- Parameters
node (QgsExpressionNodeFunction) –
- Return type
Set[str]
-
run
(self, args: QgsExpressionNode.NodeList, context: QgsExpressionContext, parent: QgsExpression, node: QgsExpressionNodeFunction) → Any¶ Evaluates the function, first evaluating all required arguments before passing them to the function’s func() method.
- Parameters
args (QgsExpressionNode.NodeList) –
context (QgsExpressionContext) –
parent (QgsExpression) –
node (QgsExpressionNodeFunction) –
- Return type
Any
-
usesGeometry
(self, node: QgsExpressionNodeFunction) → bool¶ Does this function use a geometry object.
- Parameters
node (QgsExpressionNodeFunction) –
- Return type
bool