From d6ea068ef2066cb1febdaeb711a3344ad34a2ee6 Mon Sep 17 00:00:00 2001
From: Popescu V <136721202+popescu-v@users.noreply.github.com>
Date: Mon, 29 Sep 2025 15:18:07 +0200
Subject: [PATCH 1/6] Simplify the Rule API

Only attach rules to variables (and variable blocks) as strings.

Also add notes to the `Rule` object docstring.

TODO: Add some rule serialization examples.

related_to #479
---
 doc/samples/samples.rst      |  6 +--
 khiops/core/dictionary.py    | 82 +++++++-----------------------------
 khiops/samples/samples.ipynb |  6 +--
 khiops/samples/samples.py    |  6 +--
 tests/test_core.py           | 40 +++++++-----------
 5 files changed, 41 insertions(+), 99 deletions(-)

diff --git a/doc/samples/samples.rst b/doc/samples/samples.rst
index 50f62118..1a3228ea 100644
--- a/doc/samples/samples.rst
+++ b/doc/samples/samples.rst
@@ -97,7 +97,7 @@ Samples
     third_dictionary.add_variable_from_spec(
         name="computed",
         type="Numerical",
-        rule=kh.Rule("Ceil", kh.Rule("Product", 3, kh.Rule("Random()"))),
+        rule=str(kh.Rule("Ceil", kh.Rule("Product", 3, kh.Rule("Random()")))),
     )
 
     # Add the variables used in a multi-table context in the first dictionary.
@@ -649,7 +649,7 @@ Samples
 
     # Create fold indexing rule and set it on `fold_index_variable`
     fold_index_variable = dictionary.get_variable("FoldIndex")
-    fold_index_variable.set_rule(
+    fold_index_variable.rule = str(
         kh.Rule("Ceil", kh.Rule("Product", fold_number, kh.Rule("Random()"))),
     )
 
@@ -657,7 +657,7 @@ Samples
     for fold_index in range(1, fold_number + 1):
         name = "IsInTrainDataset" + str(fold_index)
         dictionary.add_variable_from_spec(name=name, type="Numerical", used=False)
-        dictionary.get_variable(name).set_rule(
+        dictionary.get_variable(name).rule = str(
             kh.Rule("NEQ", fold_index_variable, fold_index),
         )
 
diff --git a/khiops/core/dictionary.py b/khiops/core/dictionary.py
index 6cd5e9b9..7a5f82b1 100644
--- a/khiops/core/dictionary.py
+++ b/khiops/core/dictionary.py
@@ -857,8 +857,8 @@ def add_variable_from_spec(
             Object type. Ignored if variable type not in ["Entity", "Table"].
         structure_type : str, optional
             Structure type. Ignored if variable type is not "Structure".
-        rule : `Rule`, optional
-            Variable rule.
+        rule : str, optional
+            String representation of a variable rule.
         meta_data : dict, optional
             A Python dictionary which holds the metadata specification.
             The dictionary keys are str. The values can be str, bool, float or int.
@@ -906,8 +906,8 @@ def add_variable_from_spec(
                     type_error_message("structure_type", structure_type, "string-like")
                 )
         if rule is not None:
-            if not isinstance(rule, Rule):
-                raise TypeError(type_error_message("rule", rule, Rule))
+            if not isinstance(rule, str):
+                raise TypeError(type_error_message("rule", rule, str))
 
         # Variable initialization
         variable = Variable()
@@ -923,7 +923,7 @@ def add_variable_from_spec(
         if structure_type is not None:
             variable.structure_type = structure_type
         if rule is not None:
-            variable.set_rule(rule)
+            variable.rule = str(rule)
         self.add_variable(variable)
 
     def remove_variable(self, variable_name):
@@ -1363,34 +1363,6 @@ def full_type(self):
             full_type += f"({self.structure_type})"
         return full_type
 
-    def get_rule(self):
-        """Gets the rule of the variable
-
-        Returns
-        -------
-        `Rule`
-            A `Rule` instance created as a verbatim rule from the ``rule``
-            attribute of the variable.
-        """
-        return Rule(verbatim=self.rule, is_reference=self.is_reference_rule())
-
-    def set_rule(self, rule):
-        """Sets a rule on a specified variable in the dictionary
-
-        Parameters
-        ----------
-        rule : `Rule`
-            The rule to be set on the variable.
-
-        Raises
-        ------
-        `TypeError`
-            If ``rule`` is not of type `Rule`.
-        """
-        if not isinstance(rule, Rule):
-            raise TypeError(type_error_message("rule", rule, Rule))
-        self.rule = repr(rule)
-
     def write(self, writer):
         """Writes the domain to a file writer in ``.kdic`` format
 
@@ -1576,39 +1548,6 @@ def get_value(self, key):
         """
         return self.meta_data.get_value(key)
 
-    def get_rule(self):
-        """Gets the rule of the variable block
-
-        Returns
-        -------
-        `Rule`
-            A `Rule` instance created as a verbatim rule from the ``rule``
-            attribute of the variable block.
-        """
-        return Rule(verbatim=self.rule)
-
-    def set_rule(self, rule):
-        """Sets a rule on a specified variable block in the dictionary
-
-        Parameters
-        ----------
-        rule : `Rule`
-            The rule to be set on the variable block.
-
-        Raises
-        ------
-        `TypeError`
-            If ``rule`` is not of type `Rule`.
-
-        `ValueError`
-            If ``rule`` is a reference rule.
-        """
-        if not isinstance(rule, Rule):
-            raise TypeError(type_error_message("rule", rule, Rule))
-        if rule.is_reference:
-            raise ValueError("Cannot set reference rule on a variable block")
-        self.rule = repr(rule)
-
     def write(self, writer):
         """Writes the variable block to a file writer in ``.kdic`` format
 
@@ -1664,6 +1603,17 @@ def write(self, writer):
 class Rule:
     """A rule of a variable or variable block in a Khiops dictionary
 
+    This object is a convenience feature which eases rule creation and
+    serialization, especially in complex cases (rule operands which are
+    variables or rules themselves, sometimes upper-scoped). A `Rule` instance
+    must be converted to `str` before setting it in a `Variable` or
+    `VariableBlock` instance.
+
+    `Rule` instances can be created either from full operand specifications, or
+    from verbatim rules. The latter is useful when the rule is retrieved from an
+    existing variable or variable block and is used as an operand in another
+    rule.
+
     Parameters
     ----------
     name_and_operands : tuple
diff --git a/khiops/samples/samples.ipynb b/khiops/samples/samples.ipynb
index 9b4300d9..108b4086 100644
--- a/khiops/samples/samples.ipynb
+++ b/khiops/samples/samples.ipynb
@@ -109,7 +109,7 @@
     "third_dictionary.add_variable_from_spec(\n",
     "    name=\"computed\",\n",
     "    type=\"Numerical\",\n",
-    "    rule=kh.Rule(\"Ceil\", kh.Rule(\"Product\", 3, kh.Rule(\"Random()\"))),\n",
+    "    rule=str(kh.Rule(\"Ceil\", kh.Rule(\"Product\", 3, kh.Rule(\"Random()\")))),\n",
     ")\n",
     "\n",
     "# Add the variables used in a multi-table context in the first dictionary.\n",
@@ -869,7 +869,7 @@
     "\n",
     "# Create fold indexing rule and set it on `fold_index_variable`\n",
     "fold_index_variable = dictionary.get_variable(\"FoldIndex\")\n",
-    "fold_index_variable.set_rule(\n",
+    "fold_index_variable.rule = str(\n",
     "    kh.Rule(\"Ceil\", kh.Rule(\"Product\", fold_number, kh.Rule(\"Random()\"))),\n",
     ")\n",
     "\n",
@@ -877,7 +877,7 @@
     "for fold_index in range(1, fold_number + 1):\n",
     "    name = \"IsInTrainDataset\" + str(fold_index)\n",
     "    dictionary.add_variable_from_spec(name=name, type=\"Numerical\", used=False)\n",
-    "    dictionary.get_variable(name).set_rule(\n",
+    "    dictionary.get_variable(name).rule = str(\n",
     "        kh.Rule(\"NEQ\", fold_index_variable, fold_index),\n",
     "    )\n",
     "\n",
diff --git a/khiops/samples/samples.py b/khiops/samples/samples.py
index d5868f80..7ca3be09 100644
--- a/khiops/samples/samples.py
+++ b/khiops/samples/samples.py
@@ -111,7 +111,7 @@ def create_dictionary_domain():
     third_dictionary.add_variable_from_spec(
         name="computed",
         type="Numerical",
-        rule=kh.Rule("Ceil", kh.Rule("Product", 3, kh.Rule("Random()"))),
+        rule=str(kh.Rule("Ceil", kh.Rule("Product", 3, kh.Rule("Random()")))),
     )
 
     # Add the variables used in a multi-table context in the first dictionary.
@@ -724,7 +724,7 @@ def train_predictor_with_cross_validation():
 
     # Create fold indexing rule and set it on `fold_index_variable`
     fold_index_variable = dictionary.get_variable("FoldIndex")
-    fold_index_variable.set_rule(
+    fold_index_variable.rule = str(
         kh.Rule("Ceil", kh.Rule("Product", fold_number, kh.Rule("Random()"))),
     )
 
@@ -732,7 +732,7 @@ def train_predictor_with_cross_validation():
     for fold_index in range(1, fold_number + 1):
         name = "IsInTrainDataset" + str(fold_index)
         dictionary.add_variable_from_spec(name=name, type="Numerical", used=False)
-        dictionary.get_variable(name).set_rule(
+        dictionary.get_variable(name).rule = str(
             kh.Rule("NEQ", fold_index_variable, fold_index),
         )
 
diff --git a/tests/test_core.py b/tests/test_core.py
index 761452a7..990743da 100644
--- a/tests/test_core.py
+++ b/tests/test_core.py
@@ -1890,7 +1890,7 @@ def test_dictionary_accessors(self):
                         name="fresh_one", type="Structure"
                     )
                 # rule must be Rule object
-                with self.assertRaisesRegex(TypeError, "'rule'.*Rule"):
+                with self.assertRaisesRegex(TypeError, "'rule'.*'str'"):
                     dictionary.add_variable_from_spec(
                         name="fresh_one", type="Categorical", rule={}
                     )
@@ -1904,7 +1904,9 @@ def test_dictionary_accessors(self):
                     name="fresh_one",
                     type="Categorical",
                     meta_data={"a": 1, "b": 2},
-                    rule=kh.Rule("Ceil", kh.Rule("Product", 3, kh.Rule("Random()"))),
+                    rule=str(
+                        kh.Rule("Ceil", kh.Rule("Product", 3, kh.Rule("Random()")))
+                    ),
                 )
                 self.assertEqual(
                     2,
@@ -1913,7 +1915,7 @@ def test_dictionary_accessors(self):
                 )
                 self.assertEqual(
                     "Ceil(Product(3, Random()))",
-                    repr(dictionary.get_variable("fresh_one").get_rule()),
+                    dictionary.get_variable("fresh_one").rule,
                     "Variable rule must be set correctly",
                 )
                 variable_rule = kh.Rule(verbatim="Ceil(Product(3, Random()))")
@@ -1965,7 +1967,7 @@ def test_dictionary_accessors(self):
                 block_rule = kh.Rule("SomeBlockCreatingRule")
                 with self.assertRaises(TypeError):
                     dictionary_copy.get_variable_block(block.name).rule = block_rule
-                dictionary_copy.get_variable_block(block.name).set_rule(block_rule)
+                dictionary_copy.get_variable_block(block.name).rule = str(block_rule)
                 self.assertEqual(block, dictionary_copy.get_variable_block(block.name))
                 removed_block = dictionary_copy.remove_variable_block(
                     block.name,
@@ -2020,13 +2022,13 @@ def test_dictionary_accessors(self):
                         2,
                         kh.Rule("SomeEmbeddedRule()"),
                     )
-                    dictionary_copy.get_variable(variable_name).set_rule(some_rule)
+                    dictionary_copy.get_variable(variable_name).rule = str(some_rule)
                     self.assertEqual(
                         dictionary_copy.get_variable(variable_name).rule,
                         repr(some_rule),
                     )
                     self.assertEqual(
-                        repr(dictionary_copy.get_variable(variable_name).get_rule()),
+                        dictionary_copy.get_variable(variable_name).rule,
                         repr(some_rule),
                     )
                     some_reference_rule = kh.Rule(
@@ -2039,7 +2041,7 @@ def test_dictionary_accessors(self):
                         ),
                         is_reference=True,
                     )
-                    dictionary_copy.get_variable(variable_name).set_rule(
+                    dictionary_copy.get_variable(variable_name).rule = str(
                         some_reference_rule
                     )
                     self.assertEqual(
@@ -2047,7 +2049,7 @@ def test_dictionary_accessors(self):
                         repr(some_reference_rule),
                     )
                     self.assertEqual(
-                        repr(dictionary_copy.get_variable(variable_name).get_rule()),
+                        dictionary_copy.get_variable(variable_name).rule,
                         repr(some_reference_rule),
                     )
                 for variable_block_index, variable_block_name in enumerate(
@@ -2062,7 +2064,7 @@ def test_dictionary_accessors(self):
                         2,
                         kh.Rule("SomeEmbeddedRule()"),
                     )
-                    dictionary_copy.get_variable_block(variable_block_name).set_rule(
+                    dictionary_copy.get_variable_block(variable_block_name).rule = str(
                         some_rule
                     )
                     self.assertEqual(
@@ -2070,23 +2072,13 @@ def test_dictionary_accessors(self):
                         repr(some_rule),
                     )
                     self.assertEqual(
-                        repr(
-                            dictionary_copy.get_variable_block(
-                                variable_block_name
-                            ).get_rule()
-                        ),
+                        dictionary_copy.get_variable_block(variable_block_name).rule,
                         repr(some_rule),
                     )
-                    some_reference_rule = kh.Rule(
-                        "some_reference_operand_for_variable block"
-                        + variable_block_index * "i",
-                        3,
-                        is_reference=True,
-                    )
-                    with self.assertRaises(ValueError):
-                        dictionary_copy.get_variable_block(
-                            variable_block_name
-                        ).set_rule(some_reference_rule)
+                    with self.assertRaises(TypeError):
+                        dictionary_copy.get_variable_block(variable_block_name).rule = (
+                            some_rule
+                        )
 
     def test_dictionary_rule_construction(self):
         """Tests the Rule construction and serialization"""

From 0afeba6eae06fe9c67c92eafc4c49baa2584d49d Mon Sep 17 00:00:00 2001
From: Popescu V <136721202+popescu-v@users.noreply.github.com>
Date: Tue, 30 Sep 2025 11:21:58 +0200
Subject: [PATCH 2/6] Reformat _check_name function docstring

---
 khiops/core/dictionary.py | 10 +++++-----
 1 file changed, 5 insertions(+), 5 deletions(-)

diff --git a/khiops/core/dictionary.py b/khiops/core/dictionary.py
index 7a5f82b1..a9662c3b 100644
--- a/khiops/core/dictionary.py
+++ b/khiops/core/dictionary.py
@@ -79,15 +79,15 @@ def _quote_value(value):
 
 
 def _check_name(name):
-    """Ensures the variable name is consistent
-    with the Khiops core name constraints
+    """Ensures the variable name is consistent with the Khiops core name constraints
+
+    Plain string or bytes are both accepted as input. The Khiops core forbids a name:
 
-    Plain string or bytes are both accepted as input.
-    The Khiops core forbids a name
         - with a length outside the [1,128] interval
         - containing a simple (Unix) carriage-return (\n)
         - with leading and trailing spaces.
-    This function must check at least these constraints.
+
+    This function must check these constraints.
 
     Parameters
     ----------

From d6043e23171bfc7be01d5773059ba167d55838b3 Mon Sep 17 00:00:00 2001
From: Popescu V <136721202+popescu-v@users.noreply.github.com>
Date: Tue, 30 Sep 2025 11:22:39 +0200
Subject: [PATCH 3/6] Improve no-operand rule specification: automatically
 insert parentheses

Indeed, parenthesized no-operand rule specification can only be done via
the `verbatim` parameter.
---
 doc/samples/samples.rst      |  4 ++--
 khiops/core/dictionary.py    | 15 +++++++++------
 khiops/samples/samples.ipynb |  4 ++--
 khiops/samples/samples.py    |  4 ++--
 tests/test_core.py           | 14 ++++++--------
 5 files changed, 21 insertions(+), 20 deletions(-)

diff --git a/doc/samples/samples.rst b/doc/samples/samples.rst
index 1a3228ea..a0ee41b3 100644
--- a/doc/samples/samples.rst
+++ b/doc/samples/samples.rst
@@ -97,7 +97,7 @@ Samples
     third_dictionary.add_variable_from_spec(
         name="computed",
         type="Numerical",
-        rule=str(kh.Rule("Ceil", kh.Rule("Product", 3, kh.Rule("Random()")))),
+        rule=str(kh.Rule("Ceil", kh.Rule("Product", 3, kh.Rule("Random")))),
     )
 
     # Add the variables used in a multi-table context in the first dictionary.
@@ -650,7 +650,7 @@ Samples
     # Create fold indexing rule and set it on `fold_index_variable`
     fold_index_variable = dictionary.get_variable("FoldIndex")
     fold_index_variable.rule = str(
-        kh.Rule("Ceil", kh.Rule("Product", fold_number, kh.Rule("Random()"))),
+        kh.Rule("Ceil", kh.Rule("Product", fold_number, kh.Rule("Random"))),
     )
 
     # Add variables that indicate if the instance is in the train dataset:
diff --git a/khiops/core/dictionary.py b/khiops/core/dictionary.py
index a9662c3b..8f8df10f 100644
--- a/khiops/core/dictionary.py
+++ b/khiops/core/dictionary.py
@@ -1755,9 +1755,9 @@ def write(self, writer):
             raise TypeError(type_error_message("writer", writer, KhiopsOutputWriter))
 
         # Write standard rule
-        rule_pattern = r"^[A-Z]([a-zA-Z]*)\(?.*\)?$"
-        rule_regex = re.compile(rule_pattern)
-        bytes_rule_regex = re.compile(bytes(rule_pattern, encoding="ascii"))
+        rule_name_pattern = r"^[A-Z]([a-zA-Z]*)$"
+        rule_name_regex = re.compile(rule_name_pattern)
+        bytes_rule_name_regex = re.compile(bytes(rule_name_pattern, encoding="ascii"))
         if self.operands:
             if self.is_reference:
                 writer.write("[")
@@ -1788,11 +1788,14 @@ def write(self, writer):
         # Write no-operand rule
         elif (
             isinstance(self.name, str)
-            and rule_regex.match(self.name)
+            and rule_name_regex.match(self.name)
             or isinstance(self.name, bytes)
-            and bytes_rule_regex.match(self.name)
+            and bytes_rule_name_regex.match(self.name)
         ):
-            writer.write(self.name)
+            writer.write(_format_name(self.name))
+
+            # Add parentheses automatically
+            writer.write("()")
         # Write verbatim-given rule
         elif self._verbatim:
             writer.write(self._verbatim)
diff --git a/khiops/samples/samples.ipynb b/khiops/samples/samples.ipynb
index 108b4086..13242e98 100644
--- a/khiops/samples/samples.ipynb
+++ b/khiops/samples/samples.ipynb
@@ -109,7 +109,7 @@
     "third_dictionary.add_variable_from_spec(\n",
     "    name=\"computed\",\n",
     "    type=\"Numerical\",\n",
-    "    rule=str(kh.Rule(\"Ceil\", kh.Rule(\"Product\", 3, kh.Rule(\"Random()\")))),\n",
+    "    rule=str(kh.Rule(\"Ceil\", kh.Rule(\"Product\", 3, kh.Rule(\"Random\")))),\n",
     ")\n",
     "\n",
     "# Add the variables used in a multi-table context in the first dictionary.\n",
@@ -870,7 +870,7 @@
     "# Create fold indexing rule and set it on `fold_index_variable`\n",
     "fold_index_variable = dictionary.get_variable(\"FoldIndex\")\n",
     "fold_index_variable.rule = str(\n",
-    "    kh.Rule(\"Ceil\", kh.Rule(\"Product\", fold_number, kh.Rule(\"Random()\"))),\n",
+    "    kh.Rule(\"Ceil\", kh.Rule(\"Product\", fold_number, kh.Rule(\"Random\"))),\n",
     ")\n",
     "\n",
     "# Add variables that indicate if the instance is in the train dataset:\n",
diff --git a/khiops/samples/samples.py b/khiops/samples/samples.py
index 7ca3be09..c5df0703 100644
--- a/khiops/samples/samples.py
+++ b/khiops/samples/samples.py
@@ -111,7 +111,7 @@ def create_dictionary_domain():
     third_dictionary.add_variable_from_spec(
         name="computed",
         type="Numerical",
-        rule=str(kh.Rule("Ceil", kh.Rule("Product", 3, kh.Rule("Random()")))),
+        rule=str(kh.Rule("Ceil", kh.Rule("Product", 3, kh.Rule("Random")))),
     )
 
     # Add the variables used in a multi-table context in the first dictionary.
@@ -725,7 +725,7 @@ def train_predictor_with_cross_validation():
     # Create fold indexing rule and set it on `fold_index_variable`
     fold_index_variable = dictionary.get_variable("FoldIndex")
     fold_index_variable.rule = str(
-        kh.Rule("Ceil", kh.Rule("Product", fold_number, kh.Rule("Random()"))),
+        kh.Rule("Ceil", kh.Rule("Product", fold_number, kh.Rule("Random"))),
     )
 
     # Add variables that indicate if the instance is in the train dataset:
diff --git a/tests/test_core.py b/tests/test_core.py
index 990743da..94937396 100644
--- a/tests/test_core.py
+++ b/tests/test_core.py
@@ -1904,9 +1904,7 @@ def test_dictionary_accessors(self):
                     name="fresh_one",
                     type="Categorical",
                     meta_data={"a": 1, "b": 2},
-                    rule=str(
-                        kh.Rule("Ceil", kh.Rule("Product", 3, kh.Rule("Random()")))
-                    ),
+                    rule=str(kh.Rule("Ceil", kh.Rule("Product", 3, kh.Rule("Random")))),
                 )
                 self.assertEqual(
                     2,
@@ -2020,7 +2018,7 @@ def test_dictionary_accessors(self):
                         "SomeRuleForVariable" + variable_index * "i",
                         "an_operand",
                         2,
-                        kh.Rule("SomeEmbeddedRule()"),
+                        kh.Rule("SomeEmbeddedRule"),
                     )
                     dictionary_copy.get_variable(variable_name).rule = str(some_rule)
                     self.assertEqual(
@@ -2062,7 +2060,7 @@ def test_dictionary_accessors(self):
                         "SomeRuleForVariableBlock" + variable_block_index * "i",
                         "an_operand",
                         2,
-                        kh.Rule("SomeEmbeddedRule()"),
+                        kh.Rule("SomeEmbeddedRule"),
                     )
                     dictionary_copy.get_variable_block(variable_block_name).rule = str(
                         some_rule
@@ -2083,8 +2081,8 @@ def test_dictionary_accessors(self):
     def test_dictionary_rule_construction(self):
         """Tests the Rule construction and serialization"""
         rule_verbatims = [
-            "SomeRule",
-            b"SomeRule",
+            "SomeRule()",
+            b"SomeRule()",
             'SomeRule("some_operand", 2)',
             b'SomeRule("some_operand", 2)',
             'SomeRule("some""operand", 2)',
@@ -2260,7 +2258,7 @@ def test_dictionary_rule_construction(self):
                     kh.Rule(b"SomeEmbeddedRule", b"some_other_operand"),
                 ),
                 kh.Rule(
-                    (
+                    verbatim=(
                         b'SomeRule("some_operand", 2, '
                         b'SomeEmbeddedRule("some_other_operand"))'
                     )

From 1dd711b5f4411ee895b28f4b54fcbb623ae134d2 Mon Sep 17 00:00:00 2001
From: Popescu V <136721202+popescu-v@users.noreply.github.com>
Date: Tue, 30 Sep 2025 14:56:33 +0200
Subject: [PATCH 4/6] Improve `Rule` documentation

- add rule creation examples
- add details to the docstring of the `Rule.write` method.
---
 khiops/core/dictionary.py | 92 +++++++++++++++++++++++++++++++++++++++
 1 file changed, 92 insertions(+)

diff --git a/khiops/core/dictionary.py b/khiops/core/dictionary.py
index 8f8df10f..f17186cc 100644
--- a/khiops/core/dictionary.py
+++ b/khiops/core/dictionary.py
@@ -1660,6 +1660,91 @@ class Rule:
 
         .. note::
             This attribute cannot be changed on a `Rule` instance.
+
+    Examples
+    --------
+        - basic rule, with variables as operands:
+            - verbatim:
+                .. code-block::
+
+                    Product(PetalLength, PetalWidth)
+
+            - object construction:
+                .. highlight:: python
+                .. code-block:: python
+
+                    petal_length_var = kh.Variable()
+                    petal_length_var.name = "PetalLength"
+                    petal_length_var.type = "Numerical"
+                    petal_width_var = kh.Variable()
+                    petal_width_var.name = "PetalWidth"
+                    petal_width_var.type = "Numerical"
+                    rule = kh.Rule("Product", petal_length_var, petal_width_var)
+
+        - multi-table rule:
+            - verbatim:
+                .. code-block::
+
+                    TableCount(
+                        TableSelection(
+                            Vehicles,
+                            EQ(PassengerNumber, 1)
+                        )
+                    )
+
+            - object construction:
+                .. highlight:: python
+                .. code-block:: python
+
+                    vehicles_var = accidents_dictionary.get_variable("Vehicles")
+                    passenger_number_var = vehicles_dictionary.get_variable(
+                        "PassengerNumber"
+                    )
+                    rule = kh.Rule(
+                        "TableCount",
+                        kh.Rule(
+                            "TableSelection",
+                            vehicles_var,
+                            kh.Rule("EQ", passenger_number_var, 1)
+                        )
+                    )
+
+        - multi-table rule with upper-scoped operands (advanced usage):
+            - verbatim:
+                .. code-block::
+
+                    TableSelection(
+                        Vehicles,
+                        EQ(
+                            PassengerNumber,
+                            .TableMax(Vehicles, PassengerNumber)
+                        )
+                    )
+
+            - object construction:
+                .. highlight:: python
+                .. code-block:: python
+
+                    vehicles_var = accidents_dictionary.get_variable("Vehicles")
+                    passenger_number_var = vehicles_dictionary.get_variable(
+                        "PassengerNumber"
+                    )
+                    rule = kh.Rule(
+                        "TableSelection",
+                        vehicles_var,
+                        kh.Rule(
+                            "EQ",
+                            passenger_number_var,
+                            kh.upper_scope(
+                                kh.Rule(
+                                    "TableMax",
+                                    vehicle_var,
+                                    passenger_number_var
+                                )
+                            )
+                        )
+                    )
+
     """
 
     def __init__(self, *name_and_operands, verbatim=None, is_reference=False):
@@ -1742,6 +1827,13 @@ def copy(self):
     def write(self, writer):
         """Writes the rule to a file writer in the ``.kdic`` format
 
+        This method ensures proper `Rule` serialization, automatically handling:
+
+            - back-quote recoding in variable names
+            - double-quote recoding in categorical constants
+            - missing data (``inf``, ``-inf``, ``NaN``) serialization as ``#Missing``
+            - upper-scope operator serialization as ``.``
+
         Parameters
         ----------
         writer : `.KhiopsOutputWriter`

From 1c443b132ffeea4aa90fa6667d16ee867b3eec98 Mon Sep 17 00:00:00 2001
From: Popescu V <136721202+popescu-v@users.noreply.github.com>
Date: Tue, 30 Sep 2025 17:40:09 +0200
Subject: [PATCH 5/6] Remove deprecated batch_mode Core API kwarg from the doc

---
 doc/notes.rst | 3 ---
 1 file changed, 3 deletions(-)

diff --git a/doc/notes.rst b/doc/notes.rst
index 4b51f053..339d7940 100644
--- a/doc/notes.rst
+++ b/doc/notes.rst
@@ -47,9 +47,6 @@ scenario_prologue: str, default ""
 force_ansi_scenario : bool, default ``False``
     *Advanced* If True the internal scenario generated by Khiops will force characters such as
     accentuated ones to be decoded with the UTF8->ANSI khiops transformation.
-batch_mode : bool, default ``True``
-    *Deprecated* Will be removed in Khiops 11. If ``True`` activates batch mode (command line option
-    ``-b`` of the desktop app).
 
 .. _core-api-input-types:
 

From de21b9a6e358c8500410e892d635b7460ae9149f Mon Sep 17 00:00:00 2001
From: Popescu V <136721202+popescu-v@users.noreply.github.com>
Date: Tue, 30 Sep 2025 18:12:42 +0200
Subject: [PATCH 6/6] Update CHANGELOG

---
 CHANGELOG.md | 3 +--
 1 file changed, 1 insertion(+), 2 deletions(-)

diff --git a/CHANGELOG.md b/CHANGELOG.md
index fa73097f..e02e761e 100644
--- a/CHANGELOG.md
+++ b/CHANGELOG.md
@@ -11,8 +11,7 @@
 ### Added
 - (`core`) Dictionary API support for dictionary, variable and variable block
   comments, and dictionary and variable block internal comments.
-- (`core`) Dictionary `Rule` class and supporting API for adding and getting
-  rules to / from variables and variable blocks.
+- (`core`) Dictionary `Rule` class and supporting API for serializing `Rule` instances.
 - (`core`) New way to add a variable to a dictionary using a complete specification.
 - (`sklearn`) `Text` Khiops type support at the estimator level.