Add comments and internal comments

CHANGELOG.md

@@ -6,6 +6,12 @@
   - Example: 10.2.1.4 is the 5th version that supports khiops 10.2.1.
 - Internals: Changes in *Internals* sections are unlikely to be of interest for data scientists.
 
+## Unreleased -
+
+### Added
+- (`core`) Dictionary API support for dictionary, variable and variable block
+  comments, and dictionary and variable block internal comments.
+
 ## 11.0.0.0-b.0 - 2025-07-10
 
 ### Added

khiops/core/dictionary.py

@@ -548,18 +548,22 @@ class Dictionary:
     ----------
     name : str
         Dictionary name.
-    label : str
-        Dictionary label/comment.
     root : bool
         True if the dictionary is the root of an dictionary hierarchy.
     key : list of str
         Names of the key variables.
-    meta_data : `MetaData`
-        MetaData object of the dictionary.
     variables : list of `Variable`
         The dictionary variables.
     variable_blocks : list of `VariableBlock`
         The dictionary variable blocks.
+    label : str
+        Dictionary label.
+    comments : list of str
+        List of dictionary comments.
+    internal_comments : list of str
+        List of internal dictionary comments.
+    meta_data : `MetaData`
+        MetaData object of the dictionary.
     """
 
     def __init__(self, json_data=None):
@@ -579,6 +583,8 @@ def __init__(self, json_data=None):
         # Initialize main attributes
         self.name = json_data.get("name", "")
         self.label = json_data.get("label", "")
+        self.comments = json_data.get("comments", [])
+        self.internal_comments = json_data.get("internalComments", [])
         self.root = json_data.get("root", False)
 
         # Initialize names of key variable
@@ -634,6 +640,8 @@ def copy(self):
         # Copy dictionary main features
         dictionary_copy.name = self.name
         dictionary_copy.label = self.label
+        dictionary_copy.comments = self.comments.copy()
+        dictionary_copy.internal_comments = self.internal_comments.copy()
         dictionary_copy.root = self.root
         dictionary_copy.key = self.key.copy()
         dictionary_copy.meta_data = self.meta_data.copy()
@@ -653,6 +661,10 @@ def copy(self):
                 variable_block_copy = VariableBlock()
                 variable_block_copy.name = variable.variable_block.name
                 variable_block_copy.label = variable.variable_block.label
+                variable_block_copy.comments = variable.variable_block.comments.copy()
+                variable_block_copy.internal_comments = (
+                    variable.variable_block.internal_comments.copy()
+                )
                 variable_block_copy.rule = variable.variable_block.rule
                 variable_block_copy.meta_data = variable_block.meta_data.copy()
 
@@ -900,6 +912,10 @@ def write(self, writer):
         if self.label:
             writer.write("// ")
             writer.writeln(self.label)
+        if self.comments:
+            for comment in self.comments:
+                writer.write("// ")
+                writer.writeln(comment)
         if self.root:
             writer.write("Root\t")
         writer.write("Dictionary\t")
@@ -929,6 +945,11 @@ def write(self, writer):
             else:
                 variable.variable_block.write(writer)
                 i += len(variable.variable_block.variables)
+
+        # Write internal comments if available
+        for comment in self.internal_comments:
+            writer.write("// ")
+            writer.writeln(comment)
         writer.writeln("};")
 
 
@@ -946,8 +967,6 @@ class Variable:
     ----------
     name : str
         Variable name.
-    label : str
-        Variable label/comment.
     used : bool
         True if the variable is used.
     type : str
@@ -958,11 +977,15 @@ class Variable:
         Type complement for the ``Structure`` type. Set to "" for other types.
     rule : str
         Derivation rule. Set to "" if there is no rule associated to this variable.
-    meta_data : `MetaData`
-        Variable metadata.
     variable_block : `VariableBlock`
         Block to which the variable belongs. Not set if the variable does not belong to
         a block.
+    label : str
+        Variable label.
+    comments : list of str
+        List of variable comments.
+    meta_data : `MetaData`
+        Variable metadata.
     """
 
     def __init__(self, json_data=None):
@@ -974,6 +997,7 @@ def __init__(self, json_data=None):
         # Main attributes
         self.name = ""
         self.label = ""
+        self.comments = []
         self.used = True
         self.type = ""
 
@@ -1007,6 +1031,7 @@ def __init__(self, json_data=None):
         # Initialize main attributes
         self.name = json_data.get("name")
         self.label = json_data.get("label", "")
+        self.comments = json_data.get("comments", [])
         self.used = json_data.get("used", True)
         self.type = json_data.get("type")
 
@@ -1045,6 +1070,7 @@ def copy(self):
         variable = Variable()
         variable.name = self.name
         variable.label = self.label
+        variable.comments = self.comments.copy()
         variable.used = self.used
         variable.type = self.type
         variable.object_type = self.object_type
@@ -1142,6 +1168,11 @@ def write(self, writer):
         if not isinstance(writer, KhiopsOutputWriter):
             raise TypeError(type_error_message("writer", writer, KhiopsOutputWriter))
 
+        # Write comments if available
+        for comment in self.comments:
+            writer.write("\t// ")
+            writer.writeln(comment)
+
         # Write "Unused" flag if variable not used
         if not self.used:
             writer.write("Unused")
@@ -1167,7 +1198,7 @@ def write(self, writer):
             self.meta_data.write(writer)
         writer.write("\t")
 
-        # Write label/commentary if available
+        # Write label if available
         if self.label:
             writer.write("// ")
             writer.write(self.label)
@@ -1186,16 +1217,20 @@ class VariableBlock:
 
     Attributes
     ----------
-    name :
+    name : str
         Block name.
-    label :
-        Block label/commentary.
     rule :
         Block derivation rule.
-    meta_data :
-        Metadata object of the block.
     variables :
         List of the Variable objects of the block.
+    label : str
+        Block label.
+    comments : list of str
+        List of block comments.
+    internal_comments : list of str
+        List of internal block comments.
+    meta_data :
+        Metadata object of the block.
     """
 
     def __init__(self, json_data=None):
@@ -1215,6 +1250,8 @@ def __init__(self, json_data=None):
         # Initialize main attributes
         self.name = json_data.get("blockName", "")
         self.label = json_data.get("label", "")
+        self.comments = json_data.get("comments", [])
+        self.internal_comments = json_data.get("internalComments", [])
 
         # Initialize derivation rule
         self.rule = json_data.get("rule", "")
@@ -1305,10 +1342,21 @@ def write(self, writer):
         # Check file object type
         if not isinstance(writer, KhiopsOutputWriter):
             raise TypeError(type_error_message("writer", writer, KhiopsOutputWriter))
+
+        # Write comments if available
+        for comment in self.comments:
+            writer.write("\t// ")
+            writer.writeln(comment)
+
         # Write variables
         writer.writeln("\t{")
         for variable in self.variables:
             variable.write(writer)
+
+        # Write internal comments if available
+        for comment in self.internal_comments:
+            writer.write("\t// ")
+            writer.writeln(comment)
         writer.write("\t}")
 
         # Write block's name
@@ -1328,7 +1376,7 @@ def write(self, writer):
             self.meta_data.write(writer)
         writer.write("\t")
 
-        # Write label/commentary if available
+        # Write label if available
         if self.label:
             writer.write("// ")
             writer.write(self.label)

tests/resources/dictionary/ref_kdic/CommentedIris.kdic

@@ -0,0 +1,25 @@
+#Khiops VERSION
+
+// Label Iris
+// Comment Iris 1
+// Comment Iris 2
+// Comment Iris 3
+// Comment Iris 4
+// Comment Iris 5
+Dictionary	Iris
+{
+	// Comment SepalLength 1
+	// Comment SepalLength 2
+	Numerical	SepalLength		;	// Label SepalLength
+	Numerical	SepalWidth		;	
+	Numerical	PetalLength		;	
+	// Comment PetalWidth
+	Numerical	PetalWidth		;	// Label PetalWidth
+	// Comment Class
+	Categorical	Class		;	
+	// Comment NoSetosa 1
+	// Comment NoSetosa 2
+Unused	Numerical	NoSetosa	 = NEQc(Class, "Iris-setosa")	;	// Label NoSetosa
+// Comment internal Iris 1
+// Comment internal Iris 2
+};

tests/resources/dictionary/ref_kdic/CommentedSparseCustomer.kdic

@@ -0,0 +1,48 @@
+#Khiops VERSION
+
+Dictionary	Address	(id_customer)
+{
+	Categorical	id_customer		;	
+	Numerical	StreetNumber		;	
+	Categorical	StreetName		;	
+	Categorical	City		;	
+};
+
+Root	Dictionary	Customer	(id_customer)
+{
+	Categorical	id_customer		;	
+	Categorical	id	 = CopyC(id_customer)	;	
+	Categorical	Name		;	
+	Entity(Address)	Address		;	
+	Table(Usage)	Usages		;	
+	// Partition comment
+	Structure(Partition)	partition1	 = Partition(ValueSetC("Mobile", "Tel", " * "))	;	// Partition label
+	// TablePartition comment 1
+	// TablePartition comment 2
+	{
+// Usages_S_M_Nb comment
+Unused	Table(Usage)	Usages_S_M_Nb		; <VarKey=1>	// Usages_S_M_Nb label
+// Usages_S_T_Nb comment
+Unused	Table(Usage)	Usages_S_T_Nb		; <VarKey=2>	// Usages_S_T_Nb label
+	}	tablePartition1	 = TablePartition(Usages, partition1, Service)	;	// TablePartition label
+	{
+	Numerical	S_M_Nb		; <VarKey=1>	
+	Numerical	S_T_Nb		; <VarKey=2>	
+	// Internal variable block comment
+	}	PartCounts	 = TablePartitionCount(tablePartition1)	;	// TablePartitionCount label
+	// S_Total comment
+	Numerical	S_Total	 = Sum(S_M_Nb, S_T_Nb)	;	
+	Table(Usage)	UsagesMobile	 = TableSelection(Usages, EQc(Service, "Mobile"))	;	
+	Table(Usage)	UsagesTel	 = TableSelection(Usages, EQc(Service, "Tel"))	;	
+	Numerical	D_M_Nb	 = TableCount(UsagesMobile)	;	
+	Numerical	D_T_Nb	 = TableCount(UsagesTel)	;	
+	Numerical	D_Total	 = Sum(D_M_Nb, D_T_Nb)	;	
+};
+
+Dictionary	Usage	(id_customer)
+{
+	Categorical	id_customer		;	
+	Categorical	Service		;	
+	Numerical	Duration		;	
+	Numerical	Price		;	
+};

tests/resources/dictionary/ref_kdic/CommentedSpliceJunction.kdic

@@ -0,0 +1,28 @@
+#Khiops VERSION
+
+// Label SpliceJunction
+// Comment SpliceJunction key before
+// Comment SpliceJunction key after
+// Comment end
+Root	Dictionary	SpliceJunction	(SampleId)
+{
+	Categorical	SampleId		;	
+	Categorical	Class		;
+	// Comment DNA
+	Table(SpliceJunctionDNA)	DNA		;	// Label DNA
+};
+
+// Label SpliceJunction
+// Comment SpliceJunction key before
+// Comment SpliceJunction key after
+// Comment SpliceJunction meta-data before
+// Comment SpliceJunction meta-data after
+// Comment end
+Dictionary	SpliceJunctionDNA	(SampleId)
+<TestComment>
+{
+	Categorical	SampleId		;	
+	Numerical	Pos		;	
+	Categorical	Char		;	
+// Categorical	LowerChar = ToLower(Char) ;
+};