mirror of
https://github.com/qgis/QGIS.git
synced 2025-12-15 00:07:25 -05:00
Fix malformed docs for register_function, qgsfunction
This commit is contained in:
Nyall Dawson
Julien Cabieces
parent
89c27fee8d
commit
c85589e52a
@ -104,6 +104,7 @@ def register_function(
|
||||
Register a Python function to be used as a expression function.
|
||||
|
||||
The 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
|
||||
@ -123,12 +124,10 @@ def register_function(
|
||||
:param params_as_list: If True, the function will receive the expression parameters as a list. If False, the function will receive the parameters as individual arguments. False by default.
|
||||
|
||||
:Keyword Arguments:
|
||||
* *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
|
||||
|
||||
* *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
|
||||
|
||||
:return:
|
||||
"""
|
||||
@ -168,9 +167,11 @@ def 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.
|
||||
|
||||
@ -198,88 +199,92 @@ def qgsfunction(args="auto", group="custom", **kwargs):
|
||||
If provided, used in the help tooltip instead of the function docstring
|
||||
|
||||
|
||||
**Example 1 (Basic function, with default parameters) **:
|
||||
Example 1 (Basic function, with default parameters)
|
||||
---------------------------------------------------
|
||||
|
||||
```
|
||||
@qgsfunction(group="python")
|
||||
def center(text, width, fillchar=" "):
|
||||
return text.center(width, fillchar)
|
||||
.. code-block:: python
|
||||
|
||||
```
|
||||
@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*****'
|
||||
```
|
||||
.. code-block:: text
|
||||
|
||||
>>> 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]
|
||||
Example 2 (variable number of parameters)
|
||||
-----------------------------------------
|
||||
|
||||
```
|
||||
.. code-block:: python
|
||||
|
||||
@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 ]
|
||||
```
|
||||
.. code-block:: text
|
||||
|
||||
**Example 3 (feature and parent) **:
|
||||
>>> 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 ]
|
||||
|
||||
```
|
||||
@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")
|
||||
```
|
||||
|
||||
Example 3 (feature and parent)
|
||||
------------------------------
|
||||
|
||||
.. code-block:: python
|
||||
|
||||
@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
|
||||
```
|
||||
.. code-block:: text
|
||||
|
||||
**Example 4 (context)**:
|
||||
```
|
||||
@qgsfunction(group="custom")
|
||||
def title_layer_name(context):
|
||||
return context.variable("layer_name").title()
|
||||
```
|
||||
>>> display_field("altitude")
|
||||
<b>altitude</b>: 164
|
||||
>>> display_field("lat")
|
||||
<b>lat</b>: 45.4
|
||||
|
||||
Example 4 (context)
|
||||
-------------------
|
||||
|
||||
.. code-block:: python
|
||||
|
||||
@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.
|
||||
|
||||
|
||||
"""
|
||||
|
||||
def wrapper(func):
|
||||
|
||||
@ -104,6 +104,7 @@ def register_function(
|
||||
Register a Python function to be used as a expression function.
|
||||
|
||||
The 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
|
||||
@ -123,12 +124,10 @@ def register_function(
|
||||
:param params_as_list: If True, the function will receive the expression parameters as a list. If False, the function will receive the parameters as individual arguments. False by default.
|
||||
|
||||
:Keyword Arguments:
|
||||
* *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
|
||||
|
||||
* *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
|
||||
|
||||
:return:
|
||||
"""
|
||||
@ -168,9 +167,11 @@ def 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.
|
||||
|
||||
@ -198,88 +199,92 @@ def qgsfunction(args="auto", group="custom", **kwargs):
|
||||
If provided, used in the help tooltip instead of the function docstring
|
||||
|
||||
|
||||
**Example 1 (Basic function, with default parameters) **:
|
||||
Example 1 (Basic function, with default parameters)
|
||||
---------------------------------------------------
|
||||
|
||||
```
|
||||
@qgsfunction(group="python")
|
||||
def center(text, width, fillchar=" "):
|
||||
return text.center(width, fillchar)
|
||||
.. code-block:: python
|
||||
|
||||
```
|
||||
@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*****'
|
||||
```
|
||||
.. code-block:: text
|
||||
|
||||
>>> 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]
|
||||
Example 2 (variable number of parameters)
|
||||
-----------------------------------------
|
||||
|
||||
```
|
||||
.. code-block:: python
|
||||
|
||||
@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 ]
|
||||
```
|
||||
.. code-block:: text
|
||||
|
||||
**Example 3 (feature and parent) **:
|
||||
>>> 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 ]
|
||||
|
||||
```
|
||||
@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")
|
||||
```
|
||||
|
||||
Example 3 (feature and parent)
|
||||
------------------------------
|
||||
|
||||
.. code-block:: python
|
||||
|
||||
@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
|
||||
```
|
||||
.. code-block:: text
|
||||
|
||||
**Example 4 (context)**:
|
||||
```
|
||||
@qgsfunction(group="custom")
|
||||
def title_layer_name(context):
|
||||
return context.variable("layer_name").title()
|
||||
```
|
||||
>>> display_field("altitude")
|
||||
<b>altitude</b>: 164
|
||||
>>> display_field("lat")
|
||||
<b>lat</b>: 45.4
|
||||
|
||||
Example 4 (context)
|
||||
-------------------
|
||||
|
||||
.. code-block:: python
|
||||
|
||||
@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.
|
||||
|
||||
|
||||
"""
|
||||
|
||||
def wrapper(func):
|
||||
|
||||
Loading…
x
Reference in New Issue
Block a user