fix: user extra arguments (#50)

* fix: user extra arguments

Signed-off-by: develop-cs <43383361+develop-cs@users.noreply.github.com>

* docs: update value sharing

Signed-off-by: develop-cs <43383361+develop-cs@users.noreply.github.com>

---------

Signed-off-by: develop-cs <43383361+develop-cs@users.noreply.github.com>

Author: develop-cs

.pre-commit-config.yaml

@@ -44,7 +44,7 @@ repos:
   #   hooks:
   #     - id: gitleaks
   - repo: https://github.com/pypa/pip-audit
-    rev: v2.9.0
+    rev: v2.8.0
     hooks:
       - id: pip-audit
         args: [.]

CHANGELOG.md

@@ -4,11 +4,22 @@ All notable changes to this project will be documented in this file.
 
 The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.0.0/), and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.html).
 
+## 0.10.3 - July, 2025
+
+### Fixes
+
+* User extra arguments in `.apply_rules()` were not given to action and condition function implementations (#49).
+
+### Documentation
+
+* Improve :
+    * [Value sharing](https://maif.github.io/arta/value_sharing/) page.
+
 ## 0.10.2 - July, 2025
 
 ### Fixes
 
-* `kwargs` as an optional parameter (since v0.10.0) wasn't totally implemented: *dictionary of rules* was missing (#47).
+* `kwargs` were mandatory for action functions used inside a *dictionary of rules* (#47). They are now optional.
 
 ## 0.10.1 - April, 2025
 

docs/pages/a_simple_example.md

@@ -106,8 +106,8 @@ An **action** is triggered when the conditions are verified (i.e., `True`).
 **Actions** are defined by the following *keys* in the previous YAML file:
 
 ```yaml
-        action: set_admission  # (1)
-        action_parameters:  # (2)
+        action: set_admission  # (1)!
+        action_parameters:  # (2)!
           value: true  
 ```
 
@@ -201,11 +201,11 @@ Now, let's apply the **rules** on a single applicant:
 ```python
 from arta import RulesEngine
 
-eng = RulesEngine(config_path="/to/my/config/dir")  # (1)
+eng = RulesEngine(config_path="/to/my/config/dir")  # (1)!
 
 result = eng.apply_rules(input_data=applicants[0])
 
-print(result)  # (2)
+print(result)  # (2)!
 # {
 # "admission": {"is_admitted": True},
 # "course": {"course_id": "senior"},

docs/pages/home.md

@@ -12,23 +12,19 @@
 
 Want to discover what is **Arta**? :arrow_right: [Get Started](a_simple_example.md)
 
-
 Want to know how to use it? :arrow_right: [User Guide](how_to.md)
 
-
 !!! info inline "New feature"
 
-    Use **Arta** as a *process execution engine* :zap:
-    
-    Read [this page](rule_activation_mode.md) for more details.
+    Use [value sharing](value_sharing.md) to customize actions and conditions :tools:
 
 !!! tip "Releases"
 
     Check the [Release notes](https://github.com/MAIF/arta/releases) :rocket:
 
-!!! warning "Pydantic 1 compatibility is deprecated"
+!!! warning "Pydantic v1"
 
-    **Arta** is working with [Pydantic 2](https://docs.pydantic.dev/latest/) and Pydantic 1 but compatibility with V1  will be removed in the next **major** release.
+    Compatibility with *Pydantic v1* will be removed in next **major** release.
 
 **Arta** is working and automatically tested with:
 

docs/pages/how_to.md

@@ -43,7 +43,7 @@ rules:
           value: KO
 
 actions_source_modules:
-  - my_folder.actions  # (1)
+  - my_folder.actions  # (1)!
 ```
 
 1. Contains *action function* implementations, no need of the key `conditions_source_modules` here.
@@ -112,10 +112,10 @@ Create a YAML file and define your rules like this:
 ```yaml hl_lines="6 16-26"
 ---
 rules:
-  default_rule_set:  # (1)
+  default_rule_set:  # (1)!
     check_admission:
       ADMITTED_RULE:
-        condition: HAS_SCHOOL_AUTHORIZED_POWER  # (2)
+        condition: HAS_SCHOOL_AUTHORIZED_POWER  # (2)!
         action: set_admission
         action_parameters:
           value: true
@@ -125,16 +125,16 @@ rules:
         action_parameters:
           value: false
 
-conditions:  # (3)
+conditions:  # (3)!
   HAS_SCHOOL_AUTHORIZED_POWER:
     description: "Does applicant have a school authorized power?"
     validation_function: has_authorized_super_power
     condition_parameters:
       power: input.super_power
 
-conditions_source_modules:  # (4)
+conditions_source_modules:  # (4)!
   - my_folder.conditions
-actions_source_modules:  # (5)
+actions_source_modules:  # (5)!
   - my_folder.actions
 ```
 
@@ -289,9 +289,9 @@ A **rule set** is composed of **rule groups** which are themselves composed of *
 ```yaml
 ---
 rules:
-  default_rule_set:  # (1)
-    check_admission:  # (2)
-      ADMITTED_RULE:  # (3)
+  default_rule_set:  # (1)!
+    check_admission:  # (2)!
+      ADMITTED_RULE:  # (3)!
         condition: HAS_SCHOOL_AUTHORIZED_POWER
         action: set_admission
         action_parameters:

docs/pages/value_sharing.md

@@ -1,7 +1,8 @@
-!!! note
+!!! info
 
-    Only available with `arta>=0.10.0`.
+    Needs `arta>=0.10.0`.
 
+## Between conditions and actions
 
 It is possible to share some informations between **condition** and **action** implementations.
 
@@ -22,12 +23,12 @@ In the following example, a **condition** is computing the *median* of some *inp
 def is_median_above(
     values: list[float], 
     limit: float, 
-    **kwargs: Any,  # (1)
+    **kwargs: Any,  # (1)!
     ) -> bool:
     """Check if the median of some values is above limit."""
     median = statistics.median(values)
     # Store the value for later use by an action function
-    kwargs["input_data"]["median"] = median  # (2)
+    kwargs["input_data"]["median"] = median  # (2)!
     kwargs["input_data"]["median_limit"] = limit
     return median > limit
 ```
@@ -39,13 +40,45 @@ def is_median_above(
 **Get the value (in an action for example):**
 
 ```python hl_lines="1 4"
-def alert_on_median(**kwargs: Any) -> str:  # (1)
+def alert_on_median(**kwargs: Any) -> str:  # (1)!
     """Alert: "Median is too high: 13, limit is: 10."""
     return (
-        f"Median is too high: {kwargs['input_data']['median']}, "  # (2)
+        f"Median is too high: {kwargs['input_data']['median']}, "  # (2)!
         f"limit is: {kwargs['input_data']['median_limit']}."
     )
 ```
 
 1. Add the ****kwargs** parameter.
-2. Get the value.
+2. Get the value.
+
+## User extra arguments
+
+The following code shows how to set custom **user extra arguments** (e.g., `add_details`) within the `.apply_rules()` method:
+
+```python hl_lines="5"
+from arta import RulesEngine
+
+eng = RulesEngine(config_path="/to/my/config/dir")
+
+result = eng.apply_rules(input_data={...}, add_details=True)
+```
+
+Used inside **action** and/or **condition functions**:
+
+```python hl_lines="4"
+def my_action(**kwargs: Any) -> str:  # (1)!
+    """A simple action function."""
+
+    if kwargs["add_details"]:  # (2)!
+        action_result = (
+            f"Median is too high: {kwargs['input_data']['median']}, "
+            f"limit is: {kwargs['input_data']['median_limit']}."
+        )
+    else:
+        action_result = "Median is too high."
+    
+    return action_result
+```
+
+1. Don't forget to add the ****kwargs** parameter.
+2. Straight use of the corresponding extra argument.

pyproject.toml

@@ -4,7 +4,7 @@ build-backend = "setuptools.build_meta"
 
 [project]
 name = "arta"
-version = "0.10.2"
+version = "0.10.3"
 requires-python = ">3.8.0"
 description = "A Python Rules Engine - Make rule handling simple"
 readme = "README.md"

src/arta/condition.py

@@ -145,6 +145,7 @@ def verify(self, input_data: dict[str, Any], parsing_error_strategy: ParsingErro
         arg_spec: inspect.FullArgSpec = inspect.getfullargspec(self._validation_function)
         if arg_spec.varkw is not None:
             parameters["input_data"] = input_data
+            parameters.update(kwargs)
 
         # Run validation_function
         return self._validation_function(**parameters)

src/arta/rule.py

@@ -111,18 +111,21 @@ def apply(
                 arg_spec: inspect.FullArgSpec = inspect.getfullargspec(self._action)
                 if arg_spec.varkw is not None:
                     parameters["input_data"] = input_data
+                    parameters.update(kwargs)
 
                 # Backward compatibility case (now deprecated)
                 if "input_data" in arg_spec.args or "input_data" in arg_spec.kwonlyargs:
                     warn(
                         (
                             "Using 'input_data' directly as an action function parameter is deprecated. "
-                            "Use '**kwargs' instead. See how at https://maif.github.io/arta/value_sharing/"
+                            "Use '**kwargs' instead. See how "
+                            "at https://maif.github.io/arta/value_sharing/#between-conditions-and-actions"
                         ),
                         DeprecationWarning,
                         stacklevel=2,
                     )
                     parameters["input_data"] = input_data
+                    parameters.update(kwargs)
 
                 # Run action
                 rule_results["action_result"] = self._action(**parameters)

tests/examples/code/actions.py

@@ -54,3 +54,11 @@ def concatenate(value1: str, value2: str) -> str:
 def alert_on_median(**kwargs: Any) -> str:
     """Alert: "Median is too high: 13, limit is: 10."""
     return f"Median is too high: {kwargs['input_data']['median']}, limit is: {kwargs['input_data']['median_limit']}."
+
+
+def set_admission_custom(value: bool, **kwargs: Any) -> dict[str, bool]:
+    """Return a dictionary containing the admission result and use a user defined argument."""
+    # Pseudo edge case
+    value = value if kwargs["my_parameter"] is True else False
+
+    return {"admission": value}