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

Thierry RAMORASOAVINA · Thierry RAMORASOAVINA · commit 8e6db1bf1a15 · 2025-09-11T19:27:00.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`) New 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
@@ -79,40 +79,28 @@ Samples
         {"name": "ts", "type": "TimestampTZ"},
     ]
     for var_spec in simple_variables:
-        var = kh.Variable()
-        var.name = var_spec["name"]
-        var.type = var_spec["type"]
-        root_dictionary.add_variable(var)
+        root_dictionary.add_variable_from_spec(name=var_spec["name"], type=var_spec["type"])
 
     # Create a second dictionary
     second_dictionary = kh.Dictionary(
         json_data={"name": "Service", "key": ["Id", "id_product"]}
     )
-    second_dictionary.add_variable(
-        kh.Variable(json_data={"name": "Id", "type": "Categorical"})
-    )
-    second_dictionary.add_variable(
-        kh.Variable(json_data={"name": "id_product", "type": "Categorical"})
-    )
+    second_dictionary.add_variable_from_spec(name="Id", type="Categorical")
+    second_dictionary.add_variable_from_spec(name="id_product", type="Categorical")
+
     # Create a third dictionary
     third_dictionary = kh.Dictionary(json_data={"name": "Address", "key": ["Id"]})
-    third_dictionary.add_variable(
-        kh.Variable(json_data={"name": "StreetNumber", "type": "Numerical"})
-    )
-    third_dictionary.add_variable(
-        kh.Variable(json_data={"name": "StreetName", "type": "Categorical"})
-    )
-    third_dictionary.add_variable(
-        kh.Variable(json_data={"name": "id_city", "type": "Categorical"})
-    )
+    third_dictionary.add_variable_from_spec(name="StreetNumber", type="Numerical")
+    third_dictionary.add_variable_from_spec(name="StreetName", type="Categorical")
+    third_dictionary.add_variable_from_spec(name="id_city", type="Categorical")
 
     # Add the variables used in a multi-table context in the first dictionary.
     # They link the root dictionary to the additional ones
-    root_dictionary.add_variable(
-        kh.Variable(json_data={"name": "Services", "type": "Table(Service)"})
+    root_dictionary.add_variable_from_spec(
+        name="Services", type="Table", object_type="Service"
     )
-    root_dictionary.add_variable(
-        kh.Variable(json_data={"name": "Address", "type": "Entity(Address)"})
+    root_dictionary.add_variable_from_spec(
+        name="Address", type="Entity", object_type="Address"
     )
 
     # Create a DictionaryDomain (set of dictionaries)
diff --git a/khiops/core/dictionary.py b/khiops/core/dictionary.py
@@ -80,6 +80,55 @@ def _quote_value(value):
     return quoted_value
 
 
+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) is not None
+
+
+def _is_valid_type(type_str):
+    """Checks whether the type is known"""
+    return type_str in [
+        "Categorical",
+        "Numerical",
+        "Time",
+        "Date",
+        "Timestamp",
+        "TimestampTZ",
+        "Text",
+        "TextList",
+        "Structure",
+        "Entity",
+        "Table",
+    ]
+
+
+def _is_native_type(type_str):
+    """Checks whether the type is native (not internal or relational)"""
+    return type_str in [
+        "Categorical",
+        "Numerical",
+        "Time",
+        "Date",
+        "Timestamp",
+        "TimestampTZ",
+        "Text",
+    ]
+
+
+def _is_object_type(type_str):
+    """Checks whether the type is an object one (relational)"""
+    return type_str in ["Entity", "Table"]
+
+
 class DictionaryDomain(KhiopsJSONObject):
     """Main class containing the information of a Khiops dictionary file
 
@@ -768,6 +817,113 @@ def add_variable(self, variable):
         self.variables.append(variable)
         self._variables_by_name[variable.name] = variable
 
+    def add_variable_from_spec(
+        self,
+        name,
+        type,
+        label=None,
+        used=None,
+        object_type=None,
+        structure_type=None,
+        meta_data=None,
+    ):
+        """Adds a variable to this dictionary using a complete specification
+
+        Parameters
+        ----------
+        name : str
+            Variable name
+        type : str
+            Variable type
+                See `Variable`
+        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
+            with the following keys:
+            - keys : List[str], optional
+                list of meta-data keys ([] by default)
+            - values: List[str|bool|float|int], optional
+                list of meta-data values ([] by default)
+
+        Raises
+        ------
+        `ValueError`
+            - If the variable name is empty or does not comply
+              with the formatting constraints.
+            - 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 _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 not _is_valid_type(type):
+            raise ValueError(f"Invalid type '{type}'")
+        if _is_native_type(type):
+            if object_type or structure_type:
+                raise ValueError(
+                    f"Native type '{type}' "
+                    "cannot have 'object_type' or 'structure_type'"
+                )
+        if _is_object_type(type) and object_type is None:
+            raise ValueError(f"'object_type' must be provided for type '{type}'")
+        variable = Variable()
+        variable.name = name
+        variable.type = type
+        if used is not None:
+            if not isinstance(used, bool):
+                raise ValueError("'used' must be a boolean")
+            else:
+                variable.used = used
+        if meta_data is not None:
+            if not isinstance(meta_data, dict):
+                raise ValueError("'meta_data' must be a dict")
+            if "keys" not in meta_data or "values" not in meta_data:
+                raise ValueError(
+                    "'meta_data' does not contain "
+                    "the mandatory keys 'keys' and 'values'"
+                )
+            if not isinstance(meta_data["keys"], list):
+                raise ValueError("'meta_data' keys must be a list")
+            if not isinstance(meta_data["values"], list):
+                raise ValueError("'meta_data' values must be a list")
+            variable.meta_data = MetaData(meta_data)
+        if label is not None:
+            if not isinstance(label, str):
+                raise ValueError("'label' must be a str")
+            else:
+                variable.label = label
+        if object_type is not None:
+            if not isinstance(object_type, str):
+                raise ValueError("'object_type' must be a str")
+            else:
+                variable.object_type = object_type
+        if structure_type is not None:
+            if not isinstance(structure_type, str):
+                raise ValueError("'structure_type' must be a str")
+            else:
+                variable.structure_type = structure_type
+        self.variables.append(variable)
+        self._variables_by_name[variable.name] = variable
+
     def remove_variable(self, variable_name):
         """Removes the specified variable from this dictionary
 
@@ -1007,6 +1163,43 @@ class Variable:
         - `samples.create_dictionary_domain()`
     """
 
+    # Variable 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,7 +1248,7 @@ def __init__(self, json_data=None):
         self.type = json_data.get("type")
 
         # Initialize complement of the type
-        if self.type in ("Entity", "Table"):
+        if _is_object_type(self.type):
             self.object_type = json_data.get("objectType")
         elif self.type == "Structure":
             self.structure_type = json_data.get("structureType")
@@ -1069,7 +1262,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):
@@ -1169,7 +1362,7 @@ def full_type(self):
             basic.
         """
         full_type = self.type
-        if self.type in ("Entity", "Table"):
+        if _is_object_type(self.type):
             full_type += f"({self.object_type})"
         elif self.type == "Structure":
             full_type += f"({self.structure_type})"
diff --git a/khiops/samples/samples.ipynb b/khiops/samples/samples.ipynb
@@ -91,40 +91,28 @@
     "    {\"name\": \"ts\", \"type\": \"TimestampTZ\"},\n",
     "]\n",
     "for var_spec in simple_variables:\n",
-    "    var = kh.Variable()\n",
-    "    var.name = var_spec[\"name\"]\n",
-    "    var.type = var_spec[\"type\"]\n",
-    "    root_dictionary.add_variable(var)\n",
+    "    root_dictionary.add_variable_from_spec(name=var_spec[\"name\"], type=var_spec[\"type\"])\n",
     "\n",
     "# Create a second dictionary\n",
     "second_dictionary = kh.Dictionary(\n",
     "    json_data={\"name\": \"Service\", \"key\": [\"Id\", \"id_product\"]}\n",
     ")\n",
-    "second_dictionary.add_variable(\n",
-    "    kh.Variable(json_data={\"name\": \"Id\", \"type\": \"Categorical\"})\n",
-    ")\n",
-    "second_dictionary.add_variable(\n",
-    "    kh.Variable(json_data={\"name\": \"id_product\", \"type\": \"Categorical\"})\n",
-    ")\n",
+    "second_dictionary.add_variable_from_spec(name=\"Id\", type=\"Categorical\")\n",
+    "second_dictionary.add_variable_from_spec(name=\"id_product\", type=\"Categorical\")\n",
+    "\n",
     "# Create a third dictionary\n",
     "third_dictionary = kh.Dictionary(json_data={\"name\": \"Address\", \"key\": [\"Id\"]})\n",
-    "third_dictionary.add_variable(\n",
-    "    kh.Variable(json_data={\"name\": \"StreetNumber\", \"type\": \"Numerical\"})\n",
-    ")\n",
-    "third_dictionary.add_variable(\n",
-    "    kh.Variable(json_data={\"name\": \"StreetName\", \"type\": \"Categorical\"})\n",
-    ")\n",
-    "third_dictionary.add_variable(\n",
-    "    kh.Variable(json_data={\"name\": \"id_city\", \"type\": \"Categorical\"})\n",
-    ")\n",
+    "third_dictionary.add_variable_from_spec(name=\"StreetNumber\", type=\"Numerical\")\n",
+    "third_dictionary.add_variable_from_spec(name=\"StreetName\", type=\"Categorical\")\n",
+    "third_dictionary.add_variable_from_spec(name=\"id_city\", type=\"Categorical\")\n",
     "\n",
     "# Add the variables used in a multi-table context in the first dictionary.\n",
     "# They link the root dictionary to the additional ones\n",
-    "root_dictionary.add_variable(\n",
-    "    kh.Variable(json_data={\"name\": \"Services\", \"type\": \"Table(Service)\"})\n",
+    "root_dictionary.add_variable_from_spec(\n",
+    "    name=\"Services\", type=\"Table\", object_type=\"Service\"\n",
     ")\n",
-    "root_dictionary.add_variable(\n",
-    "    kh.Variable(json_data={\"name\": \"Address\", \"type\": \"Entity(Address)\"})\n",
+    "root_dictionary.add_variable_from_spec(\n",
+    "    name=\"Address\", type=\"Entity\", object_type=\"Address\"\n",
     ")\n",
     "\n",
     "# Create a DictionaryDomain (set of dictionaries)\n",
diff --git a/khiops/samples/samples.py b/khiops/samples/samples.py
diff --git a/tests/test_core.py b/tests/test_core.py
