Config Entry methods in __init__ should succeed or raise

[gjohansson-ST]

Background

All the integrations Config entry methods in __init__.py returns a bool (True for success, False for something else).

This is legacy and originates from when an integration logged an issue/exception (swallowed it) and returned a bool depending on the outcome to drive the setup/unload further.

In the meantime the concept of ConfigEntry* exceptions was developed which today supports translations and feedback to the frontend to guide the user what happened and what options there are.

Proposal

Deprecate the returning of a boolean, either the method succeeds (None) or it raises one of the ConfigEntry* exceptions.

Most (my spy tells me there is 3 core integrations returning False within the setup method) integrations already has this behavior in place and just has a return True at the end as the typing currently requires it.

Methods considered to change:

• async_setup_entry()
• async_unload_entry()
• async_migrate_entry()

Post deprecation:

class ComponentProtocol(Protocol):
    """Define the format of an integration."""

    async def async_setup_entry(
        self, hass: HomeAssistant, config_entry: ConfigEntry
    ) -> None:
        """Set up a config entry."""

    async def async_unload_entry(
        self, hass: HomeAssistant, config_entry: ConfigEntry
    ) -> None:
        """Unload a config entry."""

    async def async_migrate_entry(
        self, hass: HomeAssistant, config_entry: ConfigEntry
    ) -> None:

Alternatives

This pattern has been there since config entries was invented and lots of custom components use it that might not get updated timely enough.
Deprecate this pattern for core integrations and allow custom to continue using it infinite. We can translate return False to ConfigEntryError with a generic message centrally.
Then custom components can opt-in as they see the benefits.

[Markus98]

This proposal was discussed in the core architecture meeting and it has been approved with the condition that we implement it with backwards compatibility handling like the "Alternatives" section describes.

We will deprecate the pattern for core integrations, but for custom integrations, we will indefinitely support a fallback which translates return False to a ConfigEntryError with a generic message.