site_data.py

Go to the documentation of this file.

"""site_data.py - Train sim's own tiny RailML reader.
 
Independently re-parses safeAPIRBC2oo2SA/etc/site/ab_site.railml.xml -
the same single source of truth safeAPIRBC2oo2GP/etc/scripts/
generate_ab_site_gp.py and safeAPIRBC2oo2GA/etc/scripts/generate_ab_site_ga.py
already generate GP's/GA's own C site-data tables from, and
safeAPIRBC2oo2TestEnv/src/web_runner/site_data.py already reads for the
live schematic - deliberately a FOURTH independent reader, not a call
into any of those three, matching the "each generator re-parses the file
itself, no pipeline coupling" convention those two C-side generators'
own header comments already establish (see either one's own doc for the
full rationale: no build-order coupling, and a real cross-check
opportunity instead of one silently trusting another's derived output).
 
Train only ever needs ONE thing from the file: the `nid_lrbg -> name`
mapping this sim uses purely for its own log-line decoration (see
train_sim.py's own get_balise_name()) - replaces what used to be a
hardcoded BALISE_NAMES dict that was, by actual comparison, a byte-for-
byte duplicate of this file's own <baliseGroup> data.
"""
 
import logging
import os
import xml.etree.ElementTree as ET
 
_RAILML_NS = "https://www.railml.org/schemas/3.3"
_SAPI_NS = "https://safeapirbc2oo2.example/schemas/sapi-ext/1"
_NS = {"r": _RAILML_NS, "sapi": _SAPI_NS}
 
# TrainRBCSim/src/train/ -> up 3 (train, src, TrainRBCSim) -> the SAPI
# workspace root -> safeAPIRBC2oo2SA's own sibling checkout. Same
# sibling-directory convention web_runner/server.py's own
# DEFAULT_RAILML_PATH already uses - see that file's own doc.
_WORKSPACE_ROOT = os.path.abspath(os.path.join(os.path.dirname(os.path.abspath(__file__)), "..", "..", ".."))
DEFAULT_RAILML_PATH = os.path.join(_WORKSPACE_ROOT, "safeAPIRBC2oo2SA", "etc", "site", "ab_site.railml.xml")
 
# Byte-for-byte what BALISE_NAMES (train_sim.py, before this module
# existed) hardcoded - kept ONLY as a fallback for a deployment that
# genuinely has no sibling safeAPIRBC2oo2SA checkout available (e.g. a
# Docker image built from just this project's own source tree, which
# does not copy that sibling project's own etc/site/ in today - a real,
# separate packaging gap, not something this module can fix from here).
# balise_names() logs a clear warning whenever this fallback is actually
# used, so the gap stays visible rather than silently masking itself.
_FALLBACK_BALISE_NAMES = {
    1001: "BG_W_TRK1", 1002: "BG_W_TRK2", 1003: "BG_W_TRK3", 1004: "BG_W_TRK4",
    1005: "BG_UP_1", 1006: "BG_UP_2", 1007: "BG_DOWN_1", 1008: "BG_DOWN_2",
    1009: "BG_E_TRK1", 1010: "BG_E_TRK2", 1011: "BG_E_TRK3", 1012: "BG_E_TRK4",
}
 
 
def balise_names(railml_path=None):
    """@return {nid_lrbg: name} parsed fresh from the RailML file (no
    caching - this sim's own catalog/config loading is likewise done
    once at import/startup time, matching that same "read once, live
    for the process's lifetime" posture). Falls back to a hardcoded copy
    of today's known-good data (see _FALLBACK_BALISE_NAMES's own doc) and
    logs a warning if the file can't be found/parsed, rather than raising
    - a missing balise-name mapping is a log-decoration cosmetic, never
    worth failing sim startup over."""
    path = railml_path or os.environ.get("SAPI_RAILML_PATH") or DEFAULT_RAILML_PATH
    try:
        tree = ET.parse(path)
        root = tree.getroot()
        infra = root.find("r:infrastructure", _NS)
        fi = infra.find("r:functionalInfrastructure", _NS)
        balise_groups = fi.find("r:baliseGroups", _NS)
        names = {}
        for bg in balise_groups.findall("r:baliseGroup", _NS):
            ext = bg.find("r:extensions/sapi:etcsBaliseGroup", _NS)
            nid_lrbg = int(ext.get("nidLrbg"))
            names[nid_lrbg] = bg.get("name", f"BG_{nid_lrbg}")
        if not names:
            raise ValueError("RailML file parsed but yielded zero balise groups")
        return names
    except Exception as e:
        logging.getLogger("train").warning(
            "[GENERAL] [train] [internal] [CONFIG] [could not read balise names from RailML "
            "(%s) - falling back to the hardcoded copy] [path=%s]", e, path)
        return dict(_FALLBACK_BALISE_NAMES)