Class: qgsfunction

class qgis.core.qgsfunction(args='auto', group='custom', **kwargs)

Decorator function used to define a user expression function.

The decorated function signature may contain special parameters (in any order at the end of the signature): - feature: the QgsFeature related to the current evaluation - parent: the QgsExpressionFunction parent - context: the QgsExpressionContext related to the current evaluation If those parameters are present in the function signature, they will be automatically passed to the function, without the need to specify them in the expression.

Functions should return a value compatible with QVariant Eval errors can be raised using parent.setEvalErrorString(“Error message”)

Parameters:

  • args – DEPRECATED since QGIS 3.32. Use the “params_as_list” keyword argument if you want to pass parameters as a list.

  • group – The expression group to which this expression should be added.

  • **kwargs – See below

Keyword Arguments:

  • usesgeometry (bool) – Defines if this expression requires the geometry. By default False.

  • referenced_columns (list) – An array of names of fields on which this expression works. By default [QgsFeatureRequest.ALL_ATTRIBUTES]. Specifying a subset of fields or an empty list will result in a faster execution.

  • handlesnull (bool) – Defines if this expression has custom handling for NULL values. If False, the result will always be NULL as soon as any parameter is NULL. False by default.

  • params_as_list (bool) since QGIS 3.32 – Defines if the parameters are passed to the function as a list. If set the False, they will be expanded. By default False.

  • register (bool) –

    Set to False to create the QgsPyExpressionFunction without registering it. Useful for testing puposes. By default True.

  • name (str) –

    If provided, replace the function name

  • helpText (str) –

    If provided, used in the help tooltip instead of the function docstring

**Example 1 (Basic function, with default parameters) **:

``` @qgsfunction(group=”python”) def center(text, width, fillchar=” “):

return text.center(width, fillchar)

```

This registers a function called “center” in the “python” group. This expression requires two parameters: text and width. An optional third parameter can be provided: fillchar.

` >>> center('Hello', 10) '  Hello   ' >>> center('Hello', 15, '*') '*****Hello*****' `

**Example 2 (variable number of parameters) **: ``` @qgsfunction(group=”custom”) def fibonnaci_numbers(*args):

def fibonnaci(n):
if n <= 1:

return n

else:

return fibonnaci(n - 1) + fibonnaci(n - 2)

return [fibonnaci(arg) for arg in args]

```

This registers a function called “fibonnaci_numbers” in the “custom” group. This expression can be called with any number of parameters, and will return a list of the fibonnaci numbers corresponding to the parameters.

` >>> fibonnaci_numbers() [] >>> fibonnaci_numbers(1) [1] >>> fibonnaci_numbers(3) [2] >>> fibonnaci_numbers(1, 2, 3, 4, 5, 6, 7) [ 1, 1, 2, 3, 5, 8, 13 ] `

**Example 3 (feature and parent) **:

``` @qgsfunction(group=”custom”) def display_field(fieldname, feature, parent):

try:

return f”<b>{fieldname}</b>: {feature[fieldname]}”

except KeyError:

parent.setEvalErrorString(f”Field {fieldname} not found”)

```

This registers a function called “display_field” in the “custom” group. This expression requires an unique parameter: fieldname. Feature is automatically passed to the function. parent is the QgsExpressionFunction parent, and can be used to raise an error.

` >>> display_field("altitude") <b>altitude</b>: 164 >>> display_field("lat") <b>lat</b>: 45.4 `

Example 4 (context): ``` @qgsfunction(group=”custom”) def title_layer_name(context):

return context.variable(“layer_name”).title()

```

This registers a function called “title_layer_name” in the “custom” group. It takes no parameters, but extracts the layer name from the expression context and returns it as a title case string.