Function: qgsfunction

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):

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.