Changes in component config processing and error handling​

The way component YAML configuration is processed has been changed. Now, it is possible to raise if an error occurs. Some custom integrations might break if they are using config.async_process_component_config. Instead, they can use config.async_process_component_and_handle_errors now. This new method supports raising when an error occurs during config processing. From now on, failures will no longer be notified as a persistent message, so integrations need to implement error handling to notify users in case of a failure. Notifications are still added during setup in case of a config issue.

async def async_process_component_and_handle_errors(
    hass: HomeAssistant,
    config: ConfigType,
    integration: Integration,
    raise_on_failure: bool = False,
) -> ConfigType | None:
...

During a reload integrations can use the helpers.reload.async_integration_yaml_config. This helper now also has the ability to raise in case of a failure.

async def async_integration_yaml_config(
    hass: HomeAssistant, integration_name: str, *, raise_on_failure: bool = False
) -> ConfigType | None:
...

Translation support for Exceptions on config validation​

A new ConfigValidationError exception class is introduced. It will be raised in case an error occurs during config error handling and raise_on_failure is set to True. It can be re-raised to a ServiceValidationError in case this error is raised during the execution of a service call and a stack trace is not warranted. Translation keys are added to allow localization of the error messages.

Background​

• Background discussion.
• Implementation Core PR #102410.

Add-ons can now have a public folder for config or data files, which users can see and modify, but it is still backed up with the add-on.

Many add-ons ask users to provide files as part of the addon configuration. Or generate files that they want users to be able to see and potentially modify. They typically handle this by including config and/or share in the list of folders to map.

The problem with this is twofold:

1. Nothing in config or share is backed up with the add-on. So, backups of that add-on do not include all the necessary files to run it after restore.
2. Add-ons that map config have far more access than they should since config includes all secrets and credentials used in your Home Assistant integrations.

There is now a better solution for add-on developers. Add-ons can include addon_config in the list of folders to map. Then, the supervisor will create a folder for that add-on at /addon_configs/<your addon slug> and map that to /config within the add-on container. If your addon needs to be able to create and modify files in this folder in addition to collecting files from users, use addon_config:rw instead.

To read more about this feature and some of the use cases, see Add-on advanced options.

Backwards compatibility with /config​

You may notice that the new public config folder is mapped to /config. Which is previously where Home Assistant's config folder was mapped if you added config to the map field.

This option is intended to replace the need for add-ons to map Home Assistant's config into their container. As such, an add-on cannot include both config and addon_config in the map field.

Going forward, if you do need to make Home Assistant's config available to your add-on, you should list homeassistant_config as a folder in the map field. Then Home Assistant's config folder will be mapped to /homeassistant within the container.

New addon_configs folder​

Some add-ons need access to all these add-on-specific config folders. For example:

1. Samba
2. SSH
3. Studio Code Server

Essentially, these add-ons provide alternative means of editing the configuration files of Home Assistant and its add-ons. Add-ons like these should add all_addon_configs:rw to the list of folders in the map field. This will map the entire addon configs folder within the container at /addon_configs.

Selectors has been expanded and now also includes a CountrySelector.

Using this in config flows will allow frontend to automatically translate the country codes into the proper country names.

Example:

vol.Schema(
    {
        vol.Optional(CONF_COUNTRY): CountrySelector(
            CountrySelectorConfig(
                countries=["DE", "US"],
            )
        ),
    }
)

The following utilities were deprecated in Home Assistant 2022.10) and have now been removed as of 2023.11:

• homeassistant/util/distance
• homeassistant/util/pressure
• homeassistant/util/speed
• homeassistant/util/temperature
• homeassistant/util/volume

Please use the corresponding static classes from homeassistant/util/unit_conversion:

• DistanceConverter
• PressureConverter
• SpeedConverter
• TemperatureConverter
• VolumeConverter

The deprecated functions were already unused within the built-in Home Assistant integrations, and community integrations using them should have seen warnings for the past 12 months. Attempting to import the original utilities will now result in an error.

📢 Exciting news for Hacktoberfest 2023 participants! We are participating! 🎉

It is not just our 10th anniversary, but also the 10th year of Hacktoberfest! Congratulations! 🎂

Hacktoberfest is a worldwide, month-long celebration of open source. An event open to everyone. Whether you’re a developer, student learning to code, documenter, or designer, you can help drive the growth of open source projects, like Home Assistant. All backgrounds and skill levels are encouraged to complete the Hacktoberfest challenge. And of course, we are happy to help you get your pull requests in.

Just like all other years, Home Assistant participates in Hacktoberfest. All of our repositories have joined, no matter if you want to make a change to the frontend, core, or even our documentation. The issue trackers on these repositories give a good overview of what is possible to contribute to.

But, I’m not a developer?!​

If you are not a developer, new to git, GitHub, or open source in general, documentation can be a great way to get started. A relatively easy way to contribute is by reviewing the documentation of integrations you use or are familiar with. Check if everything is still up to date and is free of spelling/grammar mistakes.

Every single documentation page on our website has a “Edit” button, at the buttom of the page. Using that button, you can change the text on that page and provide a suggestion for improvement.

On our Community forum, there is a good step-by-step guide on how this works: Editing the Documentation and Creating a Pull Request on GitHub.

So, what are you waiting for? Sign-up on the Hacktoberfest website and start hacking! If you have any questions, please, drop by our Discord chat server. We have dedicated developer channels and are happy to assist you.

Happy Hacktoberfest 🎉

The way in which state attributes are excluded from recording has changed

The recorder platforms have been replaced with two new attributes which can be set in classes derived from Entity:

• _entity_component_unrecorded_attributes: frozenset[str] - This should be set by base component entity classes, e.g. LightEntity
• _unrecorded_attributes: frozenset[str] - This should be set by derived platform classes, e.g. HueLight to exclude additional, integration specific, attributes from recording.

More details can be found in the entity documentation.

Background for the change is in architecture discussion #964.

The websocket command entity/source has been greatly simplified:

• It's no longer possible to get information for a single entity
• Only the domain of the entities is included in the response, custom_component, config_entry and source are no longer present.

New response example​

{
  "light.entity_1": {
    "domain": "template",
  },
  "switch.entity_2": {
    "domain": "shelly",
  },
}

Old response example​

{
  "light.entity_1": {
    "custom_component": false,
    "domain": "template",
    "source": "platform_config",
  },
  "switch.entity_2": {
    "custom_component": false,
    "config_entry": "<config_entry_id>",
    "domain": "shelly",
    "source": "config_entry",
  },
}

The change was introduced in core PR#99439

In the Home Assistant Core 2023.9 release, we introduced 3 new methods to the hass object to allow entity state formatting with localization support for custom cards:

• hass.formatEntityState
• hass.formatEntityAttributeValue
• hass.formatEntityAttributeName

Example:

hass.formatEntityState(hass.states["cover.living_room_shutter"]); 
// It will return "Open" if the user language is English.
// It will return "Ouvert" if the user language is French.

For more details, refer to the entity state formatting documentation.

The signature of HomeAssistant.__init__ has been changed from no arguments to require the configuration directory as a string to be passed to it. Scripts, tests etc. outside of the HomeAssistant core repo which create HomeAssistant objects will need to be updated.

The change was introduced in core PR#98442

If backwards compatibility is important, this is a way to achieve it:

    try:
        hass = HomeAssistant()  # pylint: disable=no-value-for-parameter
    except TypeError:
        hass = HomeAssistant(config_dir)  # pylint: disable=too-many-function-args

Numerical sensors are no longer allowed to set their state to Not a Number or to positive or negative infinity.

The change was introduce in core PR#98110

For more details, refer to the sensor documentation.