feat: introduce TransitionNodes (only 1 subsequent step, no decision) (#382)

Co-authored-by: Konstantin <[email protected]>

Author: hf-kklein

src/rebdhuhn/graph_conversion.py

@@ -2,7 +2,7 @@
 This module contains logic to convert EbdTable data to EbdGraph data.
 """
 
-from typing import Dict, List, Optional
+from typing import Dict, List, Literal, Optional, overload
 
 from networkx import DiGraph  # type:ignore[import-untyped]
 
@@ -22,7 +22,7 @@
     ToNoEdge,
     ToYesEdge,
 )
-from rebdhuhn.models.ebd_graph import EmptyNode
+from rebdhuhn.models.ebd_graph import EmptyNode, TransitionEdge, TransitionNode
 from rebdhuhn.models.errors import (
     EbdCrossReferenceNotSupportedError,
     EndeInWrongColumnError,
@@ -69,17 +69,29 @@ def _convert_sub_row_to_outcome_node(sub_row: EbdTableSubRow) -> Optional[Outcom
     return None
 
 
-def _convert_row_to_decision_node(row: EbdTableRow) -> DecisionNode:
+def _convert_row_to_decision_or_transition_node(row: EbdTableRow) -> DecisionNode | TransitionNode:
     """
     converts a row into a decision node
     """
+    if len(row.sub_rows) == 1 and row.sub_rows[0].check_result.result is None:
+        # this is a transition node
+        return TransitionNode(step_number=row.step_number, question=row.description, note=row.sub_rows[0].note)
     return DecisionNode(step_number=row.step_number, question=row.description)
 
 
-def _yes_no_transition_edge(decision: Optional[bool], source: DecisionNode, target: EbdGraphNode) -> EbdGraphEdge:
-    if decision is None:
-        # happens in another PR
-        raise NotImplementedError("None not supported yet; https://github.com/Hochfrequenz/rebdhuhn/issues/380")
+@overload
+def _yes_no_transition_edge(
+    decision: Literal[None], source: TransitionNode, target: EbdGraphNode
+) -> TransitionEdge: ...
+@overload
+def _yes_no_transition_edge(decision: bool, source: DecisionNode, target: EbdGraphNode) -> EbdGraphEdge: ...
+def _yes_no_transition_edge(
+    decision: Optional[bool], source: DecisionNode | TransitionNode, target: EbdGraphNode
+) -> EbdGraphEdge:
+    if decision is None and isinstance(source, TransitionNode):
+        return TransitionEdge(source=source, target=target, note=None)
+    assert not isinstance(source, TransitionNode), "Iff the decision is None, source must be a TransitionNode"
+    assert isinstance(source, DecisionNode)
     if decision is True:
         return ToYesEdge(source=source, target=target, note=None)
     if decision is False:
@@ -95,8 +107,10 @@ def get_all_nodes(table: EbdTable) -> List[EbdGraphNode]:
     result: List[EbdGraphNode] = [StartNode()]
     contains_ende = False
     for row in table.rows:
-        decision_node = _convert_row_to_decision_node(row)
-        result.append(decision_node)
+        decision_or_transition_node = _convert_row_to_decision_or_transition_node(row)
+        result.append(decision_or_transition_node)
+        if isinstance(decision_or_transition_node, TransitionNode):
+            continue
         for sub_row in row.sub_rows:
             outcome_node = _convert_sub_row_to_outcome_node(sub_row)
             if outcome_node is not None:
@@ -134,12 +148,24 @@ def get_all_edges(table: EbdTable) -> List[EbdGraphEdge]:
     outcome_nodes_duplicates: dict[str, OutcomeNode] = {}  # map to check for duplicate outcome nodes
 
     for row in table.rows:
-        decision_node = _convert_row_to_decision_node(row)
+        row_node = _convert_row_to_decision_or_transition_node(row)
+        if isinstance(row_node, TransitionNode):
+            assert row.sub_rows[0].check_result.subsequent_step_number is not None
+            result.append(
+                TransitionEdge(
+                    source=row_node,
+                    target=nodes[row.sub_rows[0].check_result.subsequent_step_number],
+                    note=row_node.note,
+                )
+            )
+            continue
+        assert isinstance(row_node, DecisionNode)
         for sub_row in row.sub_rows:
+            assert isinstance(sub_row.check_result.result, bool)
             if sub_row.check_result.subsequent_step_number is not None and not _is_ende_with_no_code_but_note(sub_row):
                 edge = _yes_no_transition_edge(
                     sub_row.check_result.result,
-                    source=decision_node,
+                    source=row_node,
                     target=nodes[sub_row.check_result.subsequent_step_number],
                 )
             else:
@@ -149,8 +175,8 @@ def get_all_edges(table: EbdTable) -> List[EbdGraphEdge]:
                     if all(sr.result_code is None for sr in row.sub_rows) and any(
                         sr.note is not None and sr.note.startswith("EBD ") for sr in row.sub_rows
                     ):
-                        raise EbdCrossReferenceNotSupportedError(row=row, decision_node=decision_node)
-                    raise OutcomeNodeCreationError(decision_node=decision_node, sub_row=sub_row)
+                        raise EbdCrossReferenceNotSupportedError(row=row, decision_node=row_node)
+                    raise OutcomeNodeCreationError(decision_node=row_node, sub_row=sub_row)
 
                 # check for ambiguous outcome nodes, i.e. A** with different notes
                 is_ambiguous_outcome_node = (
@@ -167,7 +193,7 @@ def get_all_edges(table: EbdTable) -> List[EbdGraphEdge]:
 
                 edge = _yes_no_transition_edge(
                     sub_row.check_result.result,
-                    source=decision_node,
+                    source=row_node,
                     target=nodes[outcome_node.get_key()],
                 )
             result.append(edge)

src/rebdhuhn/graphviz.py

@@ -10,7 +10,7 @@
 from rebdhuhn.graph_utils import _mark_last_common_ancestors
 from rebdhuhn.kroki import DotToSvgConverter
 from rebdhuhn.models import DecisionNode, EbdGraph, EbdGraphEdge, EndNode, OutcomeNode, StartNode, ToNoEdge, ToYesEdge
-from rebdhuhn.models.ebd_graph import EmptyNode
+from rebdhuhn.models.ebd_graph import EmptyNode, TransitionNode
 from rebdhuhn.utils import add_line_breaks
 
 ADD_INDENT = "    "  #: This is just for style purposes to make the plantuml files human-readable.
@@ -104,6 +104,25 @@ def _convert_decision_node_to_dot(ebd_graph: EbdGraph, node: str, indent: str) -
     )
 
 
+def _convert_transition_node_to_dot(ebd_graph: EbdGraph, node: str, indent: str) -> str:
+    """
+    Convert a TransitionNode to dot code
+    """
+    formatted_label = (
+        f'<B>{ebd_graph.graph.nodes[node]["node"].step_number}: </B>'
+        f'{_format_label(ebd_graph.graph.nodes[node]["node"].question)}'
+        f'<BR align="left"/>'
+    )
+    if ebd_graph.graph.nodes[node]["node"].note:
+        formatted_label += (
+            f"<FONT>" f'{_format_label(ebd_graph.graph.nodes[node]["node"].note)}<BR align="left"/>' f"</FONT>"
+        )
+    return (
+        f'{indent}"{node}" [margin="0.2,0.12", shape=box, style="filled,rounded", penwidth=0.0, fillcolor="#c2cee9", '
+        f'label=<{formatted_label}>, fontname="Roboto, sans-serif"];'
+    )
+
+
 def _convert_node_to_dot(ebd_graph: EbdGraph, node: str, indent: str) -> str:
     """
     A shorthand to convert an arbitrary node to dot code. It just determines the node type and calls the
@@ -120,6 +139,8 @@ def _convert_node_to_dot(ebd_graph: EbdGraph, node: str, indent: str) -> str:
             return _convert_start_node_to_dot(ebd_graph, node, indent)
         case EmptyNode():
             return _convert_empty_node_to_dot(ebd_graph, node, indent)
+        case TransitionNode():
+            return _convert_transition_node_to_dot(ebd_graph, node, indent)
         case _:
             raise ValueError(f"Unknown node type: {ebd_graph.graph.nodes[node]['node']}")
 

src/rebdhuhn/models/ebd_graph.py

@@ -150,6 +150,33 @@ def get_key(self) -> str:
         return "Empty"
 
 
+@attrs.define(auto_attribs=True, kw_only=True, frozen=True)
+class TransitionNode(EbdGraphNode):
+    """
+    A transition node is a leaf of the Entscheidungsbaum tree.
+    It has exactly one subsequent step and does neither contain a decision nor an outcome.
+    Its fields are the same as the DecisionNode, but they are functionally different.
+    It's related to an EbdCheckResult/SubRow which has a check_result.result None and only 1 subsequent step number.
+    """
+
+    step_number: str = attrs.field(validator=attrs.validators.matches_re(r"\d+\*?"))
+    """
+    number of the Prüfschritt, e.g. '105', '2' or '6*'
+    """
+    question: str = attrs.field(validator=attrs.validators.instance_of(str))
+    """
+    the questions which is asked at this node in the tree
+    """
+    note: Optional[str] = attrs.field(validator=attrs.validators.optional(attrs.validators.instance_of(str)))
+    """
+    An optional note that explains the purpose, e.g.
+    'Aufnahme von 0..n Treffern in die neue Trefferliste auf Basis von drei Kriterien'
+    """
+
+    def get_key(self) -> str:
+        return self.step_number
+
+
 @attrs.define(auto_attribs=True, kw_only=True)
 class EbdGraphEdge:
     """
@@ -196,6 +223,18 @@ class ToNoEdge(EbdGraphEdge):
     """
 
 
+@attrs.define(auto_attribs=True, kw_only=True)
+class TransitionEdge(EbdGraphEdge):
+    """
+    an edge that connects a TransitionNode to the respective next step
+    """
+
+    source: TransitionNode = attrs.field(validator=attrs.validators.instance_of(TransitionNode))
+    """
+    ths source which refers to the next step
+    """
+
+
 @attrs.define(auto_attribs=True, kw_only=True)
 class EbdGraph:
     """

unittests/__snapshots__/test_table_to_graph.ambr

@@ -1838,3 +1838,35 @@
   }
   '''
 # ---
+# name: TestEbdTableModels.test_table_to_dot_to_svg[E_0594-partly][table_dot_svg_E_0594]
+  '''
+  digraph D {
+      labelloc="t";
+      label=<<B><FONT POINT-SIZE="18">GPKE</FONT></B><BR align="left"/><BR/><B><FONT POINT-SIZE="16">MaLo Ident</FONT></B><BR align="left"/><BR/><BR/><BR/>>;
+      ratio="compress";
+      concentrate=true;
+      pack=true;
+      rankdir=TB;
+      packmode="array";
+      size="20,20";
+      fontsize=12;
+      pad=0.25;
+      "Start" [margin="0.2,0.12", shape=box, style="filled,rounded", penwidth=0.0, fillcolor="#8ba2d7", label=<<B>E_0594</B><BR align="left"/><FONT>Prüfende Rolle: <B>VNB</B></FONT><BR align="center"/>>, fontname="Roboto, sans-serif"];
+      "270" [margin="0.2,0.12", shape=box, style="filled,rounded", penwidth=0.0, fillcolor="#c2cee9", label=<<B>270: </B>Ist das Identifikationskriterium „Adresse“ in der Anfrage enthalten?<BR align="left"/>>, fontname="Roboto, sans-serif"];
+      "275" [margin="0.2,0.12", shape=box, style="filled,rounded", penwidth=0.0, fillcolor="#c2cee9", label=<<B>275: </B>Vollständige [Adressprüfung]<BR align="left"/><FONT>Aufnahme von 0..n Treffern in die Trefferliste auf Basis der alleinigen<BR align="left"/>Adressprüfung<BR align="left"/></FONT>>, fontname="Roboto, sans-serif"];
+      "280" [margin="0.2,0.12", shape=box, style="filled,rounded", penwidth=0.0, fillcolor="#c2cee9", label=<<B>280: </B>Gibt es in der Trefferliste auf Basis der alleinigen Adressprüfung genau einen<BR align="left"/>Treffer mit dem Identifikationskriterium Adresse?<BR align="left"/>>, fontname="Roboto, sans-serif"];
+      "A02" [margin="0.2,0.12", shape=box, style="filled,rounded", penwidth=0.0, fillcolor="#c4cac1", label=<<B>A02</B><BR align="left"/><BR align="left"/><FONT>Cluster Ablehnung blablba<BR align="left"/></FONT>>, fontname="Roboto, sans-serif"];
+      "A123" [margin="0.2,0.12", shape=box, style="filled,rounded", penwidth=0.0, fillcolor="#c4cac1", label=<<B>A123</B><BR align="left"/><BR align="left"/><FONT>Cluster keine Ablehnung bliblub<BR align="left"/></FONT>>, fontname="Roboto, sans-serif"];
+  
+      "Start" -> "270" [color="#88a0d6"];
+      "270" -> "275" [label=<<B>JA</B>>, color="#88a0d6", fontname="Roboto, sans-serif"];
+      "270" -> "280" [label=<<B>NEIN</B>>, color="#88a0d6", fontname="Roboto, sans-serif"];
+      "275" -> "280" [color="#88a0d6"];
+      "280" -> "A02" [label=<<B>NEIN</B>>, color="#88a0d6", fontname="Roboto, sans-serif"];
+      "280" -> "A123" [label=<<B>JA</B>>, color="#88a0d6", fontname="Roboto, sans-serif"];
+  
+      bgcolor="transparent";
+  fontname="Roboto, sans-serif";
+  }
+  '''
+# ---