From 252ce2c95b68c09d7abe1fa6b9a27cef9d7eeade Mon Sep 17 00:00:00 2001 From: Erik Montnemery Date: Wed, 18 Sep 2024 18:19:13 +0200 Subject: [PATCH] Improve FlowManager.async_finish_flow docstring (#126178) * Improve FlowManager.async_finish_flow docstring * Fix typos --- homeassistant/auth/__init__.py | 6 +++++- homeassistant/components/auth/mfa_setup_flow.py | 6 +++++- homeassistant/components/repairs/issue_handler.py | 6 +++++- homeassistant/config_entries.py | 9 ++++++++- homeassistant/data_entry_flow.py | 6 +++++- 5 files changed, 28 insertions(+), 5 deletions(-) diff --git a/homeassistant/auth/__init__.py b/homeassistant/auth/__init__.py index b74fd587fab..19045406a15 100644 --- a/homeassistant/auth/__init__.py +++ b/homeassistant/auth/__init__.py @@ -127,7 +127,11 @@ class AuthManagerFlowManager( flow: data_entry_flow.FlowHandler[AuthFlowResult, tuple[str, str]], result: AuthFlowResult, ) -> AuthFlowResult: - """Return a user as result of login flow.""" + """Return a user as result of login flow. + + This method is called when a flow step returns FlowResultType.ABORT or + FlowResultType.CREATE_ENTRY. + """ flow = cast(LoginFlow, flow) if result["type"] != data_entry_flow.FlowResultType.CREATE_ENTRY: diff --git a/homeassistant/components/auth/mfa_setup_flow.py b/homeassistant/components/auth/mfa_setup_flow.py index 8ae55396fa9..84f66440a75 100644 --- a/homeassistant/components/auth/mfa_setup_flow.py +++ b/homeassistant/components/auth/mfa_setup_flow.py @@ -57,7 +57,11 @@ class MfaFlowManager(data_entry_flow.FlowManager): async def async_finish_flow( self, flow: data_entry_flow.FlowHandler, result: data_entry_flow.FlowResult ) -> data_entry_flow.FlowResult: - """Complete an mfs setup flow.""" + """Complete an mfa setup flow. + + This method is called when a flow step returns FlowResultType.ABORT or + FlowResultType.CREATE_ENTRY. + """ _LOGGER.debug("flow_result: %s", result) return result diff --git a/homeassistant/components/repairs/issue_handler.py b/homeassistant/components/repairs/issue_handler.py index 38dcea1668d..b0b3f82a5d6 100644 --- a/homeassistant/components/repairs/issue_handler.py +++ b/homeassistant/components/repairs/issue_handler.py @@ -82,7 +82,11 @@ class RepairsFlowManager(data_entry_flow.FlowManager): async def async_finish_flow( self, flow: data_entry_flow.FlowHandler, result: data_entry_flow.FlowResult ) -> data_entry_flow.FlowResult: - """Complete a fix flow.""" + """Complete a fix flow. + + This method is called when a flow step returns FlowResultType.ABORT or + FlowResultType.CREATE_ENTRY. + """ if result.get("type") != data_entry_flow.FlowResultType.ABORT: ir.async_delete_issue(self.hass, flow.handler, flow.init_data["issue_id"]) if "result" not in result: diff --git a/homeassistant/config_entries.py b/homeassistant/config_entries.py index 797fcc5f345..395dcaf79a3 100644 --- a/homeassistant/config_entries.py +++ b/homeassistant/config_entries.py @@ -1338,7 +1338,11 @@ class ConfigEntriesFlowManager(data_entry_flow.FlowManager[ConfigFlowResult]): flow: data_entry_flow.FlowHandler[ConfigFlowResult], result: ConfigFlowResult, ) -> ConfigFlowResult: - """Finish a config flow and add an entry.""" + """Finish a config flow and add an entry. + + This method is called when a flow step returns FlowResultType.ABORT or + FlowResultType.CREATE_ENTRY. + """ flow = cast(ConfigFlow, flow) # Mark the step as done. @@ -2660,6 +2664,9 @@ class OptionsFlowManager(data_entry_flow.FlowManager[ConfigFlowResult]): ) -> ConfigFlowResult: """Finish an options flow and update options for configuration entry. + This method is called when a flow step returns FlowResultType.ABORT or + FlowResultType.CREATE_ENTRY. + Flow.handler and entry_id is the same thing to map flow with entry. """ flow = cast(OptionsFlow, flow) diff --git a/homeassistant/data_entry_flow.py b/homeassistant/data_entry_flow.py index b8e8f269b82..7ecbe5508c6 100644 --- a/homeassistant/data_entry_flow.py +++ b/homeassistant/data_entry_flow.py @@ -226,7 +226,11 @@ class FlowManager(abc.ABC, Generic[_FlowResultT, _HandlerT]): async def async_finish_flow( self, flow: FlowHandler[_FlowResultT, _HandlerT], result: _FlowResultT ) -> _FlowResultT: - """Finish a data entry flow.""" + """Finish a data entry flow. + + This method is called when a flow step returns FlowResultType.ABORT or + FlowResultType.CREATE_ENTRY. + """ async def async_post_init( self, flow: FlowHandler[_FlowResultT, _HandlerT], result: _FlowResultT