Add Khiops dictionary rule API support

- add a `Rule` class
- add `Dictionary.set_rule` and `Dictionary.get_rule` methods

Author: popescu-v

khiops/core/dictionary.py

@@ -13,6 +13,7 @@
 
 """
 import io
+import math
 import os
 import re
 import warnings
@@ -880,6 +881,124 @@ def remove_variable_block(
 
         return removed_block
 
+    def _check_name(self, name, name_label):
+        if not is_string_like(name):
+            raise TypeError(type_error_message(name_label, name, str))
+        if not name:
+            raise ValueError(f"'{name_label}' must not be empty")
+
+    def _set_rule(self, rule, name, label, getter):
+        # Perform input checks
+        self._check_name(name, label)
+        if not isinstance(rule, Rule):
+            raise TypeError(type_error_message("rule", rule, Rule))
+
+        # Get the object of "name" and set the serialized rule on it
+        getattr(self, getter)(name).rule = repr(rule)
+
+    def _get_rule(self, name, label, getter):
+        # Perform input checks
+        self._check_name(name, label)
+
+        # Get the serialized rule from the object of "name" and pack it into a
+        # `Rule`
+        return Rule(name=getattr(self, getter)(name).rule)
+
+    def set_variable_rule(self, variable_name, rule):
+        """Sets a rule on a specified variable in the dictionary
+
+        Parameters
+        ----------
+        variable_name : str
+            Name of the variable the rule is set on.
+        rule : `Rule`
+            The rule to be set on the variable whose name is ``variable_name``.
+
+        Raises
+        ------
+        `TypeError`
+            If ``rule`` is not of type `Rule`
+            If ``variable_name`` is not of type `str`
+
+        `ValueError`
+            If ``variable_name`` is the empty string
+
+        `KeyError`
+            If no variable of name ``variable_name`` exists in the dictionary
+        """
+        self._set_rule(rule, variable_name, "variable_name", "get_variable")
+
+    def set_variable_block_rule(self, variable_block_name, rule):
+        """Sets a rule on a specified variable block in the dictionary
+
+        Parameters
+        ----------
+        variable_block_name : str
+            Name of the variable block the rule is set on.
+        rule : `Rule`
+            The rule to be set on the variable block whose name is
+            ``variable_block_name``.
+
+        Raises
+        ------
+        `TypeError`
+            If ``rule`` is not of type `Rule`
+            If ``variable_block_name`` is not of type `str`
+
+        `ValueError`
+            If ``variable_block_name`` is the empty string
+
+        `KeyError`
+            If no variable block of name ``variable_block_name`` exists in the
+            dictionary
+        """
+        self._set_rule(
+            rule, variable_block_name, "variable_block_name", "get_variable_block"
+        )
+
+    def get_variable_rule(self, variable_name):
+        """Gets `Rule` from a specified variable
+
+        Parameters
+        ----------
+        variable_name : str
+            Name of the variable the rule is set on.
+
+        Raises
+        ------
+        `TypeError`
+            If ``variable_name`` is not of type `str`
+
+        `ValueError`
+            If ``variable_name`` is the empty string
+
+        `KeyError`
+            If no variable of name ``variable_name`` exists in the dictionary
+        """
+        self._get_rule(variable_name, "variable_name", "get_variable")
+
+    def get_variable_block_rule(self, variable_block_name):
+        """Gets `Rule` from a specified variable block
+
+        Parameters
+        ----------
+        variable_block_name : str
+            Name of the variable block_the rule is set on.
+
+        Raises
+        ------
+        `TypeError`
+            If ``variable_block_name`` is not of type `str`
+
+        `ValueError`
+            If ``variable_block_name`` is the empty string
+
+        `KeyError`
+            If no variable block of name ``variable_block_name`` exists in the
+            dictionary
+        """
+        self._get_rule(variable_block_name, "variable_block_name", "get_variable_block")
+
     def is_key_variable(self, variable):
         """Returns ``True`` if a variable belongs to this dictionary's key
 
@@ -978,8 +1097,10 @@ class Variable:
     rule : str
         Derivation rule or external table reference. Set to "" if there is no
         rule associated to this variable. Examples:
+
             - standard rule: "Sum(Var1, Var2)"
             - reference rule: "[TableName]"
+
     variable_block : `VariableBlock`
         Block to which the variable belongs. Not set if the variable does not belong to
         a block.
@@ -1386,6 +1507,134 @@ def write(self, writer):
         writer.writeln("")
 
 
+class Rule:
+    """A rule of a variable in a Khiops dictionary
+
+    Parameters
+    ----------
+    name : str
+        Name 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
+
+        It is intepreted as a reference rule if and only if:
+
+            - the first condition above does *not* apply
+            - the second condition above applies
+
+    operands : tuple of operands
+        Each operand can have one of the following types:
+
+            - str
+            - int
+            - float
+            - ``Variable``
+            - ``Rule``
+
+        If no operand is specified, then the rule is:
+
+            - a standard rule if ``name`` is the verbatim representation of an
+              entire rule
+            - a reference rule if ``name`` does not satisfy the condition above
+
+    Attributes
+    ----------
+    name : str
+        Name of the rule.
+    operands : tuple of operands
+        Each operand has one of the following types:
+
+            - str
+            - int
+            - float
+            - ``Variable``
+            - ``Rule``
+    """
+
+    def __init__(self, name, *operands):
+        """See class docstring"""
+
+        # Check the types of the parameters
+        if not isinstance(name, str):
+            raise TypeError(type_error_message("name", name, str))
+        for operand in operands:
+            if not isinstance(operand, (str, int, float, Variable, Rule)):
+                raise TypeError(
+                    type_error_message(
+                        f"Operand '{operand}'", operand, str, int, float, Variable, Rule
+                    )
+                )
+
+        # name must not be empty
+        if not name:
+            raise ValueError(f"'name' must be a non-empty string")
+
+        self.name = name
+        self.operands = operands
+
+    def __repr__(self):
+        stream = io.BytesIO()
+        writer = KhiopsOutputWriter(stream)
+        self.write(writer)
+        return str(stream.getvalue(), encoding="utf8", errors="replace")
+
+    def copy(self):
+        """Copies this rule instance
+
+        Returns
+        -------
+        `Rule`
+            A copy of this instance
+        """
+        return Rule(self.name, *self.operands)
+
+    def write(self, writer):
+        """Writes the rule to a file writer in the ``.kdic`` format
+
+        Parameters
+        ----------
+        writer : `.KhiopsOutputWriter`
+            Output writer.
+        """
+        # Check file object type
+        if not isinstance(writer, KhiopsOutputWriter):
+            raise TypeError(type_error_message("writer", writer, KhiopsOutputWriter))
+
+        # Write standard rule
+        rule_regex = re.compile(r"^[A-Z]([a-zA-Z]*)\(.*\)")
+        if self.operands:
+            n_operands = len(self.operands)
+            writer.write(f"{_format_name(self.name)}(")
+            for i, operand in enumerate(self.operands):
+                # Write operand, according to its type
+                # Variable operands have their name written only
+                if isinstance(operand, Rule):
+                    operand.write(writer)
+                elif isinstance(operand, Variable):
+                    writer.write(_format_name(operand.name))
+                elif isinstance(operand, str):
+                    writer.write(f'"{operand}"')
+                elif math.isnan(float(operand)):
+                    writer.write("#Missing")
+                else:
+                    writer.write(f"{operand}")
+                if i < n_operands - 1:
+                    writer.write(", ")
+            writer.write(")")
+
+        # Write verbatim-given rule
+        elif rule_regex.match(self.name):
+            writer.write(self.name)
+
+        # Write rule as a reference rule
+        else:
+            writer.write(f"[{self.name}]")
+
+
 class MetaData:
     """A metadata container for a dictionary, a variable or variable block
 

tests/test_core.py

@@ -1878,8 +1878,9 @@ def test_dictionary_accessors(self):
                     dictionary_copy.get_variable_block(block.name)
 
                 # Set the block as non-native add, and remove it
-                block.rule = "SomeBlockCreatingRule()"
                 dictionary_copy.add_variable_block(block)
+                block_rule = kh.Rule("SomeBlockCreatingRule()")
+                dictionary_copy.set_variable_block_rule(block.name, block_rule)
                 self.assertEqual(block, dictionary_copy.get_variable_block(block.name))
                 removed_block = dictionary_copy.remove_variable_block(
                     block.name,