ENH(scanner): allow recursive references to records on the same level in the cfood

src/caoscrawler/converters/converters.py

@@ -249,11 +249,34 @@ out: tuple
     return (propvalue, propunit, collection_mode)
 
 
-def create_records(values: GeneralStore, records: RecordStore, def_records: dict):
-    # list of keys to identify, which variables have been set by which paths:
-    # the items are tuples:
-    # 0: record name
-    # 1: property name
+def create_records(values: GeneralStore,
+                   records: RecordStore,
+                   def_records: dict) -> list[tuple[str, str]]:
+    """
+    Create records in GeneralStore `values` and RecordStore `records` as given
+    by the definition in `def_records`.
+
+    This function will be called during scanning using the cfood definition.
+    It also should be used by CustomConverters to set records as automatic substitution
+    and other crawler features are applied automatically.
+
+    Arguments:
+    ----------
+    values: GeneralStore
+      This GeneralStore will be used to access variables that are needed during variable substitution
+      in setting the properties of records and files.
+      Furthermore, the records that are generated in this function will be stored in this GeneralStore
+      **additionally to** storing them in the RecordStore given as the second argument to this function.
+
+    records: RecordStore
+      The RecordStore where the generated records will be stored.
+
+    Returns:
+    --------
+    A list of tuples containing the record names (1st element of tuple) and respective property names
+    as 2nd element of the tuples. This list will be used by the scanner for creating the debug tree.
+
+    """
     keys_modified = []
 
     for name, record in def_records.items():
@@ -286,11 +309,22 @@ def create_records(values: GeneralStore, records: RecordStore, def_records: dict
             if (role == "Record" and "parents" not in record):
                 c_record.add_parent(name)
 
-        c_record = records[name]
-
         if isinstance(record, str):
             raise RuntimeError(
                 "dict expected, but found str: {}".format(record))
+
+    # We do a second run over the def_records, here. Having finished the first run
+    # for creating the records (in the variable and records stores) makes sure that
+    # records, that are defined on this level can already be accessed during variable substitution
+    # in the properties that will be set in the next block.
+    for name, record in def_records.items():
+        # See above:
+        if record is None:
+            record = {}
+
+        c_record = records[name]
+
+        # Set the properties:
         for key, value in record.items():
             if key == "parents" or key == "role":
                 continue
@@ -320,7 +354,8 @@ def create_records(values: GeneralStore, records: RecordStore, def_records: dict
                         c_record.add_property(name=key, value=propvalue, unit=propunit)
                 else:
                     if collection_mode == "list":
-                        if propunit and c_record.get_property(key).unit and propunit != c_record.get_property(key).unit:
+                        if (propunit and c_record.get_property(key).unit
+                                and propunit != c_record.get_property(key).unit):
                             raise RuntimeError(
                                 f"Property '{key}' has contradictory units: "
                                 f"{propunit} and {c_record.get_property(key).unit}"