sps_skel/doc/Klassenhierarchie.md

Klassenhierarchie

Bestandsaufnahme aller Python-Klassen in lib/ (Stand 2026-10-10). Kurzes Ergebnis vorweg: es gibt praktisch keine Vererbung in diesem Code (eine Ausnahme: DerivedTro(TroBase), plus die Standard-Exception RegistrationError(RuntimeError)). Alles andere sind flache, eigenständige Klassen — entweder @dataclass (veränderlicher Laufzeit-/Analysezustand) oder Pydantic BaseModel (validierte Daten, die auch als JSON ein-/ausgehen). Eine klassische "ist-ein"-Hierarchie zu suchen wäre hier der falsche Blickwinkel; interessanter ist, wer wen enthält/referenziert und in welchem Modul-Layer eine Klasse sitzt (siehe Layer-Kommentar oben in model.py).

Modul-Layer (wer darf wen importieren)

tro_catalog.py   (Typ-Ebene: was ein TRO-Typ ist)
      |
      v
   model.py      (Instanz-Ebene: ein konkreter TRO, die TRO-JSON)
      |
      v
 tro_flow.py      (Ableitung: CSV-Graph -> Analysis -> TroDocument)
      |
      +----------------------+
      v                      v
scl_context.py          tro_annotate.py   (Ausgabe: annotierte Zeichnung)
(TroDocument -> SclFile, Render-Kontext)
      |
      v
scl_skeleton.py         (Ausgabe: SclFile -> FB_Main.scl, generisch oder per Jinja-Template)

material_flow.py  dxf_registration.py   (eigenständig, ohne Abhängigkeit auf obige)
tro_overrides.py  (importiert model.Connection / model.TroCandidate)

tro_flow.py und tro_annotate.py definieren keine eigenen Klassen (nur Funktionen). scl_skeleton.py hat genau eine (SclTemplates, Jinja-Anbindung). material_flow.py hat Graph-Dataclasses — das ist CSV-Rohmodell, nicht TRO-Modell.

Vererbung (ASCII)

RuntimeError (stdlib)                    BaseModel (pydantic, stdlib: pydantic)
   |                                         |
   +-- RegistrationError                    +-- _Positioned  (model.py, Mixin)
       (dxf_registration.py)                     |
                                                  +-- TroBase
                                                  |    +-- DerivedTro
                                                  +-- TroCandidate

Das ist die gesamte class X(Y)-Liste im Projekt — alle anderen Klassen unten haben object/BaseModel direkt als einzige Basis und erscheinen hier nur noch als Gruppen nach Datei.

Klassen nach Datei, mit Komposition ("enthält")

lib/tro_catalog.py                          [Typ-Katalog, keine Instanzdaten]
├── TroItem            (Konstanten-Klasse: Bauteilarten wie SEPARATOR, SWITCH)
├── TroSymbol           (Konstanten-Klasse: Zeichensymbole wie CIRCLE, TRIANGLE)
├── TroStyle(BaseModel)   Farbe/Darstellung einer Typgruppe
└── TroDefinition(BaseModel)
    └─ style: TroStyle                      (1 TroDefinition hat genau 1 TroStyle)

lib/model.py                                 [Instanz-Ebene / TRO-JSON]
├── TroBase(BaseModel)
│   └─ definition() --> TroDefinition         (gelesen aus tro_catalog, nicht gespeichert)
│   └── DerivedTro(TroBase)                   [einzige echte Vererbung im Projekt]
├── _Positioned(BaseModel)                    (Mixin: position {x,y,z}, describe_position)
│   ├── TroBase, TroCandidate
├── Connection(BaseModel)                     (from/to/kind zwischen zwei TRO-IDs)
├── TroCandidate(_Positioned)                 (gemeldete Stelle, an der ein TRO erwartet wird)
├── Analysis(BaseModel)
│   ├─ tros: list[DerivedTro]
│   ├─ isolated: list[DerivedTro]
│   └─ boundaries: list[DerivedTro]
└── TroDocument(BaseModel)                    (= <csv>_tro.json)
    ├─ tros: list[DerivedTro]
    ├─ boundaries: list[DerivedTro]
    ├─ connections: list[Connection]
    └─ candidates: list[TroCandidate]

lib/material_flow.py                         [CSV-Rohmodell -> Graph, @dataclass]
├── Element                                   (1 CSV-Zeile)
├── Node
│   └─ element: Element
├── Edge
├── Graph
│   ├─ nodes: dict[str, Node]
│   ├─ edges: list[Edge]
│   └─ unassigned: list[Element]
├── TrackNode
│   └─ element: Element | None
├── TrackEdge
└── TrackGraph
    ├─ nodes: dict[str, TrackNode]
    └─ edges: list[TrackEdge]

lib/tro_overrides.py                         [manuelle Korrekturen aus cfg/tro_overrides.ini, @dataclass]
├── TroOverride         (Typkorrektur an einem abgeleiteten TRO: tro_id ODER separator)
├── SplitSpec           (TRO aus einem bestehenden heraustrennen)
├── MergeSpec           (mehrere TROs zu einem zusammenfassen)
└── Overrides            (Sammelcontainer für eine CSV-Datei)
    ├─ tros: dict[str, TroOverride]
    ├─ splits: list[SplitSpec]
    ├─ merges: list[MergeSpec]
    ├─ connections: list[model.Connection]
    └─ candidates: list[model.TroCandidate]

lib/dxf_registration.py                      [CSV<->DXF Koordinatentransform]
├── RegistrationError(RuntimeError)
└── Transform(BaseModel)

lib/scl_context.py                           [Render-Kontext für die SCL, BaseModel]
├── SclName              (Wert + Merker todo: noch aus der E-Planung offen?)
├── SclSeparator         (ein stInSeparator<n>-Block)
├── SclSwitch            (ein stInSwitch<n>-Block + FC_Direction-Aufruf)
├── SclSwitchExit        (Weichenabgang + darüber erreichbare TROs)
├── SclScanner           (ein stInBarcodeReader-Block)
├── SclJam               (Staubereich an Ein-/Ausgang)
├── SclTro               (alles für eine REGION)
│   ├─ separators: list[SclSeparator]
│   ├─ switches: list[SclSwitch]
│   ├─ switch_exits: list[SclSwitchExit]
│   ├─ scanners: list[SclScanner]
│   ├─ jam_entries / jam_exits: list[SclJam]
│   └─ main_tro, safety, ... : SclName
└── SclFile              (die ganze Datei)
    └─ tros: list[SclTro]                     (in Fliessrichtung)

lib/scl_skeleton.py                          [SCL-Ausgabe]
└── SclTemplates         (Ordner mit <fbType>.scl.j2, hält ein jinja2.Environment)

Auffälligkeiten für ein mögliches Refactoring

1. OpenPoint existiert zweimal — erledigt 2026-10-10: zu model.TroCandidate zusammengefasst (expect → type_name, x/y/z → position); ConnectionSpec durch model.Connection ersetzt; tro_overrides.py importiert beide aus model.py.
2. Zwei parallele Graph-Hierarchien in material_flow.py (Node/Edge/Graph vs. TrackNode/TrackEdge/TrackGraph) teilen sich keine Basisklasse, obwohl Struktur und Feldnamen sich stark ähneln (node_id, kind, ... / src, dst, ...). Eine gemeinsame leichte Basis (z. B. ein generisches GraphBase[NodeT, EdgeT]) wäre möglich, aber angesichts der wenigen Stellen, die beide Typen anfassen, vermutlich mehr Abstraktion als Nutzen.
3. TroItem und TroSymbol sind reine Konstanten-Namespaces (keine Instanzen, keine Methoden außer TroItem.all()), kein Pydantic-Modell wie der Rest von tro_catalog.py. Das ist bewusst so (siehe Docstring: "damit Tippfehler auffallen") und funktioniert wie ein Enum-Ersatz — ein StrEnum wäre eine nahe liegende, idiomatischere Alternative, falls ein Refactoring ansteht.
4. Die einzige echte Vererbung (DerivedTro(TroBase)) ist sauber: TroBase ist bereits so geschnitten, dass es für Systemgrenzen (boundaries) wiederverwendet wird, DerivedTro ergänzt nur das, was die CSV-Ableitung zusätzlich weiß. Kein Handlungsbedarf.

Fazit: Die Code-Basis nutzt Vererbung bewusst kaum — die Architektur trennt stattdessen über Module (Typ-Katalog vs. Instanz vs. Ableitung vs. Ausgabe, siehe model.py-Kopfkommentar) und über Komposition. Ein Refactoring in Richtung "mehr Vererbung" wäre hier eher kontraproduktiv. Die doppelte OpenPoint-Definition (1) ist behoben; offen bleibt nur optional StrEnum statt Konstanten-Klassen (3).

Die komplexen Klassen im Einzelnen

Die folgenden Abschnitte beschreiben je Klasse, wozu sie da ist, was darin passiert und wer sie erzeugt bzw. liest. Einfache Datenhalter ohne eigene Logik — Connection, TroCandidate, Edge, TrackEdge, TroItem/TroSymbol und die kleinen Blöcke SclSeparator, SclSwitch, SclSwitchExit, SclScanner, SclJam — sind im Baum oben ausreichend beschrieben und bekommen keinen eigenen Abschnitt.

TroDefinition (+ TroStyle) — lib/tro_catalog.py

Wozu: Beschreibt einen TRO-Typ, nicht eine Stelle in der Anlage: Kurzname (1Sep1Swi), Siemens-FB (FB_ILS_MTRO_1Sep1Swi), Bauteile ({"Separator": 1, "Switch": 1}), Farbgruppe und CAD-Symbol. Der Katalog aller Definitionen ist die ausführbare Form von doc/TRO_Typen.md.

Was passiert darin: Pydantic mit validate_assignment und extra="forbid" — eine Definition kann nie ungültig werden, auch nicht über die set_*-Methoden. _clean_items wirft Bauteile mit Anzahl ≤ 0 heraus. Ein eigener __init__ erlaubt die alte Positionsform TroDefinition("1Sep", "FB_...", {...}). Dazu kommen Abfragen (get_items, has_item, get_item_fb, get_total_items) und Darstellungshelfer (get_dot_attrs, mermaid_class/_classdef, describe_items). TroStyle liefert nur die Farben einer Gruppe für Graphviz, Mermaid und CAD.

Wer nutzt sie: Über get_tro(name)/catalog() jeder, der vom Typnamen auf FB oder Bauteile kommen muss — vor allem TroBase.definition(); außerdem tro_flow (Typprüfung), tro_annotate (Farbe/Symbol, --emit-lisp) und die Doku-Grafiken.

TroBase / DerivedTro — lib/model.py

Wozu: Ein konkreter TRO in einer Anlage (Instanz). TroBase ist der Kern, den jeder TRO hat, egal woher er stammt: tro_id, type_name, separators, predecessors/successors, position. DerivedTro ergänzt, was tro_flow beim Ableiten aus dem CSV zusätzlich weiß: hosts, scanners, reason, colocated, position_from/position_points. Systemgrenzen (SYSn) sind ebenfalls DerivedTro.

Was passiert darin:

• fb_block und items sind berechnete Felder: bei jedem Zugriff aus dem Katalog gelesen (definition() → get_tro(type_name)), nie gespeichert. In der JSON stehen sie trotzdem (fbType, items), damit sie lesbar ist.
• _check_catalog_fields (Validator vor dem Einlesen): steht in einer JSON ein items/fbType, das nicht zum Typ passt, ist das ein Fehler — "den Typ ändern, nicht die Bauteile". Danach werden die Felder verworfen.
• Aliase: in der JSON id/type, im Code tro_id/type_name (populate_by_name).
• _Positioned (Mixin) wandelt position zwischen Tupel und {"x","y","z"} und liefert x/y/z und describe_position().
• DerivedTro.connected: hat der TRO überhaupt Nachbarn?

Wer nutzt sie: tro_flow.derive_tros/derive_boundaries erzeugen sie, scl_context liest sie (als TroBase), tro_annotate zeichnet sie.

Analysis — lib/model.py

Wozu: Das Arbeitsergebnis eines Ableitungslaufs, bevor daraus eine Datei wird. Enthält mehr als die JSON: Kanten als Tupel, Kantenarten, isolierte TROs, unbekannte Typen, Befunde, die verwendete Methode.

Was passiert darin: Fast nur Daten; by_id() sucht über TROs und Systemgrenzen. Befüllt wird sie in tro_flow.analyse_tros in fester Reihenfolge: derive_tros → derive_boundaries → locate_tros (Position, nötig für die Reihenfolge auf einer Kreiselbahn) → link_tros (Kanten und Kantenarten) → Prüfung gegen den Katalog.

Wer nutzt sie: tro_flow (Bericht, Diagramm, --json) und tro_annotate (zeichnet direkt aus der Analysis, ohne Umweg über die JSON).

TroDocument — lib/model.py

Wozu: Die TRO-JSON <csv>_tro.json (Schema sps_skel-tro-v3) — die Schnittstelle zwischen Ableitung (tro_flow --json) und SCL-Ausgabe (scl_skeleton). Weil beide Seiten dieselbe Klasse benutzen, kann das Format nicht unbemerkt auseinanderlaufen.

Was passiert darin: from_analysis() macht aus einer Analysis ein Dokument (Kanten + Kantenarten → Connection-Liste). to_json() schreibt mit den JSON-Aliasen, from_json() liest und prüft. extra="forbid" sorgt dafür, dass ein umbenannter oder falscher Schlüssel als Fehler auffällt statt still einen Standardwert zu bekommen; scl_skeleton.main meldet bei falschem schema gezielt "mit tro_flow neu erzeugen".

Wer nutzt sie: geschrieben von tro_flow --json, gelesen von scl_skeleton.load_document → scl_context.build_context.

Element, Graph, TrackGraph — lib/material_flow.py

Wozu: Das Rohmodell aus dem CSV-Export (ILS 2.0), noch ohne TRO-Begriff.

• Element = eine CSV-Zeile: Art, ID, Name, Nachbarn, track_ids, Merkmale, Position, Bounding-Box, Anschlusspunkte K1..K4.
• Graph (Node/Edge) = grober Materialfluss-Graph: Transportobjekte (Strecke, Gefällestrecke, Kreisel-Bahn) als Knoten, Geräte (Separatoren, Weichen, Scanner …) an die Knoten gehängt (Node.devices), Stationen und Übergaben als Kanten.
• TrackGraph (TrackNode/TrackEdge) = feiner Bahnzusammenhang: jedes Bahnelement (AS, SEP, ES, Weiche, BTMT …) ist ein Knoten, verkettet in Bau- bzw. Drehrichtung (siehe doc/track.md).

Was passiert darin: Element hat viele abgeleitete Properties: Klassifizierung (is_transport, is_circle, is_device, is_station, is_transfer, is_entry/is_exit), Geometrie (x/y/z, bbox_x/y, height, height_from/to, rise), Antrieb (drive_dir, rotation). Die Graphklassen selbst sind reine Container; die Logik steckt in den Funktionen build_graph() (Knoten bilden, Geräte zuordnen, Kanten sammeln, Fliessrichtung aus Gefälle/Antrieb, Stationen und Übergaben einhängen) und build_track_graph() (Ketten aus der Spalte TrackIds; ein Element in zwei Containern verbindet diese automatisch). TrackNode kann ohne element existieren (Platzhalter für eine nicht auflösbare Bahn, generisches Ein-/Ausgang-Symbol).

Wer nutzt sie: material_flow selbst (DOT/SVG/connect.ini/Bericht) und tro_flow.analyse_tros(graph, elements) als Eingang der TRO-Ableitung; tro_annotate für Ankerpunkte des Lagebezugs.

Overrides (+ TroOverride, SplitSpec, MergeSpec) — lib/tro_overrides.py

Wozu: Von Hand gepflegte, vor Ort bestätigte Korrekturen aus cfg/tro_overrides.ini für das, was die Ableitung nicht erkennen kann.

• TroOverride: Typ eines TRO korrigieren. Adressiert über tro_id oder — stabiler — über einen separator, weil TRO-Nummern sich zwischen Läufen verschieben, Separatornummern aus dem Export nicht (matches()).
• SplitSpec: Separatoren/Scanner aus einem TRO herauslösen und einen neuen TRO bilden (Übergabestelle, deren Zuordnung auf die Strecke statt auf die Kreiselbahn zeigt).
• MergeSpec: mehrere TROs zu einem Steuerobjekt zusammenfassen (z. B. zwei Sperren beiderseits eines Kreisel-Berührpunkts).
• Overrides: Sammelcontainer je CSV-Datei, dazu gesetzte Topologie (connections, ersetzt die abgeleiteten Kanten vollständig), erwartete TROs (candidates), Protokoll (applied) und warnings. bool(overrides) ist True, sobald irgendeine Korrektur vorhanden ist.

Was passiert darin: load_overrides(csv_name) liest den INI-Abschnitt der CSV-Datei und baut daraus die Objekte; Lesefehler landen in warnings statt den Lauf abzubrechen.

Wer nutzt sie: Stand heute nur material_flow --connect (render_connect_ini schreibt sie als [<Anlage>.manual]-Abschnitt). tro_flow wendet sie (noch) nicht an — sie fliessen also nicht in die TRO-JSON und nicht in die SCL.

Transform (+ RegistrationError) — lib/dxf_registration.py

Wozu: Der Lagebezug zwischen CSV-Export und BricsCAD-Zeichnung: eine starre Transformation csv = R(rotation) · dxf + (dx, dy). Ohne sie landen die TRO-Marker in tro_annotate an der falschen Stelle.

Was passiert darin: to_csv()/to_dxf() rechnen Punkte hin und zurück, describe() fasst Verschiebung, Drehung, Punktzahl und Restfehler zusammen. Die Ermittlung steckt in Funktionen: derive_transform() ordnet punktartige Objekte gleicher Rolle (Separator, Scanner) aus CSV und DXF zu, stimmt über Verschiebungen ab, gleicht aus und wählt den besten Kandidaten; verify_transform() rechnet die Restfehler nach und schreibt sie ins Objekt; load_transform()/save_transform() lesen/schreiben cfg/dxf_registration.json. RegistrationError heisst: der Bezug liess sich nicht nachweisbar bestimmen — dann lieber abbrechen als falsch zeichnen.

Wer nutzt sie: tro_annotate.resolve_transform (Reihenfolge: --offset → abgelegter Bezug → neu ermitteln, jeweils mit Prüfung), dazu das geparkte tro_extract.

SclFile, SclTro, SclName — lib/scl_context.py

Wozu: Der Render-Kontext für das FB_Main-Gerüst. Alles, was aus der TRO-JSON abgeleitet wird, steht hier fertig drin; die Ausgabe (emit_*-Funktionen oder Jinja-Templates) rechnet nichts mehr selbst, sie liest nur noch. So können generischer Aufbau und Templates nicht unterschiedlich ableiten.

Was passiert darin:

• build_context(document, source, start_id) baut aus einem TroDocument ein SclFile: Kopfdaten plus die TROs in Fliessrichtung.
• flow_order() bestimmt die Reihenfolge der REGIONs: Start bei --start, sonst beim TRO ohne Vorgänger, sonst beim TRO, den eine Station (SYSn) speist, sonst wird der Kreislauf willkürlich aufgetrennt — der Grund steht im SCL-Kopf (start_reason). Danach Breitensuche; nicht erreichte TROs werden hinten angehängt, damit keiner verloren geht.
• _tro_context() baut je TRO ein SclTro: so viele Separator-, Weichen- und Scannerblöcke, wie der Katalogtyp Bauteile hat (items); je Vorgänger ein Staubereich am Eingang, je Nachfolger einer am Ausgang; to1_destinations nur bei genau einer Weiche (bei mehreren ist die Aufteilung eine Planungsentscheidung); die Zielliste je Weichenabgang über reachable_via() (Erreichbarkeit im TRO-Graphen, ohne über die Weiche zurückzulaufen).
• SclName = Wert + Merker todo. Alles, was aus der E-Planung kommen muss (Separator-/Weichennummern, Sensor-/Aktoradressen, MainTro, Staubereichs-DB …), ist heute ein Platzhalter mit todo=True; die Ausgabe hängt daran den Kommentar TODO(E-Planung). Spätere Namensregeln ersetzen nur den Wert und löschen den Merker — die Ausgabe ändert sich dafür nicht.

Wer nutzt sie: erzeugt in scl_skeleton.render()/main(), gelesen von render_context(), den emit_*-Funktionen und den Templates (als t).

SclTemplates — lib/scl_skeleton.py

Wozu: Die Anbindung der parametrisierten SCL-Aufrufstellen (lib/scl_templates/*.scl.j2) an die Ausgabe. Ein Objekt steht für einen Template-Ordner.

Was passiert darin: Der Konstruktor baut ein jinja2.Environment mit StrictUndefined (ein Tippfehler im Template wird zum Fehler statt zu einer leeren SCL-Stelle), trim_blocks/lstrip_blocks und der globalen Variable TODO. has(fb) prüft, ob <fb>.scl.j2 existiert; render(tro) rendert das Template mit t = SclTro und fasst danach mehrfache Leerzeilen zusammen (statt das mit {%- -%} im Template zu tun, was die Einrückung bricht).

Template ↔ TRO: Zuordnung und Einstieg in die Produktion

Zuordnung — es gibt keine Tabelle, nur eine Namenskonvention: Dateiname = FB-Typ. Die Kette:

DerivedTro.type_name            "1Sep1Swi"                  (TRO-JSON, Feld "type")
  -> tro_catalog.get_tro()      TroDefinition
  -> TroDefinition.fb_block     "FB_ILS_MTRO_1Sep1Swi"
  -> TroBase.fb_block           (berechnet, nicht gespeichert)
  -> SclTro.fb                  (scl_context._tro_context)
  -> SclTemplates.has/render    lib/scl_templates/FB_ILS_MTRO_1Sep1Swi.scl.j2

Ein neues Template für einen weiteren Typ heisst also einfach <fbType>.scl.j2 und wird automatisch für alle TROs dieses Typs verwendet. Heute gibt es nur den Piloten FB_ILS_MTRO_1Sep1Swi.scl.j2 (plus _macros.scl.j2 mit gemeinsamen Makros). Alle anderen Typen laufen über den generischen Aufbau (emit_region()).

Einstieg — nur per Schalter (opt-in):

• scl_skeleton --templates [DIR] (ohne DIR: lib/scl_templates). main() legt dann ein SclTemplates an; render_context() nimmt pro TRO templates.render(tro), wenn templates.has(tro.fb), sonst emit_region(). Der SCL-Kopf listet, welche FB-Typen aus Template bzw. generisch kamen.
• --strict bricht ab (Exit 1, keine SCL), wenn ein FB-Typ der Anlage kein Template hat. Ein TemplateError (fehlende Variable, Syntaxfehler) bricht ebenfalls ab — lieber keine SCL als eine mit stillen Lücken.
• Ohne --templates werden Templates gar nicht geladen; die Ausgabe ist die bisherige (Golden-Files tests/fixtures/scl/*_FB_Main.scl). Mit Templates pinnen *_FB_Main_templates.scl das Ergebnis.
• bin/scl_skeleton.bat/.sh reichen die Schalter nur durch; der Standardaufruf ohne --templates nutzt also keine Templates.

Nicht Produktion: doc/TRO_Katalog/scl_templates/*.scl sind die realen Referenz-Aufrufstellen. Gegen sie prüft tests/test_scl_templates.py jedes Template im Round-Trip; in die erzeugte SCL fliessen sie nicht ein.