Deprecate passing step_id to FlowHandler methods (#107944)

homeassistant/data_entry_flow.py

@@ -76,6 +76,9 @@ FLOW_NOT_COMPLETE_STEPS = {
 }
 
 STEP_ID_OPTIONAL_STEPS = {
+    FlowResultType.EXTERNAL_STEP,
+    FlowResultType.FORM,
+    FlowResultType.MENU,
     FlowResultType.SHOW_PROGRESS,
 }
 
@@ -575,25 +578,30 @@ class FlowHandler:
     def async_show_form(
         self,
         *,
-        step_id: str,
+        step_id: str | None = None,
         data_schema: vol.Schema | None = None,
         errors: dict[str, str] | None = None,
         description_placeholders: Mapping[str, str | None] | None = None,
         last_step: bool | None = None,
         preview: str | None = None,
     ) -> FlowResult:
-        """Return the definition of a form to gather user input."""
+        """Return the definition of a form to gather user input.
-        return FlowResult(
+
+        The step_id parameter is deprecated and will be removed in a future release.
+        """
+        flow_result = FlowResult(
             type=FlowResultType.FORM,
             flow_id=self.flow_id,
             handler=self.handler,
-            step_id=step_id,
             data_schema=data_schema,
             errors=errors,
             description_placeholders=description_placeholders,
             last_step=last_step,  # Display next or submit button in frontend
             preview=preview,  # Display preview component in frontend
         )
+        if step_id is not None:
+            flow_result["step_id"] = step_id
+        return flow_result
 
     @callback
     def async_create_entry(
@@ -636,19 +644,24 @@ class FlowHandler:
     def async_external_step(
         self,
         *,
-        step_id: str,
+        step_id: str | None = None,
         url: str,
         description_placeholders: Mapping[str, str] | None = None,
     ) -> FlowResult:
-        """Return the definition of an external step for the user to take."""
+        """Return the definition of an external step for the user to take.
-        return FlowResult(
+
+        The step_id parameter is deprecated and will be removed in a future release.
+        """
+        flow_result = FlowResult(
             type=FlowResultType.EXTERNAL_STEP,
             flow_id=self.flow_id,
             handler=self.handler,
-            step_id=step_id,
             url=url,
             description_placeholders=description_placeholders,
         )
+        if step_id is not None:
+            flow_result["step_id"] = step_id
+        return flow_result
 
     @callback
     def async_external_step_done(self, *, next_step_id: str) -> FlowResult:
@@ -669,7 +682,10 @@ class FlowHandler:
         description_placeholders: Mapping[str, str] | None = None,
         progress_task: asyncio.Task[Any] | None = None,
     ) -> FlowResult:
-        """Show a progress message to the user, without user input allowed."""
+        """Show a progress message to the user, without user input allowed.
+
+        The step_id parameter is deprecated and will be removed in a future release.
+        """
         if progress_task is None and not self.__no_progress_task_reported:
             self.__no_progress_task_reported = True
             cls = self.__class__
@@ -685,7 +701,7 @@ class FlowHandler:
                 report_issue,
             )
 
-        result = FlowResult(
+        flow_result = FlowResult(
             type=FlowResultType.SHOW_PROGRESS,
             flow_id=self.flow_id,
             handler=self.handler,
@@ -694,8 +710,8 @@ class FlowHandler:
             progress_task=progress_task,
         )
         if step_id is not None:
-            result["step_id"] = step_id
+            flow_result["step_id"] = step_id
-        return result
+        return flow_result
 
     @callback
     def async_show_progress_done(self, *, next_step_id: str) -> FlowResult:
@@ -711,23 +727,26 @@ class FlowHandler:
     def async_show_menu(
         self,
         *,
-        step_id: str,
+        step_id: str | None = None,
         menu_options: list[str] | dict[str, str],
         description_placeholders: Mapping[str, str] | None = None,
     ) -> FlowResult:
         """Show a navigation menu to the user.
 
         Options dict maps step_id => i18n label
+        The step_id parameter is deprecated and will be removed in a future release.
         """
-        return FlowResult(
+        flow_result = FlowResult(
             type=FlowResultType.MENU,
             flow_id=self.flow_id,
             handler=self.handler,
-            step_id=step_id,
             data_schema=vol.Schema({"next_step_id": vol.In(menu_options)}),
             menu_options=menu_options,
             description_placeholders=description_placeholders,
         )
+        if step_id is not None:
+            flow_result["step_id"] = step_id
+        return flow_result
 
     @callback
     def async_remove(self) -> None: