Skip to content

Commit

Permalink
Fix malformed docs for register_function, qgsfunction
Browse files Browse the repository at this point in the history
  • Loading branch information
@nyalldawson @troopa81
nyalldawson authored and troopa81 committed Sep 11, 2024
1 parent 89c27fe commit c85589e
Show file tree
Hide file tree
Showing 2 changed files with 136 additions and 126 deletions.
131 changes: 68 additions & 63 deletions python/PyQt6/core/additions/qgsfunction.py
View file
Original file line number Diff line number Diff line change
Expand Up @@ -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
Expand All @@ -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:
"""
Expand Down Expand Up @@ -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.
Expand Down Expand Up @@ -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 ]
```
**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")
```
.. code-block:: text
>>> 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)
------------------------------
.. 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):
Expand Down
131 changes: 68 additions & 63 deletions python/core/additions/qgsfunction.py
View file
Original file line number Diff line number Diff line change
Expand Up @@ -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
Expand All @@ -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:
"""
Expand Down Expand Up @@ -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.
Expand Down Expand Up @@ -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 ]
```
**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")
```
.. code-block:: text
>>> 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)
------------------------------
.. 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):
Expand Down

0 comments on commit c85589e

Please sign in to comment.