Streamline Rule object support for reference and verbatim rules

Author: popescu-v

khiops/core/dictionary.py

@@ -1187,7 +1187,7 @@ def full_type(self):
 
     def get_rule(self):
         """Gets `Rule` from a specified variable"""
-        return Rule(name=self.rule)
+        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
@@ -1383,7 +1383,7 @@ def get_value(self, key):
 
     def get_rule(self):
         """Gets `Rule` from a specified variable block"""
-        return Rule(name=self.rule)
+        return Rule(verbatim=self.rule)
 
     def set_rule(self, rule):
         """Sets a rule on a specified variable block in the dictionary
@@ -1397,9 +1397,14 @@ def set_rule(self, rule):
         ------
         `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):
@@ -1459,16 +1464,8 @@ class Rule:
 
     Parameters
     ----------
-    name : str or bytes
-        Name or verbatim of the rule. It is intepreted as the verbatim
-        representation of an entire rule if and only if:
-
-            - it starts with an UpperCamelCase string, followed by a
-              parenthesized block (...)
-            - ``operands`` is empty
-
-    operands : tuple of operands
-        Each operand can have one of the following types:
+    name_and_operands : tuple of rule fragments
+        Each rule fragment can have one of the following types:
 
             - str
             - bytes
@@ -1479,6 +1476,17 @@ class Rule:
             - upper-scoped `Variable`
             - upper-scoped `Rule`
 
+        .. note::
+            The first element of the ``name_and_operands`` tuple is the name of
+            the rule and must be str or bytes and non-empty for a standard rule,
+            i.e. if ``is_reference`` is not set.
+
+    verbatim : str or bytes, optional
+        Verbatim representation of an entire rule.
+
+        .. note::
+            ``names_and_operands`` must be empty if ``verbatim`` is set.
+
     is_reference : bool, default ``False``
         If set to ``True``, then the rule is serialized as a reference rule:
         ``Rule(Operand1, Operand2, ...)`` is serialized as
@@ -1487,7 +1495,7 @@ class Rule:
     Attributes
     ----------
     name : str or bytes
-        Name of the rule.
+        Name of the rule. It is ``None`` for reference rules.
     operands : tuple of operands
         Each operand has one of the following types:
 
@@ -1507,12 +1515,47 @@ class Rule:
             This attribute cannot be changed on a `Rule` instance.
     """
 
-    def __init__(self, name, *operands, is_reference=False):
+    def __init__(self, *name_and_operands, verbatim=None, is_reference=False):
         """See class docstring"""
-        # Check input parameters
-        if not is_string_like(name):
-            raise TypeError(type_error_message("name", name, "string-like"))
-        for operand in operands:
+        # Check input parameters and initialize rule fragments accordigly
+        if not isinstance(is_reference, bool):
+            raise TypeError(type_error_message("is_reference", is_reference, bool))
+        if verbatim is not None:
+            if not is_string_like(verbatim):
+                raise TypeError(type_error_message("verbatim", verbatim, "string-like"))
+            if not verbatim:
+                raise ValueError(
+                    "'verbatim' must not be set to an empty string-like object"
+                )
+            if name_and_operands:
+                raise ValueError(
+                    "Rule name and operands must not be provided for verbatim rules"
+                )
+            self.name = None
+            self.operands = ()
+        else:
+            if not name_and_operands:
+                raise ValueError("A name must be provided to a standard rule")
+            if is_reference:
+                self.name = None
+                self.operands = name_and_operands
+            else:
+                name, *operands = name_and_operands
+                if not is_string_like(name):
+                    raise TypeError(type_error_message("name", name, "string-like"))
+                if not name:
+                    raise ValueError("'name' must be a non-empty string")
+                self.name = name
+                self.operands = operands
+
+        self._check_operands()
+
+        # Initialize private attributes
+        self._verbatim = verbatim
+        self._is_reference = is_reference
+
+    def _check_operands(self):
+        for operand in self.operands:
             if not is_string_like(operand) and not isinstance(
                 operand, (int, float, Variable, Rule, _ScopedOperand)
             ):
@@ -1529,15 +1572,6 @@ def __init__(self, name, *operands, is_reference=False):
                         "upper-scoped Rule",
                     )
                 )
-        if not isinstance(is_reference, bool):
-            raise TypeError(type_error_message("is_reference", is_reference, bool))
-        if not is_reference and not name:
-            raise ValueError("'name' must be a non-empty string")
-
-        # Initialize attributes
-        self.name = name
-        self.operands = operands
-        self._is_reference = is_reference
 
     @property
     def is_reference(self):
@@ -1568,8 +1602,8 @@ def write(self, writer):
             Output writer.
 
             .. note::
-                If ``self.is_reference`` is set, then ``self.name`` is not
-                included in the serialization.
+                ``self.name`` is not included in the serialization of reference
+                rules.
         """
         # Check the type of the writer
         if not isinstance(writer, KhiopsOutputWriter):
@@ -1606,14 +1640,17 @@ def write(self, writer):
                 writer.write("]")
             else:
                 writer.write(")")
-        # Write verbatim-given rule
+        # Write no-operand rule
         elif (
             isinstance(self.name, str)
             and rule_regex.match(self.name)
             or isinstance(self.name, bytes)
             and bytes_rule_regex.match(self.name)
         ):
             writer.write(self.name)
+        # Write verbatim-given rule
+        elif self._verbatim:
+            writer.write(self._verbatim)
 
 
 class _ScopedOperand:

tests/test_core.py

@@ -1945,9 +1945,26 @@ def test_dictionary_accessors(self):
                         repr(dictionary_copy.get_variable(variable_name).get_rule()),
                         repr(some_rule),
                     )
+                    some_reference_rule = kh.Rule(
+                        "some_reference_operand_for_variable" + variable_index * "i",
+                        kh.Variable(
+                            json_data={
+                                "name": "SomeReferenceVariable" + variable_index * "i",
+                                "type": "Categorical",
+                            }
+                        ),
+                        is_reference=True,
+                    )
+                    dictionary_copy.get_variable(variable_name).set_rule(
+                        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()),
-                        repr(some_rule),
+                        repr(some_reference_rule),
                     )
                 for variable_block_index, variable_block_name in enumerate(
                     [
@@ -1976,6 +1993,16 @@ def test_dictionary_accessors(self):
                         ),
                         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)
 
     def test_dictionary_rule_construction(self):
         """Tests the Rule construction and serialization"""
@@ -2019,11 +2046,11 @@ def test_dictionary_rule_construction(self):
             [kh.Rule(b"SomeRule")],
             [
                 kh.Rule("SomeRule", "some_operand", 2),
-                kh.Rule('SomeRule("some_operand", 2)'),
+                kh.Rule(verbatim='SomeRule("some_operand", 2)'),
             ],
             [
                 kh.Rule(b"SomeRule", b"some_operand", 2),
-                kh.Rule(b'SomeRule("some_operand", 2)'),
+                kh.Rule(verbatim=b'SomeRule("some_operand", 2)'),
             ],
             [
                 kh.Rule("SomeRule", 'some"operand', 2),
@@ -2032,7 +2059,7 @@ def test_dictionary_rule_construction(self):
                 kh.Rule(b"SomeRule", b'some"operand', 2),
             ],
             [
-                kh.Rule('SomeRule("some_operand", 2, SomeVariable)'),
+                kh.Rule(verbatim='SomeRule("some_operand", 2, SomeVariable)'),
                 kh.Rule(
                     "SomeRule",
                     "some_operand",
@@ -2127,13 +2154,13 @@ def test_dictionary_rule_construction(self):
                 kh.Rule("SomeRule", "some_operand", math.nan),
                 kh.Rule("SomeRule", "some_operand", float("inf")),
                 kh.Rule("SomeRule", "some_operand", float("-inf")),
-                kh.Rule('SomeRule("some_operand", #Missing)'),
+                kh.Rule(verbatim='SomeRule("some_operand", #Missing)'),
             ],
             [
                 kh.Rule(b"SomeRule", b"some_operand", math.nan),
                 kh.Rule(b"SomeRule", b"some_operand", float("inf")),
                 kh.Rule(b"SomeRule", b"some_operand", float("-inf")),
-                kh.Rule(b'SomeRule("some_operand", #Missing)'),
+                kh.Rule(verbatim=b'SomeRule("some_operand", #Missing)'),
             ],
             [
                 kh.Rule(
@@ -2143,10 +2170,10 @@ def test_dictionary_rule_construction(self):
                     kh.Rule("SomeEmbeddedRule", "some_other_operand"),
                 ),
                 kh.Rule(
-                    (
+                    verbatim=(
                         'SomeRule("some_operand", 2, '
                         'SomeEmbeddedRule("some_other_operand"))'
-                    )
+                    ),
                 ),
             ],
             [
@@ -2195,11 +2222,10 @@ def test_dictionary_rule_construction(self):
                     ),
                 )
             ],
-            [kh.Rule("", "some_reference_operand", is_reference=True)],
-            [kh.Rule(b"", b"some_reference_operand", is_reference=True)],
+            [kh.Rule("some_reference_operand", is_reference=True)],
+            [kh.Rule(b"some_reference_operand", is_reference=True)],
             [
                 kh.Rule(
-                    "",
                     "some_reference_operand",
                     kh.Variable(
                         json_data={
@@ -2212,7 +2238,6 @@ def test_dictionary_rule_construction(self):
             ],
             [
                 kh.Rule(
-                    b"",
                     b"some_reference_operand",
                     kh.Variable(
                         json_data={