improved docs, naming in the flow step sequence

rasa/shared/core/flows/flow.py

@@ -20,7 +20,7 @@
 from rasa.shared.core.flows.steps.start import StartFlowStep
 from rasa.shared.core.flows.steps.collect import CollectInformationFlowStep
 from rasa.shared.core.flows.steps.link import LinkFlowStep
-from rasa.shared.core.flows.flow_step_sequence import StepSequence
+from rasa.shared.core.flows.flow_step_sequence import FlowStepSequence
 
 
 @dataclass
@@ -33,7 +33,7 @@ class Flow:
     """The human-readable name of the flow."""
     description: Optional[Text]
     """The description of the flow."""
-    step_sequence: StepSequence
+    step_sequence: FlowStepSequence
     """The steps of the flow."""
 
     @staticmethod
@@ -46,7 +46,7 @@ def from_json(flow_id: Text, data: Dict[Text, Any]) -> Flow:
         Returns:
             A Flow object.
         """
-        step_sequence = StepSequence.from_json(data.get("steps"))
+        step_sequence = FlowStepSequence.from_json(data.get("steps"))
 
         return Flow(
             id=flow_id,
@@ -61,7 +61,7 @@ def create_default_name(flow_id: str) -> str:
         return flow_id.replace("_", " ").replace("-", " ")
 
     @staticmethod
-    def resolve_default_ids(step_sequence: StepSequence) -> StepSequence:
+    def resolve_default_ids(step_sequence: FlowStepSequence) -> FlowStepSequence:
         """Resolves the default ids of all steps in the sequence.
 
         If a step does not have an id, a default id is assigned to it based

rasa/shared/core/flows/flow_step_links.py

@@ -7,7 +7,7 @@
 from rasa.shared.core.flows.flow_step import FlowStep
 
 if TYPE_CHECKING:
-    from rasa.shared.core.flows.flow_step_sequence import StepSequence
+    from rasa.shared.core.flows.flow_step_sequence import FlowStepSequence
 
 
 @dataclass
@@ -107,31 +107,31 @@ def child_steps(self) -> List[FlowStep]:
 
 @dataclass
 class BranchingFlowStepLink(FlowStepLink):
-    target_reference: Union[Text, StepSequence]
+    target_reference: Union[Text, FlowStepSequence]
     """The id of the linked step or a sequence of steps."""
 
     def steps_in_tree(self) -> Generator[FlowStep, None, None]:
         """Recursively generates the steps in the tree."""
-        from rasa.shared.core.flows.flow_step_sequence import StepSequence
+        from rasa.shared.core.flows.flow_step_sequence import FlowStepSequence
 
-        if isinstance(self.target_reference, StepSequence):
+        if isinstance(self.target_reference, FlowStepSequence):
             yield from self.target_reference.steps
 
     def child_steps(self) -> List[FlowStep]:
         """Returns the steps of the linked flow step sequence if any."""
-        from rasa.shared.core.flows.flow_step_sequence import StepSequence
+        from rasa.shared.core.flows.flow_step_sequence import FlowStepSequence
 
-        if isinstance(self.target_reference, StepSequence):
+        if isinstance(self.target_reference, FlowStepSequence):
             return self.target_reference.child_steps
         else:
             return []
 
     @property
     def target(self) -> Text:
         """Return the target flow step id."""
-        from rasa.shared.core.flows.flow_step_sequence import StepSequence
+        from rasa.shared.core.flows.flow_step_sequence import FlowStepSequence
 
-        if isinstance(self.target_reference, StepSequence):
+        if isinstance(self.target_reference, FlowStepSequence):
             if first := self.target_reference.first():
                 return first.id
             else:
@@ -175,13 +175,13 @@ def from_json(data: Dict[Text, Any]) -> IfFlowStepLink:
         Returns:
             An IfFlowStepLink object.
         """
-        from rasa.shared.core.flows.flow_step_sequence import StepSequence
+        from rasa.shared.core.flows.flow_step_sequence import FlowStepSequence
 
         if isinstance(data["then"], str):
             return IfFlowStepLink(target_reference=data["then"], condition=data["if"])
         else:
             return IfFlowStepLink(
-                target_reference=StepSequence.from_json(data["then"]),
+                target_reference=FlowStepSequence.from_json(data["then"]),
                 condition=data["if"],
             )
 
@@ -191,12 +191,12 @@ def as_json(self) -> Dict[Text, Any]:
         Returns:
             the IfFlowStepLink object as serialized data.
         """
-        from rasa.shared.core.flows.flow_step_sequence import StepSequence
+        from rasa.shared.core.flows.flow_step_sequence import FlowStepSequence
 
         return {
             "if": self.condition,
             "then": self.target_reference.as_json()
-            if isinstance(self.target_reference, StepSequence)
+            if isinstance(self.target_reference, FlowStepSequence)
             else self.target_reference,
         }
 
@@ -215,13 +215,13 @@ def from_json(data: Dict[Text, Any]) -> ElseFlowStepLink:
         Returns:
             An ElseFlowStepLink
         """
-        from rasa.shared.core.flows.flow_step_sequence import StepSequence
+        from rasa.shared.core.flows.flow_step_sequence import FlowStepSequence
 
         if isinstance(data["else"], str):
             return ElseFlowStepLink(target_reference=data["else"])
         else:
             return ElseFlowStepLink(
-                target_reference=StepSequence.from_json(data["else"])
+                target_reference=FlowStepSequence.from_json(data["else"])
             )
 
     def as_json(self) -> Dict[Text, Any]:
@@ -230,11 +230,11 @@ def as_json(self) -> Dict[Text, Any]:
         Returns:
             The ElseFlowStepLink as serialized data.
         """
-        from rasa.shared.core.flows.flow_step_sequence import StepSequence
+        from rasa.shared.core.flows.flow_step_sequence import FlowStepSequence
 
         return {
             "else": self.target_reference.as_json()
-            if isinstance(self.target_reference, StepSequence)
+            if isinstance(self.target_reference, FlowStepSequence)
             else self.target_reference
         }
 

rasa/shared/core/flows/flow_step_sequence.py

@@ -8,29 +8,31 @@
 
 
 @dataclass
-class StepSequence:
+class FlowStepSequence:
+    """A Sequence of flow steps."""
+
     child_steps: List[FlowStep]
 
     @staticmethod
-    def from_json(steps_config: List[Dict[Text, Any]]) -> StepSequence:
-        """Used to read steps from parsed YAML.
+    def from_json(data: List[Dict[Text, Any]]) -> FlowStepSequence:
+        """Create a StepSequence object from serialized data
 
         Args:
-            steps_config: The parsed YAML as a dictionary.
+            data: data for a StepSequence in a serialized format
 
         Returns:
-            The parsed steps.
+            A StepSequence object including its flow step objects.
         """
 
-        flow_steps: List[FlowStep] = [step_from_json(config) for config in steps_config]
+        flow_steps: List[FlowStep] = [step_from_json(config) for config in data]
 
-        return StepSequence(child_steps=flow_steps)
+        return FlowStepSequence(child_steps=flow_steps)
 
     def as_json(self) -> List[Dict[Text, Any]]:
-        """Returns the steps as a dictionary.
+        """Serialize the StepSequence object and contained FlowStep objects
 
         Returns:
-            The steps as a dictionary.
+            the StepSequence and its FlowSteps as serialized data
         """
         return [
             step.as_json()
@@ -40,15 +42,15 @@ def as_json(self) -> List[Dict[Text, Any]]:
 
     @property
     def steps(self) -> List[FlowStep]:
-        """Returns the steps of the flow."""
+        """Return all steps in this step sequence and their sub steps."""
         return [
             step
             for child_step in self.child_steps
             for step in child_step.steps_in_tree()
         ]
 
     def first(self) -> Optional[FlowStep]:
-        """Returns the first step of the sequence."""
+        """Return the first step of the sequence."""
         if len(self.child_steps) == 0:
             return None
         return self.child_steps[0]

rasa/shared/core/flows/validation.py

@@ -10,7 +10,7 @@
     IfFlowStepLink,
     ElseFlowStepLink,
 )
-from rasa.shared.core.flows.flow_step_sequence import StepSequence
+from rasa.shared.core.flows.flow_step_sequence import FlowStepSequence
 from rasa.shared.core.flows.steps.constants import CONTINUE_STEP_PREFIX, DEFAULT_STEPS
 from rasa.shared.core.flows.steps.link import LinkFlowStep
 from rasa.shared.core.flows.flow import Flow
@@ -201,7 +201,7 @@ def validate_no_empty_step_sequences(flow: Flow) -> None:
         for link in step.next.links:
             if (
                 isinstance(link, BranchingFlowStepLink)
-                and isinstance(link.target_reference, StepSequence)
+                and isinstance(link.target_reference, FlowStepSequence)
                 and len(link.target_reference.child_steps) == 0
             ):
                 raise EmptyStepSequenceException(flow.id, step.id)

tests/dialogue_understanding/stack/frames/test_flow_frame.py

@@ -8,7 +8,7 @@
 )
 from rasa.shared.core.flows.flow_step_links import FlowStepLinks
 from rasa.shared.core.flows.steps.action import ActionFlowStep
-from rasa.shared.core.flows.flow_step_sequence import StepSequence
+from rasa.shared.core.flows.flow_step_sequence import FlowStepSequence
 from rasa.shared.core.flows.flow import Flow
 from rasa.shared.core.flows.flows_list import FlowsList
 
@@ -55,7 +55,7 @@ def test_flow_get_flow():
     frame = UserFlowStackFrame(frame_id="test", flow_id="foo", step_id="bar")
     flow = Flow(
         id="foo",
-        step_sequence=StepSequence(child_steps=[]),
+        step_sequence=FlowStepSequence(child_steps=[]),
         name="foo flow",
         description="foo flow description",
     )
@@ -69,7 +69,7 @@ def test_flow_get_flow_non_existant_id():
         flows=[
             Flow(
                 id="foo",
-                step_sequence=StepSequence(child_steps=[]),
+                step_sequence=FlowStepSequence(child_steps=[]),
                 name="foo flow",
                 description="foo flow description",
             )
@@ -93,7 +93,7 @@ def test_flow_get_step():
         flows=[
             Flow(
                 id="foo",
-                step_sequence=StepSequence(child_steps=[step]),
+                step_sequence=FlowStepSequence(child_steps=[step]),
                 name="foo flow",
                 description="foo flow description",
             )
@@ -108,7 +108,7 @@ def test_flow_get_step_non_existant_id():
         flows=[
             Flow(
                 id="foo",
-                step_sequence=StepSequence(child_steps=[]),
+                step_sequence=FlowStepSequence(child_steps=[]),
                 name="foo flow",
                 description="foo flow description",
             )
@@ -124,7 +124,7 @@ def test_flow_get_step_non_existant_flow_id():
         flows=[
             Flow(
                 id="foo",
-                step_sequence=StepSequence(child_steps=[]),
+                step_sequence=FlowStepSequence(child_steps=[]),
                 name="foo flow",
                 description="foo flow description",
             )