Deprecate the Core helper build_multi_table_dictionary_domain (#395)

Keep the same functionality as a "private" function.
Deprecate the usage of the public function. It could be dropped in V11.

Also add documentation note to the public function, as to its intent and
purpose.

closes #386

Author: popescu-v

CHANGELOG.md

@@ -14,6 +14,10 @@
 ### Fixed
 - (`sklearn`) Crash when there were no informative trees in predictors.
 
+### Deprecated
+- `core`:
+  - The `build_multi_table_dictionary_domain` helper function.
+
 ## 10.3.0.0 - 2025-02-10
 
 ### Fixed

khiops/core/api.py

@@ -21,7 +21,7 @@
 import khiops.core.internals.filesystems as fs
 from khiops.core.dictionary import DictionaryDomain, read_dictionary_file
 from khiops.core.exceptions import KhiopsRuntimeError
-from khiops.core.helpers import build_multi_table_dictionary_domain
+from khiops.core.helpers import _build_multi_table_dictionary_domain
 from khiops.core.internals.common import (
     CommandLineOptions,
     SystemSettings,
@@ -1943,8 +1943,7 @@ def build_multi_table_dictionary(
 
     .. warning::
         This method is *deprecated* since Khiops 10.1.3 and will be removed in Khiops
-        11. Use the `.build_multi_table_dictionary_domain` helper function to
-        the same effect.
+        11.
 
     Parameters
     ----------
@@ -1979,7 +1978,7 @@ def build_multi_table_dictionary(
     # Generate multi-table domain by using the eponymous helper function
     # Honor exception API:
     try:
-        multi_table_domain = build_multi_table_dictionary_domain(
+        multi_table_domain = _build_multi_table_dictionary_domain(
             dictionary_domain, root_dictionary_name, secondary_table_variable_name
         )
     except TypeError as error:

khiops/core/helpers.py

@@ -8,6 +8,7 @@
 import os
 import platform
 import subprocess
+import warnings
 
 import khiops.core.internals.filesystems as fs
 from khiops.core import api
@@ -19,6 +20,7 @@
 )
 from khiops.core.internals.common import (
     create_unambiguous_khiops_path,
+    deprecation_message,
     is_list_like,
     type_error_message,
 )
@@ -29,6 +31,22 @@ def build_multi_table_dictionary_domain(
 ):
     """Builds a multi-table dictionary domain from a dictionary with a key
 
+    .. note::
+
+        This is a special-purpose function whose goal is to assist in preparing the
+        coclustering deployment.
+
+        This function builds a new root dictionary and adds it to an existing dictionary
+        domain.
+        The new root dictionary only contains one field, which references a preexisting
+        dictionary from the input dictionary domain as a new (secondary) Table variable.
+        The preexisting dictionary must have a key set on it, as this is the join key
+        with the new root table.
+
+    .. warning::
+        This method is *deprecated* since Khiops 10.3.1.0 and will be removed in Khiops
+        11.
+
     Parameters
     ----------
     dictionary_domain : `.DictionaryDomain`
@@ -38,6 +56,11 @@ def build_multi_table_dictionary_domain(
     secondary_table_variable_name : str
         Name, in the root dictionary, for the "table" variable of the secondary table.
 
+    Returns
+    -------
+    `.DictionaryDomain`
+        The new dictionary domain
+
     Raises
     ------
     `TypeError`
@@ -47,6 +70,16 @@ def build_multi_table_dictionary_domain(
         - the dictionary domain doesn't contain at least a dictionary
         - the dictionary domain's root dictionary doesn't have a key set
     """
+    # Warn the user that this helper function is deprecated and will be removed
+    warnings.warn(deprecation_message("build_multi_table_dictionary_domain", "11.0.0"))
+    return _build_multi_table_dictionary_domain(
+        dictionary_domain, root_dictionary_name, secondary_table_variable_name
+    )
+
+
+def _build_multi_table_dictionary_domain(
+    dictionary_domain, root_dictionary_name, secondary_table_variable_name
+):
     # Check that `dictionary_domain` is a `DictionaryDomain`
     if not isinstance(dictionary_domain, DictionaryDomain):
         raise TypeError(
@@ -266,7 +299,7 @@ def deploy_coclustering(
     # Create a root dictionary containing the keys
     root_dictionary_name = "CC_" + dictionary_name
     table_variable_name = "Table_" + dictionary_name
-    domain = build_multi_table_dictionary_domain(
+    domain = _build_multi_table_dictionary_domain(
         tmp_domain, root_dictionary_name, table_variable_name
     )
 

khiops/sklearn/estimators.py

@@ -44,7 +44,7 @@
 import khiops.core as kh
 import khiops.core.internals.filesystems as fs
 from khiops.core.dictionary import DictionaryDomain
-from khiops.core.helpers import build_multi_table_dictionary_domain
+from khiops.core.helpers import _build_multi_table_dictionary_domain
 from khiops.core.internals.common import (
     deprecation_message,
     is_dict_like,
@@ -1037,7 +1037,7 @@ def _create_coclustering_model_domain(
         assert isinstance(output_dir, str)
 
         # Build multi-table dictionary domain out of the input domain
-        mt_domain = build_multi_table_dictionary_domain(
+        mt_domain = _build_multi_table_dictionary_domain(
             domain,
             self.model_main_dictionary_name_,
             self.model_secondary_table_variable_name,

tests/test_core.py

@@ -2305,7 +2305,7 @@ def test_build_multi_table_dictionary_behavior(self):
         parameter_trace = KhiopsTestHelper.create_parameter_trace()
 
         in_args = KhiopsCoreVariousTests._build_multi_table_dictionary_args()
-        helper_name = "build_multi_table_dictionary_domain"
+        helper_name = "_build_multi_table_dictionary_domain"
         KhiopsTestHelper.wrap_with_parameter_trace(
             "khiops.core.api", helper_name, parameter_trace
         )

tests/test_helper_functions.py

@@ -11,6 +11,7 @@
 import platform
 import stat
 import unittest
+import warnings
 
 import pandas as pd
 
@@ -22,10 +23,9 @@
 class KhiopsHelperFunctions(unittest.TestCase):
     """Tests for checking the behaviour of the helper functions"""
 
-    def test_build_multi_table_dictionary_domain(self):
-        """Test that the multi-table dictionary domain built is as expected"""
-        # Build monotable_domain, with one dictionary, holding three variables
-        monotable_domain_specification = {
+    @staticmethod
+    def _build_monotable_domain_specification():
+        return {
             "tool": "Khiops Dictionary",
             "version": "10.0",
             "khiops_encoding": "ascii",
@@ -42,6 +42,42 @@ def test_build_multi_table_dictionary_domain(self):
                 }
             ],
         }
+
+    def test_build_multi_table_dictionary_domain_deprecation(self):
+        """Test that `core.helpers.build_multi_table_dictionary_domain` raises
+        deprecation warning
+        """
+        # Build monotable_domain, with one dictionary, holding three variables
+        monotable_domain_specification = (
+            KhiopsHelperFunctions._build_monotable_domain_specification()
+        )
+        monotable_domain = DictionaryDomain(monotable_domain_specification)
+
+        # Build multi-table dictionary domain from the montable dictionary domain
+        with warnings.catch_warnings(record=True) as warning_list:
+            build_multi_table_dictionary_domain(
+                monotable_domain,
+                "A_Prefix_SpliceJunctionDNA",
+                "A_Name_SpliceJunctionDNA",
+            )
+
+        self.assertEqual(len(warning_list), 1)
+        warning = warning_list[0]
+        self.assertTrue(issubclass(warning.category, UserWarning))
+        warning_message = warning.message
+        self.assertEqual(len(warning_message.args), 1)
+        message = warning_message.args[0]
+        self.assertTrue(
+            "'build_multi_table_dictionary_domain'" in message
+            and "deprecated" in message
+        )
+
+    def test_build_multi_table_dictionary_domain(self):
+        """Test that the multi-table dictionary domain built is as expected"""
+        # Build monotable_domain, with one dictionary, holding three variables
+        monotable_domain_specification = (
+            KhiopsHelperFunctions._build_monotable_domain_specification()
+        )
         monotable_domain = DictionaryDomain(monotable_domain_specification)
 
         # Build reference multi-table domain, with two dictionaries, one root