Add `single_instance_only` manifest option

[jpbede]

Proposed change

Add the possibility to signal to the frontend if we support multiple config entries or not. This way we can remove the button on the integration page and show a message to the user.

I think you could also use this to reduce the copied code if an integration only allows one entry, and move the check to the base config flow.

~Frontend PR follows.~

Type of change

• [ ] Dependency upgrade
• [ ] Bugfix (non-breaking change which fixes an issue)
• [ ] New integration (thank you!)
• [x] New feature (which adds functionality to an existing integration)
• [ ] Deprecation (breaking change to happen in the future)
• [ ] Breaking change (fix/feature causing existing functionality to break)
• [ ] Code quality improvements to existing code or addition of tests

Additional information

• This PR fixes or closes issue: fixes #
• This PR is related to issue:
• Link to documentation pull request:
• Link to the frontend pull request: https://github.com/home-assistant/frontend/pull/19648
• Link to the developer documentation PR: https://github.com/home-assistant/developers.home-assistant/pull/2074

Checklist

• [x] The code change is tested and works locally.
• [x] Local tests pass. Your PR cannot be merged unless tests pass
• [x] There is no commented out code in this PR.
• [x] I have followed the development checklist
• [x] I have followed the perfect PR recommendations
• [x] The code has been formatted using Ruff (ruff format homeassistant tests)
• [x] Tests have been added to verify that the new code works.

If user exposed functionality or configuration variables are added/changed:

• [ ] Documentation added/updated for www.home-assistant.io

If the code communicates with devices, web services, or third-party tools:

• [ ] The manifest file has all fields filled out correctly.
  Updated and included derived files by running: python3 -m script.hassfest.
• [ ] New or updated dependencies have been added to requirements_all.txt.
  Updated by running python3 -m script.gen_requirements_all.
• [ ] For the updated dependencies - a link to the changelog, or at minimum a diff between library versions is added to the PR description.
• [ ] Untested files have been added to .coveragerc.

To help with the load of incoming pull requests:

• [x] I have reviewed two other open pull requests in this repository.

[home-assistant[bot]]

Hey there @home-assistant/core, mind taking a look at this pull request as it has been labeled with an integration (config) you are listed as a code owner for? Thanks!

Code owner commands

Code owners of config can trigger bot actions by commenting:

• @home-assistant close Closes the pull request.
• @home-assistant rename Awesome new title Renames the pull request.
• @home-assistant reopen Reopen the pull request.
• @home-assistant unassign config Removes the current integration label and assignees on the pull request, add the integration domain after the command.
• @home-assistant add-label needs-more-information Add a label (needs-more-information, problem in dependency, problem in custom component) to the pull request.
• @home-assistant remove-label needs-more-information Remove a label (needs-more-information, problem in dependency, problem in custom component) on the pull request.

[bdraco]

~~Do we need a new API for this? Can we add it to instead?~~

Nevermind. I see you need it if there are no config entries as well

[home-assistant[bot]]

Please take a look at the requested changes, and use the Ready for review button when you are done, thanks :+1:

Learn more about our pull request process.

[MartinHjelmare]

The frontend team will need to approve its PR before we can go ahead also.

[jpbede]

I think it's not great that we still need to abort the flow if there's already an existing entry. So there's now two ways of saying that the integration only supports a single entry.

Yeah indeed, my plan was to add the abort to the base config flow in a followup PR, so we don't need to abort the flow in the extended config flows.

Edit: or would it be better to add it to this PR?

[joostlek]

Wouldn't it be better to move the "abort popup" to the frontend? What's the value of starting a flow when we are going to immediately abort it?

[bramkragten]

Can't we add this to the manifest?

[jpbede]

Can't we add this to the manifest?

Would be possible, yes.

Edit: This way, we can use it in the add integration dialog without any problems and we would no longer have to abort the config flow

[codyc1515]

Can't we add this to the manifest?

This was my immediate thought. It's already getting difficult to accurately display some of this data in the UI given there is so many entrypoints. A single key in the manifest would be a very simple addition.

[jpbede]

Moved this to the manifest now

[codyc1515]

Developer docs will need updating too. Do we know today which integrations only support a single entry?

[jpbede]

Do we know today which integrations only support a single entry?

Yes, you could search the config_flow.py for self.async_abort(reason="single_instance_allowed") and some have already_configured.

[emontnemery]

With the new flag, integrations should no longer need to worry about protecting against multiple config entries being created, this means the PR needs to be updated to also:

• Prevent initializing config flows for integrations which already have an entry
• Make sure any in progress flow is aborted when a config entry is created
• Make sure it's impossible to accidentally create an additional config entry

[gjohansson-ST]

Is it only me who doesn't like the "name" of this new key? On the other hand I don't have much of a suggestion either.

[emontnemery]

I will implement the changes suggested by Martin.