Class: QgsExpressionFunction

An abstract base class for defining QgsExpression functions.

Note

This is an abstract class, with methods which must be implemented by a subclass.

The following methods must be implemented: func()

Class Hierarchy

Subclasses

QgsScopedExpressionFunction

Expression function for use within a QgsExpressionContextScope.

Abstract Methods

func	Returns result of evaluating the function.

Methods

group	Returns the first group which the function belongs to.
groups	Returns a list of the groups the function belongs to.
helpText	The help text for the function.
isContextual	Returns whether the function is only available if provided by a QgsExpressionContext object.
lazyEval	True if this function should use lazy evaluation.
minParams	The minimum number of parameters this function takes.
name	The name of the function.
parameters	Returns the list of named parameters for the function, if set.
params	The number of parameters this function takes.

Virtual Methods

In PyQGIS, only methods marked as virtual can be safely overridden in a Python subclass of QgsExpressionFunction. See the FAQ for more details.

aliases	Returns a list of possible aliases for the function.
handlesNull	Returns True if the function handles NULL values in arguments by itself, and the default NULL value handling should be skipped.
isDeprecated	Returns True if the function is deprecated and should not be presented as a valid option to users in expression builders.
isStatic	Will be called during prepare to determine if the function is static.
prepare	This will be called during the prepare step() of an expression if it is not static.
referencedColumns	Returns a set of field names which are required for this function.
run	Evaluates the function, first evaluating all required arguments before passing them to the function's func() method.
usesGeometry	Does this function use a geometry object.

Static Methods

allParamsStatic

This will return True if all the params for the provided function node are static within the constraints imposed by the context within the given parent.

class qgis.core.QgsExpressionFunction

Bases: object

__init__(fnname: str | None, params: int, group: str | None, helpText: str | None = '', lazyEval: bool = False, handlesNull: bool = False, isContextual: bool = False)

Constructor for function which uses unnamed parameters

Parameters:

• fnname (Optional[str])

• params (int)

• group (Optional[str])

• helpText (Optional[str] = '')

• lazyEval (bool = False)

• handlesNull (bool = False)

• isContextual (bool = False)

__init__(fnname: str | None, params: int, groups: Iterable[str | None], helpText: str | None = '', lazyEval: bool = False, handlesNull: bool = False, isContextual: bool = False)

Constructor for function which uses unnamed parameters and group list

Parameters:

• fnname (Optional[str])

• params (int)

• groups (Iterable[Optional[str]])

• helpText (Optional[str] = '')

• lazyEval (bool = False)

• handlesNull (bool = False)

• isContextual (bool = False)

__init__(fnname: str | None, params: Iterable[QgsExpressionFunction.Parameter], group: str | None, helpText: str | None = '', lazyEval: bool = False, handlesNull: bool = False, isContextual: bool = False)

Constructor for function which uses named parameter list.

Parameters:

• fnname (Optional[str])

• params (Iterable[QgsExpressionFunction.Parameter])

• group (Optional[str])

• helpText (Optional[str] = '')

• lazyEval (bool = False)

• handlesNull (bool = False)

• isContextual (bool = False)

__init__(fnname: str | None, params: Iterable[QgsExpressionFunction.Parameter], groups: Iterable[str | None], helpText: str | None = '', lazyEval: bool = False, handlesNull: bool = False, isContextual: bool = False)

Constructor for function which uses named parameter list and group list.

Parameters:

• fnname (Optional[str])

• params (Iterable[QgsExpressionFunction.Parameter])

• groups (Iterable[Optional[str]])

• helpText (Optional[str] = '')

• lazyEval (bool = False)

• handlesNull (bool = False)

• isContextual (bool = False)

__init__(a0: QgsExpressionFunction)

Parameters:

a0 (QgsExpressionFunction)

class Parameter

Bases: object

Represents a single parameter passed to a function.

QgsExpressionFunction.Parameter(name: Optional[str], optional: bool = False, defaultValue: Any = None, isSubExpression: bool = False) Constructor for Parameter.

Parameters:

• name – parameter name, used when named parameter are specified in an expression

• optional – set to True if parameter should be optional

• defaultValue – default value to use for optional parameters

• isSubExpression – set to True if this parameter is a sub-expression

QgsExpressionFunction.Parameter(a0: QgsExpressionFunction.Parameter)

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.

Added 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

virtual 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

static allParamsStatic(node: QgsExpressionNodeFunction | None, parent: QgsExpression | None, context: QgsExpressionContext | None) → bool

This will return True if all the params for the provided function node are static within the constraints imposed by the context within the given parent.

This can be used as callback for custom implementations of subclasses. It is the default for implementation for StaticFunction.isStatic.

Parameters:

• node (Optional[QgsExpressionNodeFunction])

• parent (Optional[QgsExpression])

• context (Optional[QgsExpressionContext])

Return type:

bool

abstract func(self, values: Iterable[Any], context: QgsExpressionContext | None, parent: QgsExpression | None, node: QgsExpressionNodeFunction | None) → Any

Returns result of evaluating the function.

Parameters:

• values (Iterable[Any]) – list of values passed to the function

• context (Optional[QgsExpressionContext]) – context expression is being evaluated against

• parent (Optional[QgsExpression]) – parent expression

• node (Optional[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

group()

Return type:

List[str]

virtual 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.

Return type:

bool

virtual isDeprecated(self) → bool

Returns True if the function is deprecated and should not be presented as a valid option to users in expression builders.

Return type:

bool

virtual isStatic(self, node: QgsExpressionNodeFunction | None, parent: QgsExpression | None, context: QgsExpressionContext | None) → 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.

Parameters:

• node (Optional[QgsExpressionNodeFunction])

• parent (Optional[QgsExpression])

• context (Optional[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.

Return type:

List[QgsExpressionFunction.Parameter]

params(self) → int

The number of parameters this function takes.

Return type:

int

virtual prepare(self, node: QgsExpressionNodeFunction | None, parent: QgsExpression | None, context: QgsExpressionContext | None) → 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.

Parameters:

• node (Optional[QgsExpressionNodeFunction])

• parent (Optional[QgsExpression])

• context (Optional[QgsExpressionContext])

Return type:

bool

virtual referencedColumns(self, node: QgsExpressionNodeFunction | None) → 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.

Parameters:

node (Optional[QgsExpressionNodeFunction])

Return type:

Set[str]

virtual run(self, args: QgsExpressionNode.NodeList | None, context: QgsExpressionContext | None, parent: QgsExpression | None, node: QgsExpressionNodeFunction | None) → Any

Evaluates the function, first evaluating all required arguments before passing them to the function’s func() method.

Parameters:

• args (Optional[QgsExpressionNode.NodeList])

• context (Optional[QgsExpressionContext])

• parent (Optional[QgsExpression])

• node (Optional[QgsExpressionNodeFunction])

Return type:

Any

virtual usesGeometry(self, node: QgsExpressionNodeFunction | None) → bool

Does this function use a geometry object.

Parameters:

node (Optional[QgsExpressionNodeFunction])

Return type:

bool