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

Author: popescu-v

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,15 +649,15 @@ 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()"))),
     )
 
     # Add variables that indicate if the instance is in the train dataset:
     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),
         )
 

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,18 @@ def write(self, writer):
 class Rule:
     """A rule of a variable or variable block in a Khiops dictionary
 
+    .. note::
+        This object is a convenience feature which easies rule creation and
+        serialization, especially in rather complex cases (rule operands which
+        are variables or rules themselves, sometimes upper-scoped). Rules
+        continue be attached *as strings* to variables and variable blocks.
+
+    .. note::
+        Rule object 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

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,15 +869,15 @@
     "\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",
     "# Add variables that indicate if the instance is in the train dataset:\n",
     "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",

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,15 +724,15 @@ 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()"))),
     )
 
     # Add variables that indicate if the instance is in the train dataset:
     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),
         )
 

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,15 +2041,15 @@ 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(
                         dictionary_copy.get_variable(variable_name).rule,
                         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,31 +2064,21 @@ 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(
                         dictionary_copy.get_variable_block(variable_block_name).rule,
                         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"""