Add a way to add a variable to a dictionary using a complete specification

Thierry RAMORASOAVINA · Thierry RAMORASOAVINA · commit 2e7cdc5bdd48 · 2025-09-11T10:51:36.000+02:00
diff --git a/CHANGELOG.md b/CHANGELOG.md
@@ -11,6 +11,7 @@
 ### Added
 - (`core`) Dictionary API support for dictionary, variable and variable block
   comments, and dictionary and variable block internal comments.
+- (`core`) Additional way to add a variable to a dictionary using a complete specification
 - (`sklearn`) `Text` Khiops type support at the estimator level.
 
 ### Fixed
diff --git a/doc/samples/samples.rst b/doc/samples/samples.rst
@@ -83,6 +83,8 @@ Samples
         var.name = var_spec["name"]
         var.type = var_spec["type"]
         root_dictionary.add_variable(var)
+    # another way to add a variable
+    root_dictionary.add_variable_from_spec(name="other_ts", type="TimestampTZ")
 
     # Create a second dictionary
     second_dictionary = kh.Dictionary(
diff --git a/khiops/core/dictionary.py b/khiops/core/dictionary.py
@@ -738,6 +738,88 @@ def get_variable_block(self, variable_block_name):
         """
         return self._variable_blocks_by_name[variable_block_name]
 
+    def add_variable_from_spec(self, name, type, **variable_spec):
+        """Adds a variable to this dictionary using a complete specification
+
+        Parameters
+        ----------
+            name : str
+                Variable name
+            type : str
+                Variable type
+                    See `Variable`
+            variable_spec : dict
+                Additional specification for the variable.
+                The recognized keys and their corresponding values are currently
+                    - label: str, optional -
+                        label of the variable (None by default)
+                    - used: bool, optional -
+                        usage status of the variable (True by default)
+                    - object_type: str, optional -
+                        object type (None by default;
+                            ignored if variable_type not in ["Entity", "Table"])
+                    - structure_type: str, optional -
+                        structure type (None by default;
+                            ignored if variable_type != "Structure")
+                    - meta_data: dict, optional - a Python dictionary
+                        which holds the metadata specification
+
+        Raises
+        ------
+
+        `ValueError`
+            If the variable name is empty or does not comply to the format rule.
+            If there is already a variable with the same name.
+            If the given variable type is unknown.
+            If a native type is given 'object_type' or 'structure_type'
+            If the 'meta_data' is not a dictionary
+        """
+        if not name:
+            raise ValueError(
+                "Cannot add to dictionary unnamed variable " f"(name = '{name}')"
+            )
+        if not Variable._is_a_valid_variable_name(name):
+            raise ValueError(
+                f"New variable name '{name}' cannot be accepted "
+                "(invalid length or characters)"
+            )
+        if name in self._variables_by_name:
+            raise ValueError(f"Dictionary already has a variable named '{name}'")
+        if type not in Variable.__all_types__:
+            raise ValueError(
+                f"Invalid type '{type}', "
+                f"not in the allowed list {Variable.__all_types__}"
+            )
+        if type in Variable.__native_types__:
+            if "object_type" in variable_spec or "structure_type" in variable_spec:
+                raise ValueError(
+                    f"Native type '{type}' "
+                    "cannot have 'object_type' or 'structure_type'"
+                )
+        if type in Variable.__object_types__ and "object_type" not in variable_spec:
+            raise ValueError(f"'object_type' must be provided for type '{type}'")
+        variable = Variable()
+        variable.name = name
+        variable.type = type
+        if "used" in variable_spec:
+            if not isinstance(variable_spec["used"], bool):
+                raise ValueError("'used' must be a boolean")
+            else:
+                variable.used = variable_spec["used"]
+        if "meta_data" in variable_spec:
+            if not isinstance(variable_spec["meta_data"], dict):
+                raise ValueError("'meta_data' must be a dict")
+            else:
+                variable.meta_data = MetaData(variable_spec["meta_data"])
+        if "label" in variable_spec:
+            variable.label = variable_spec["label"]
+        if "object_type" in variable_spec:
+            variable.object_type = variable_spec["object_type"]
+        if "structure_type" in variable_spec:
+            variable.structure_type = variable_spec["structure_type"]
+        self.variables.append(variable)
+        self._variables_by_name[variable.name] = variable
+
     def add_variable(self, variable):
         """Adds a variable to this dictionary
 
@@ -1007,6 +1089,43 @@ class Variable:
         - `samples.create_dictionary_domain()`
     """
 
+    # Variables types
+    CATEGORICAL_TYPE = "Categorical"
+    NUMERICAL_TYPE = "Numerical"
+    TIME_TYPE = "Time"
+    DATE_TYPE = "Date"
+    TIMESTAMP_TYPE = "Timestamp"
+    TIMESTAMP_TZ_TYPE = "TimestampTZ"
+    TEXT_TYPE = "Text"
+    TEXTLIST_TYPE = "TextList"
+    STRUCTURE_TYPE = "Structure"
+    ENTITY_TYPE = "Entity"
+    TABLE_TYPE = "Table"
+    __all_types__ = (
+        CATEGORICAL_TYPE,
+        NUMERICAL_TYPE,
+        TIME_TYPE,
+        DATE_TYPE,
+        TIMESTAMP_TYPE,
+        TIMESTAMP_TZ_TYPE,
+        TEXT_TYPE,
+        TEXTLIST_TYPE,
+        STRUCTURE_TYPE,
+        ENTITY_TYPE,
+        TABLE_TYPE,
+    )
+    __native_types__ = (
+        CATEGORICAL_TYPE,
+        NUMERICAL_TYPE,
+        TIME_TYPE,
+        DATE_TYPE,
+        TIMESTAMP_TYPE,
+        TIMESTAMP_TZ_TYPE,
+        TEXT_TYPE,
+    )
+    __internal_types__ = (TEXTLIST_TYPE, STRUCTURE_TYPE)
+    __object_types__ = (ENTITY_TYPE, TABLE_TYPE)
+
     def __init__(self, json_data=None):
         """See class docstring"""
         # Check the type of json_data
@@ -1055,9 +1174,9 @@ def __init__(self, json_data=None):
         self.type = json_data.get("type")
 
         # Initialize complement of the type
-        if self.type in ("Entity", "Table"):
+        if self.type in Variable.__object_types__:
             self.object_type = json_data.get("objectType")
-        elif self.type == "Structure":
+        elif self.type == Variable.STRUCTURE_TYPE:
             self.structure_type = json_data.get("structureType")
 
         # Initialize derivation rule
@@ -1069,7 +1188,7 @@ def __init__(self, json_data=None):
             self.meta_data = MetaData(json_meta_data)
 
     def __repr__(self):
-        """Returns a human readable string representation"""
+        """Returns a human-readable string representation"""
         return f"Variable ({self.name})"
 
     def __str__(self):
@@ -1078,6 +1197,19 @@ def __str__(self):
         self.write(writer)
         return str(stream.getvalue(), encoding="utf8", errors="replace")
 
+    @staticmethod
+    def _is_a_valid_variable_name(name):
+        """Ensures the variable name is valid.
+        Please note 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
+                (\s in Perl-Compatible-Regular-Expressions syntax).
+        This function must check at least these constraints
+        """
+        variable_name_regexp = re.compile(r"^[a-zA-Z][a-zA-Z0-9_]{1,128}$")
+        return variable_name_regexp.match(name)
+
     def copy(self):
         """Copies this variable instance
 
@@ -1169,9 +1301,9 @@ def full_type(self):
             basic.
         """
         full_type = self.type
-        if self.type in ("Entity", "Table"):
+        if self.type in Variable.__object_types__:
             full_type += f"({self.object_type})"
-        elif self.type == "Structure":
+        elif self.type == Variable.STRUCTURE_TYPE:
             full_type += f"({self.structure_type})"
         return full_type
 
diff --git a/khiops/samples/samples.ipynb b/khiops/samples/samples.ipynb
@@ -95,6 +95,8 @@
     "    var.name = var_spec[\"name\"]\n",
     "    var.type = var_spec[\"type\"]\n",
     "    root_dictionary.add_variable(var)\n",
+    "# another way to add a variable\n",
+    "root_dictionary.add_variable_from_spec(name=\"other_ts\", type=\"TimestampTZ\")\n",
     "\n",
     "# Create a second dictionary\n",
     "second_dictionary = kh.Dictionary(\n",
diff --git a/khiops/samples/samples.py b/khiops/samples/samples.py
@@ -95,6 +95,8 @@ def create_dictionary_domain():
         var.name = var_spec["name"]
         var.type = var_spec["type"]
         root_dictionary.add_variable(var)
+    # another way to add a variable
+    root_dictionary.add_variable_from_spec(name="other_ts", type="TimestampTZ")
 
     # Create a second dictionary
     second_dictionary = kh.Dictionary(
diff --git a/tests/test_core.py b/tests/test_core.py
@@ -1836,6 +1836,52 @@ def test_dictionary_accessors(self):
                 variable.name = ""
                 with self.assertRaises(ValueError):
                     dictionary_copy.add_variable(variable)
+                # Thoroughly test Dictionary.add_variable_from_spec
+                # (using a part of the exception message to ensure
+                # the actual error is raised)
+                # empty name is forbidden
+                with self.assertRaisesRegex(ValueError, "unnamed"):
+                    dictionary.add_variable_from_spec(name="", type="Categorical")
+                # too long name is forbidden
+                with self.assertRaisesRegex(ValueError, "cannot be accepted"):
+                    dictionary.add_variable_from_spec(
+                        name="A" * 200, type="Categorical"
+                    )
+                # the name must not contain forbidden characters
+                with self.assertRaisesRegex(ValueError, "cannot be accepted"):
+                    dictionary.add_variable_from_spec(
+                        name="ALLFDLFDFDLLL\t", type="Categorical"
+                    )
+                # successful adding
+                dictionary.add_variable_from_spec(name="label", type="Categorical")
+                # duplicate name is forbidden
+                with self.assertRaisesRegex(ValueError, "already"):
+                    dictionary.add_variable_from_spec(name="label", type="Numerical")
+                # type must be recognized
+                with self.assertRaisesRegex(ValueError, "Invalid type"):
+                    dictionary.add_variable_from_spec(
+                        name="fresh_one", type="Unknowntype"
+                    )
+                # native types cannot accept object_type or structure_type
+                with self.assertRaisesRegex(ValueError, "Native type"):
+                    dictionary.add_variable_from_spec(
+                        name="fresh_one", type="Numerical", object_type="X"
+                    )
+                # object type must have a object_type parameter
+                with self.assertRaisesRegex(
+                    ValueError, "'object_type' must be provided"
+                ):
+                    dictionary.add_variable_from_spec(name="fresh_one", type="Entity")
+                # used must be a boolean
+                with self.assertRaisesRegex(ValueError, "boolean"):
+                    dictionary.add_variable_from_spec(
+                        name="fresh_one", type="Numerical", used="True"
+                    )
+                # meta data must be valid
+                with self.assertRaisesRegex(ValueError, "meta_data"):
+                    dictionary.add_variable_from_spec(
+                        name="fresh_one", type="Categorical", meta_data="str"
+                    )
 
                 # Test Dictionary variable block accessors
                 # Create a simple block
