Make upper_scope a global and composable function

Thus, `upper_scope` can be composed with itself an arbitrary number of
times, thus allowing to support multi-level upper scopes in snowflake
multi-table topologies.

Author: popescu-v

khiops/core/dictionary.py

@@ -83,8 +83,8 @@ def _quote_value(value):
 
 class _ScopedOperand:
     def __init__(self, operand):
-        assert type(operand) in (Variable, Rule), type_error_message(
-            "operand", operand, Variable, Rule
+        assert type(operand) in (Variable, Rule, _ScopedOperand), type_error_message(
+            "operand", operand, Variable, Rule, "upper-scoped Variable or Rule"
         )
         self.operand = operand
 
@@ -105,6 +105,35 @@ def __repr__(self):
         return str(stream.getvalue(), encoding="utf8", errors="replace")
 
 
+def upper_scope(operand):
+    """Adds the '.' upper-scope prefix to the serialization of the operand.
+
+    Parameters
+    ----------
+    operand : `Variable`, `Rule`, upper-scoped `Variable` or upper-scoped `Rule`
+        Operand that is upper-scoped.
+
+    Raises
+    ------
+    `TypeError`
+        If the type of ``operand`` is not `Variable`, `Rule`, upper-scoped `Variable`
+        or upper-scoped `Rule`.
+
+    Returns
+    -------
+    upper-scoped operand
+        Upper-scoped operand, serialized as prefixed with ``.``.
+
+    """
+    if not isinstance(operand, (Variable, Rule, _ScopedOperand)):
+        raise TypeError(
+            type_error_message(
+                "operand", operand, Variable, Rule, "upper-scoped Variable or Rule"
+            )
+        )
+    return _ScopedOperand(operand)
+
+
 class DictionaryDomain(KhiopsJSONObject):
     """Main class containing the information of a Khiops dictionary file
 
@@ -1198,10 +1227,6 @@ def __str__(self):
         self.write(writer)
         return str(stream.getvalue(), encoding="utf8", errors="replace")
 
-    def upper_scope(self):
-        """Adds the '.' upper-scope prefix to the serialization of the operand."""
-        return _ScopedOperand(self)
-
     def copy(self):
         """Copies this variable instance
 
@@ -1659,10 +1684,6 @@ def __repr__(self):
         self.write(writer)
         return str(stream.getvalue(), encoding="utf8", errors="replace")
 
-    def upper_scope(self):
-        """Adds the '.' upper-scope prefix to the serialization of the operand."""
-        return _ScopedOperand(self)
-
     def copy(self):
         """Copies this rule instance
 
@@ -1682,7 +1703,8 @@ def write(self, writer):
             Output writer.
 
         .. note::
-            If ``self.is_reference`` is set, then ``self.name`` is not included in the serialization.
+            If ``self.is_reference`` is set, then ``self.name`` is not included
+            in the serialization.
         """
         # Check the type of the writer
         if not isinstance(writer, KhiopsOutputWriter):

tests/test_core.py

@@ -1991,11 +1991,13 @@ def test_dictionary_rule_construction(self):
             b'SomeRule("some_operand", 2, `Some``Variable`)',
             'SomeRule("some_operand", 2, .SomeVariable)',
             b'SomeRule("some_operand", 2, .SomeVariable)',
+            'SomeRule("some_operand", 2, ..SomeVariable)',
             'SomeRule("some_operand", #Missing)',
             b'SomeRule("some_operand", #Missing)',
             'SomeRule("some_operand", 2, SomeEmbeddedRule("some_other_operand"))',
             b'SomeRule("some_operand", 2, SomeEmbeddedRule("some_other_operand"))',
             'SomeRule("some_operand", 2, .SomeEmbeddedRule("some_other_operand"))',
+            'SomeRule("some_operand", 2, ..SomeEmbeddedRule("some_other_operand"))',
             (
                 'SomeRule("some_operand", 2, SomeEmbeddedRule("some_other_operand", '
                 'SomeOtherRule("some_embedded_operand", #Missing, 3)))'
@@ -2083,19 +2085,40 @@ def test_dictionary_rule_construction(self):
                     "SomeRule",
                     "some_operand",
                     2,
-                    kh.Variable(
-                        json_data={"name": "SomeVariable", "type": "Categorical"}
-                    ).upper_scope(),
+                    kh.upper_scope(
+                        kh.Variable(
+                            json_data={"name": "SomeVariable", "type": "Categorical"}
+                        )
+                    ),
                 ),
             ],
             [
                 kh.Rule(
                     b"SomeRule",
                     b"some_operand",
                     2,
-                    kh.Variable(
-                        json_data={"name": b"SomeVariable", "type": b"Categorical"}
-                    ).upper_scope(),
+                    kh.upper_scope(
+                        kh.Variable(
+                            json_data={"name": b"SomeVariable", "type": b"Categorical"}
+                        )
+                    ),
+                ),
+            ],
+            [
+                kh.Rule(
+                    "SomeRule",
+                    "some_operand",
+                    2,
+                    kh.upper_scope(
+                        kh.upper_scope(
+                            kh.Variable(
+                                json_data={
+                                    "name": "SomeVariable",
+                                    "type": "Categorical",
+                                }
+                            )
+                        )
+                    ),
                 ),
             ],
             [
@@ -2143,7 +2166,19 @@ def test_dictionary_rule_construction(self):
                     "SomeRule",
                     "some_operand",
                     2,
-                    kh.Rule("SomeEmbeddedRule", "some_other_operand").upper_scope(),
+                    kh.upper_scope(kh.Rule("SomeEmbeddedRule", "some_other_operand")),
+                ),
+            ],
+            [
+                kh.Rule(
+                    "SomeRule",
+                    "some_operand",
+                    2,
+                    kh.upper_scope(
+                        kh.upper_scope(
+                            kh.Rule("SomeEmbeddedRule", "some_other_operand")
+                        )
+                    ),
                 ),
             ],
             [