python.GeneratorSettingsSemantics Namespace Reference

Classes
class	GeneratorSettingsKeep
class	GeneratorSettingsRecord
class	GeneratorSettingsPrecedence
class	GeneratorSettingsLayer
class	GeneratorSettingsValue
class	GeneratorSettingsSemantics

Functions
	_ordered_layers (layers)
	_build_records (layers, separators)
	_parse_assignment (setting_text, separators)
	_normalize_text (value)
	_deduplicate_records (records, keep)
	_build_report (records, kept_records, removed_records)
	_build_conflict_details (records, kept_records)
	_find_conflicts (records)
	_log_report (context, report)

Variables
	genSettingsLog = logging.getLogger("GeneratorSettingsSemantics")

Function Documentation

_build_conflict_details()

python.GeneratorSettingsSemantics._build_conflict_details ( records, kept_records )

protected

Build one reporting entry per conflicting parsed key.

The source and value order follows the original record order, and the kept
value is marked explicitly in the value list.

Definition at line 439 of file GeneratorSettingsSemantics.py.

def _build_conflict_details(records, kept_records):
    """
    Build one reporting entry per conflicting parsed key.
 
    The source and value order follows the original record order, and the kept
    value is marked explicitly in the value list.
    """
    kept_value_by_key = {}
    for record in kept_records:
        if record["record_kind"] != GeneratorSettingsRecord.PARSED_COMMAND:
            continue
        kept_value_by_key[record["normalized_key"]] = record["normalized_value"]
 
    values_by_key = {}
    for record in records:
        if record["record_kind"] != GeneratorSettingsRecord.PARSED_COMMAND:
            continue
 
        key = record["normalized_key"]
        source_name = record["source_name"]
        value = record["normalized_value"]
 
        key_entry = values_by_key.setdefault(
            key,
            {
                "sources": [],
                "source_set": set(),
                "values": [],
                "value_set": set(),
                "source_to_values": {},
            },
        )
        if source_name not in key_entry["source_set"]:
            key_entry["source_set"].add(source_name)
            key_entry["sources"].append(source_name)
        if value not in key_entry["value_set"]:
            key_entry["value_set"].add(value)
            key_entry["values"].append(value)
        key_entry["source_to_values"].setdefault(source_name, set()).add(value)
 
    conflict_details = []
    for key, key_entry in values_by_key.items():
        merged_values = set()
        for values in key_entry["source_to_values"].values():
            merged_values.update(values)
        if len(merged_values) <= 1 or len(key_entry["source_to_values"]) <= 1:
            continue
 
        kept_value = kept_value_by_key.get(key)
        marked_values = []
        for value in key_entry["values"]:
            if value == kept_value:
                marked_values.append(f"{value} (kept)")
                continue
            marked_values.append(value)
 
        conflict_details.append({
            "key": key,
            "sources": key_entry["sources"],
            "values": marked_values,
        })
    return conflict_details
 
 

_build_records()

python.GeneratorSettingsSemantics._build_records ( layers, separators )

protected

Convert raw command strings into normalized records.
Parsed commands are deduplicated by key. Commands that cannot be parsed as
key/value records are deduplicated by their normalized full text.

Definition at line 287 of file GeneratorSettingsSemantics.py.

def _build_records(layers, separators):
    """
    Convert raw command strings into normalized records.
    Parsed commands are deduplicated by key. Commands that cannot be parsed as
    key/value records are deduplicated by their normalized full text.
    """
    records = []
    for layer in layers:
        for raw_setting in layer.values:
            key_text, value_text = _parse_assignment(raw_setting, separators)
            if key_text is None:
                records.append({
                    "source_name": layer.source,
                    "record_kind": GeneratorSettingsRecord.UNPARSED_COMMAND,
                    "normalized_key": None,
                    "normalized_value": None,
                    "original_setting": raw_setting,
                    "dedup_signature": (
                        GeneratorSettingsRecord.UNPARSED_COMMAND,
                        _normalize_text(raw_setting),
                    ),
                })
                continue
 
            normalized_key = _normalize_text(key_text)
            records.append({
                "source_name": layer.source,
                "record_kind": GeneratorSettingsRecord.PARSED_COMMAND,
                "normalized_key": normalized_key,
                "normalized_value": _normalize_text(value_text),
                "original_setting": raw_setting,
                "dedup_signature": (
                    GeneratorSettingsRecord.PARSED_COMMAND,
                    normalized_key,
                ),
            })
    return records
 
 

_build_report()

python.GeneratorSettingsSemantics._build_report ( records, kept_records, removed_records )

protected

Collect duplicate and conflict information for logging/tests.

Definition at line 368 of file GeneratorSettingsSemantics.py.

def _build_report(records, kept_records, removed_records):
    """Collect duplicate and conflict information for logging/tests."""
    removed_duplicates = [
        {
            "source": record["source_name"],
            "duplicate_of_source": record.get("duplicate_of_source_name"),
            "setting": record["original_setting"],
            "kept_setting": record.get("kept_original_setting"),
            "normalized_value": record["normalized_value"],
            "kept_normalized_value": record.get("kept_normalized_value"),
        }
        for record in removed_records
    ]
 
    removed_identical = [
        {
            "source": record["source"],
            "duplicate_of_source": record.get("duplicate_of_source"),
            "setting": record["setting"],
            "kept_setting": record.get("kept_setting"),
        }
        for record in removed_duplicates
        if record["normalized_value"] == record.get("kept_normalized_value")
    ]
    duplicates_in_source = {}
    duplicates_across_sources = {}
 
    for record in removed_identical:
        source_name = record.get("source", "<unknown>")
        duplicate_of_source = record.get("duplicate_of_source", "<unknown>")
        if duplicate_of_source == source_name:
            duplicates_in_source[source_name] = (
                duplicates_in_source.get(source_name, 0) + 1
            )
            continue
 
        source_pair = (source_name, duplicate_of_source)
        duplicates_across_sources[source_pair] = (
            duplicates_across_sources.get(source_pair, 0) + 1
        )
 
    conflict_details = _build_conflict_details(records, kept_records)
 
    return {
        "removed_duplicates": removed_duplicates,
        "removed_identical": removed_identical,
        "conflicting_reassignments": [
            record
            for record in removed_duplicates
            if record["normalized_value"] != record.get("kept_normalized_value")
        ],
        "removed_overridden": [
            record
            for record in removed_duplicates
            if record["normalized_value"] != record.get("kept_normalized_value")
        ],
        "conflict_details": conflict_details,
        "conflicts": _find_conflicts(records),
        "duplicates_in_source": duplicates_in_source,
        "duplicates_across_sources": [
            {
                "source": source_name,
                "duplicate_of_source": duplicate_of_source,
                "count": duplicate_count,
            }
            for (source_name, duplicate_of_source), duplicate_count
            in sorted(duplicates_across_sources.items())
        ],
    }
 
 

_deduplicate_records()

python.GeneratorSettingsSemantics._deduplicate_records ( records, keep )

protected

Keep the first or last record for each normalized setting key.

Definition at line 340 of file GeneratorSettingsSemantics.py.

def _deduplicate_records(records, keep):
    """Keep the first or last record for each normalized setting key."""
    keep_last = keep == GeneratorSettingsKeep.LAST
    records_to_scan = reversed(records) if keep_last else records
 
    kept_records = []
    removed_records = []
    first_seen_by_signature = {}
    for record in records_to_scan:
        signature = record["dedup_signature"]
        if signature in first_seen_by_signature:
            kept_record = first_seen_by_signature[signature]
            removed_record = dict(record)
            removed_record["duplicate_of_source_name"] = kept_record["source_name"]
            removed_record["kept_normalized_value"] = kept_record["normalized_value"]
            removed_record["kept_original_setting"] = kept_record["original_setting"]
            removed_records.append(removed_record)
            continue
 
        first_seen_by_signature[signature] = record
        kept_records.append(record)
 
    if keep_last:
        kept_records.reverse()
        removed_records.reverse()
    return kept_records, removed_records
 
 

_find_conflicts()

python.GeneratorSettingsSemantics._find_conflicts ( records )

protected

Find keys assigned to multiple values within or across sources.

Definition at line 503 of file GeneratorSettingsSemantics.py.

def _find_conflicts(records):
    """Find keys assigned to multiple values within or across sources."""
    values_by_key_and_source = {}
    for record in records:
        if record["record_kind"] != GeneratorSettingsRecord.PARSED_COMMAND:
            continue
 
        key = record["normalized_key"]
        source_name = record["source_name"]
        value = record["normalized_value"]
        values_by_key_and_source.setdefault(key, {}).setdefault(
            source_name,
            set(),
        ).add(value)
 
    conflicts = []
    for key, source_to_values in values_by_key_and_source.items():
        for source_name, values in source_to_values.items():
            if len(values) > 1:
                conflicts.append({
                    "type": "intra_source_conflict",
                    "key": key,
                    "source": source_name,
                    "values": sorted(values),
                })
 
        merged_values = set()
        for values in source_to_values.values():
            merged_values.update(values)
        if len(merged_values) > 1 and len(source_to_values) > 1:
            conflicts.append({
                "type": "inter_source_conflict",
                "key": key,
                "sources": sorted(source_to_values.keys()),
                "values": sorted(merged_values),
            })
    return conflicts
 
 

_log_report()

python.GeneratorSettingsSemantics._log_report ( context, report )

protected

Print warnings from the structured report.

Definition at line 542 of file GeneratorSettingsSemantics.py.

def _log_report(context, report):
    """Print warnings from the structured report."""
    issue_prefix = "Potential issue with generator settings"
 
    duplicates = report.get("removed_identical", [])
    conflict_details = report.get("conflict_details", [])
    if not duplicates and not conflict_details:
        return
 
    genSettingsLog.warning(
        f"{issue_prefix} [{context}]: found {len(duplicates)} duplicate "
        f"setting(s) across sources and {len(conflict_details)} conflicting "
        f"setting key(s)"
    )
 
    for entry in sorted(
        duplicates,
        key=lambda record: (
            record.get("source", ""),
            record.get("duplicate_of_source", ""),
            record.get("setting", ""),
        ),
    ):
        source_name = entry.get("source", "<unknown>")
        duplicate_of_source = entry.get("duplicate_of_source", "<unknown>")
        setting = entry.get("setting", "<unknown>")
        source_list = [source_name]
        if duplicate_of_source != source_name:
            source_list.append(duplicate_of_source)
        genSettingsLog.warning(
            f"{issue_prefix} [{context}]: duplicate setting from sources "
            f"[{', '.join(source_list)}]: {setting}"
        )
 
    for entry in conflict_details:
        key = entry.get("key", "<unknown>")
        sources = ", ".join(entry.get("sources", []))
        values = ", ".join(entry.get("values", []))
        genSettingsLog.warning(
            f"{issue_prefix} [{context}]: conflicting setting '{key}' across "
            f"sources [{sources}] -> [{values}]"
        )

_normalize_text()

python.GeneratorSettingsSemantics._normalize_text ( value )

protected

Definition at line 335 of file GeneratorSettingsSemantics.py.

def _normalize_text(value):
    text = str(value).strip()
    return " ".join(text.split())
 
 

_ordered_layers()

python.GeneratorSettingsSemantics._ordered_layers ( layers )

protected

Apply precedence before deduplication.

Definition at line 275 of file GeneratorSettingsSemantics.py.

def _ordered_layers(layers):
    """Apply precedence before deduplication."""
    return sorted(
        layers,
        key=lambda layer: (
            int(layer.precedence),
            layer.source,
            repr(layer.values),
        ),
    )
 
 

_parse_assignment()

python.GeneratorSettingsSemantics._parse_assignment ( setting_text, separators )

protected

Definition at line 326 of file GeneratorSettingsSemantics.py.

def _parse_assignment(setting_text, separators):
    text = str(setting_text).strip()
    for separator in separators:
        if separator in text:
            key_text, value_text = text.split(separator, 1)
            return key_text.strip(), value_text.strip()
    return None, None
 
 

Variable Documentation

genSettingsLog

python.GeneratorSettingsSemantics.genSettingsLog = logging.getLogger("GeneratorSettingsSemantics")

Definition at line 9 of file GeneratorSettingsSemantics.py.