Merge branch 'master' into area-square-meters-docs

home-assistant · Dec 26, 2024 · 3a7ad5c · 3a7ad5c
2 parents 3123b71 + 979cd62
commit 3a7ad5c
Show file tree

Hide file tree

Showing 93 changed files with 3,914 additions and 188 deletions.
diff --git a/blog/2024-11-20-integration-quality-scale.md b/blog/2024-11-20-integration-quality-scale.md
@@ -0,0 +1,29 @@
+---
+author: Joost Lekkerkerker
+authorURL: https://github.com/joostlek
+authorImageURL: https://avatars.githubusercontent.com/u/7083755?v=4
+title: "Integration quality scale"
+---
+
+Since the original quality scale was introduced in 2020, Home Assistant changed quite a lot.
+Both in how integrations are developed and what features they can provide.
+The quality scale, however, has not been updated to reflect these changes.
+
+For the last couple of months, we have been working with the community on a new integration quality scale that fits the current state of Home Assistant.
+To give an overview of the changes:
+
+- The quality scale now has four scaled tiers: Bronze, Silver, Gold, and Platinum. The newly added Bronze tier is the new minimum requirement for new core integrations going forward. This does lower the bar for new integrations for a bit, but it does make it clear upfront what is expected from a core integration in this day and age.
+- A new non-scaled tier, legacy, has been added for integrations that are not configurable via the UI yet. This tier would indicate to the user that the integration might not meet their expectation compared to integrations configurable via the UI.
+- To allow the scale to grow with Home Assistant and to avoid another major rework in the future, we have designed a rulebook for the scale so it's known what needs to happen when a rule is added.
+- To show that the project has a commitment on keeping the scale up to date, we have created an architecture decision record (ADR) that describes the goal and the process of keeping the scale up to date.
+- The developer documentation now has [a brand new section](/docs/core/integration-quality-scale/) dedicated to the Integration Quality Scale. It includes the rules and the reasoning for every rule, and it provides examples that can be used to give an idea of how to implement it. There is also [a checklist](/docs/core/integration-quality-scale/checklist) that can be used for changing the scale of an integration.
+- Documentation now also plays a role in the quality of the integrations, since the user experience of an integration goes beyond code.
+- To track the progress of integration, we have added [a `quality_scale.yaml` file](https://github.com/home-assistant/core/blob/dev/homeassistant/components/airgradient/quality_scale.yaml) to the integration folder. This will contain a list of all the rules the integration is adhering to and notes of possible exemptions and the reasons behind them.
+
+With this in place, you might wonder what the next steps are.
+Because this is a major rework of the scale, we have decided to drop the scale of the current integrations.
+This means that those integrations have to create a PR to get their scale back to the level they think it should be.
+
+I would also like to motivate the community to help out with getting as many integrations to Bronze (or above) as possible.
+I also want to thank the community for their input in the quality scale and their effort in maintaining the integrations.
+Home Assistant would not be where it is today without the community ❤️.
diff --git a/blog/2024-11-21-unit-of-measurement-translations.md b/blog/2024-11-21-unit-of-measurement-translations.md
@@ -0,0 +1,23 @@
+---
+author: Abílio Costa
+authorURL: https://github.com/abmantis
+title: "Translating units of measurement"
+---
+
+Home Assistant 2024.12 will support the translation of custom units of measurement. Previously, those would have been hardcoded in their integrations.
+
+Just like for entity names, integrations just need to set the `translation_key` on the entity definition and provide the unit designation in the `strings.json` file (with the new `unit_of_measurement` key):
+
+```json
+{
+  "entity": {
+    "sensor": {
+      "subscribers_count": {
+        "unit_of_measurement": "subscribers"
+      },
+    }
+  }
+}
+```
+
+Check our [backend localization documentation](/docs/internationalization/core#unit-of-measurement-of-entities) for details.
diff --git a/blog/2024-11-26-camera-deprecations.md b/blog/2024-11-26-camera-deprecations.md
@@ -0,0 +1,17 @@
+---
+author: Robert Resch
+authorURL: https://github.com/edenhaus
+authorImageURL: https://avatars.githubusercontent.com/u/26537646?s=96&v=4
+title: "Camera API changes"
+---
+
+With Home Assistant `2024.11` we added WebRTC for most cameras. To add support for it we needed to refactor and improve the camera entity.
+Today we would like to announce that with the upcoming Home Assistant release `2024.12` the following methods are deprecated and will be removed with Home Assistant version `2025.6`:
+
+- The property `frontend_stream_type` will be removed. As of `2024.11` Home assistant will identify the frontend stream type by checking if the camera entity implements the native WebRTC methods ([#130932](https://github.com/home-assistant/core/pull/130932)). Card developers can use the new websocket command `camera/capabilities` to get the frontend stream types.
+
+- The method `async_handle_web_rtc_offer` will be removed. Please use `async_handle_async_webrtc_offer` and the async WebRTC signaling approach ([#131285](https://github.com/home-assistant/core/pull/131285)).
+
+- The method `async_register_rtsp_to_web_rtc_provider` has been deprecated. Please use `async_register_webrtc_provider`, which offers more flexibility and supports the async WebRTC signaling approach ([#131462](https://github.com/home-assistant/core/pull/131462)).
+
+More information about the replacements can be found in the [camera entity documentation](/docs/core/entity/camera).
diff --git a/blog/2024-11-28-dt-util-utc-to-timestamp-deprecation.md b/blog/2024-11-28-dt-util-utc-to-timestamp-deprecation.md
@@ -0,0 +1,11 @@
+---
+author: Erik Montnemery
+authorURL: https://github.com/emontnemery
+title: "Utility function homeassistant.util.dt.utc_to_timestamp is deprecated"
+---
+
+The utility function `homeassistant.util.dt.utc_to_timestamp` is deprecated and will be removed in Home Assistant Core 2026.1, custom integrations which call it should instead call the stdlib method `datetime.datetime.timestamp()`
+
+The reason for deprecation is that the stdlib method is just as fast as the utility function.
+
+More details can be found in the [core PR](https://github.com/home-assistant/core/pull/131787).
diff --git a/blog/2024-12-03-climate-horizontal-swing.md b/blog/2024-12-03-climate-horizontal-swing.md
@@ -0,0 +1,73 @@
+---
+author: G Johansson
+authorURL: https://github.com/gjohansson-ST
+authorImageURL: https://avatars.githubusercontent.com/u/62932417?v=4
+authorTwitter: GJohansson
+title: "Climate entity now supports independent horizontal swing"
+---
+
+As of Home Assistant Core 2024.12, we have implemented an independent property and method for controlling horizontal swing in `ClimateEntity`.
+
+Integrations that support completely independent control and state for vertical and horizontal swing can now use the previous `swing_mode` for vertical swing only and use the new `swing_horizontal_mode` for providing the horizontal swing state and control.
+
+Integrations that don't have independent control should still keep using the current `swing_mode` for both vertical and horizontal support.
+
+
+### Example
+
+Example requirements to implement `swing` and `swing_horizontal` in your climate entity.
+
+```python
+
+class MyClimateEntity(ClimateEntity):
+    """Implementation of my climate entity."""
+
+    @property
+    def supported_features(self) -> ClimateEntityFeature:
+        """Return the list of supported features."""
+        return ClimateEntityFeature.SWING_MODE | ClimateEntityFeature.SWING_HORIZONTAL_MODE
+
+    @property
+    def swing_mode(self) -> str | None:
+        """Return the swing setting.
+
+        Requires ClimateEntityFeature.SWING_MODE.
+        """
+        return self._attr_swing_mode
+
+    @property
+    def swing_modes(self) -> list[str] | None:
+        """Return the list of available swing modes.
+
+        Requires ClimateEntityFeature.SWING_MODE.
+        """
+        return self._attr_swing_modes
+
+    @property
+    def swing_horizontal_mode(self) -> str | None:
+        """Return the swing setting.
+
+        Requires ClimateEntityFeature.SWING_HORIZONTAL_MODE.
+        """
+        return self._attr_swing_horizontal_mode
+
+    @property
+    def swing_horizontal_modes(self) -> list[str] | None:
+        """Return the list of available swing modes.
+
+        Requires ClimateEntityFeature.SWING_HORIZONTAL_MODE.
+        """
+        return self._attr_swing_horizontal_modes
+
+    async def async_set_swing_mode(self, swing_mode: str) -> None:
+        """Set new target swing operation."""
+        await self.api.set_swing_mode(swing_mode)
+
+    async def async_set_swing_horizontal_mode(self, swing_horizontal_mode: str) -> None:
+        """Set new target horizontal swing operation."""
+        await self.api.set_swing_horizontal_mode(swing_horizontal_mode)
+
+```
+
+More details can be found in the [climate documentation](/docs/core/entity/climate#swing-modes).
+
diff --git a/blog/2024-12-08-new-vacuum-state-property.md b/blog/2024-12-08-new-vacuum-state-property.md
@@ -0,0 +1,33 @@
+---
+author: G Johansson
+authorURL: https://github.com/gjohansson-ST
+authorImageURL: https://avatars.githubusercontent.com/u/62932417?v=4
+authorTwitter: GJohansson
+title: "New vacuum state property"
+---
+
+As of Home Assistant Core 2025.1, the constants used to return state in `StateVacuumEntity` are deprecated and replaced by the `VacuumActivity` enum.
+
+Also with this change, integrations should set the `activity` property instead of directly setting the `state` property.
+
+There is a one-year deprecation period, and the constants will stop working from 2026.1 to ensure all custom integration authors have time to adjust.
+
+### Example
+
+```python
+
+from homeassistant.components.vacuum import VacuumActivity
+
+class MyVacuumCleaner(StateVacuumEntity):
+    """My vacuum cleaner."""
+
+    @property
+    def activity(self) -> VacuumActivity | None:
+        """Return the state of the vacuum."""
+        if self.device.is_cleaning():
+            return VacuumActivity.CLEANING
+        return VacuumActivity.DOCKED
+
+```
+
+More details can be found in the [vacuum documentation](/docs/core/entity/vacuum#states).
diff --git a/blog/2024-12-13-water-heater-entity-description.md b/blog/2024-12-13-water-heater-entity-description.md
@@ -0,0 +1,11 @@
+---
+author: L Boué
+authorURL: https://github.com/lboue
+authorTwitter: lboue
+title: "Changed name of WaterHeaterEntityDescription"
+---
+
+A naming error of the entity description was found in the Water Heater integration, and we have now renamed `WaterHeaterEntityEntityDescription` to `WaterHeaterEntityDescription` in the 2025.1 release.
+The old `WaterHeaterEntityEntityDescription` is deprecated, due for removal in 2026.1, and developpers are advised to use the new `WaterHeaterEntityDescription` instead.
+
+See details in the core PR: [#132888](https://github.com/home-assistant/core/pull/132888).
diff --git a/blog/2024-12-14-kelvin-preferred-color-temperature-unit.md b/blog/2024-12-14-kelvin-preferred-color-temperature-unit.md
@@ -0,0 +1,105 @@
+---
+author: epenet
+authorURL: https://github.com/epenet
+title: "Use Kelvin as the preferred color temperature unit"
+---
+
+### Summary of changes
+
+In October 2022, Home Assistant migrated the preferred color temperature unit from mired to kelvin.
+
+It is now time to add deprecation warnings for the corresponding attributes, constants and properties:
+* Deprecate state and capability attributes `ATTR_COLOR_TEMP`, `ATTR_MIN_MIREDS` and `ATTR_MAX_MIREDS`
+* Deprecate constants `ATTR_KELVIN` and `ATTR_COLOR_TEMP` from the `light.turn_on` service call
+* Deprecate properties `LightEntity.color_temp`, `LightEntity.min_mireds` and `LightEntity.max_mireds`
+* Deprecate corresponding attributes `LightEntity._attr_color_temp`, `LightEntity._attr_min_mired` and `LightEntity._attr_max_mired`
+
+### Examples
+
+#### Custom minimum/maximum color temperature
+
+```python
+class MyLight(LightEntity):
+    """Representation of a light."""
+
+    # Old
+    # _attr_min_mireds = 200 # 5000K
+    # _attr_max_mireds = 400 # 2500K
+
+    # New
+    _attr_min_color_temp_kelvin = 2500 # 400 mireds
+    _attr_max_color_temp_kelvin = 5000 # 200 mireds
+```
+
+#### Default minimum/maximum color temperature
+
+```python
+from homeassistant.components.light import DEFAULT_MAX_KELVIN, DEFAULT_MIN_KELVIN
+
+class MyLight(LightEntity):
+    """Representation of a light."""
+
+    # Old did not need to have _attr_min_mireds / _attr_max_mireds set
+    # New needs to set the default explicitly
+    _attr_min_color_temp_kelvin = DEFAULT_MIN_KELVIN
+    _attr_max_color_temp_kelvin = DEFAULT_MAX_KELVIN
+```
+
+#### Dynamic minimum/maximum color temperature
+
+```python
+from homeassistant.util import color as color_util
+
+class MyLight(LightEntity):
+    """Representation of a light."""
+
+    # Old
+    # def min_mireds(self) -> int:
+    #     """Return the coldest color_temp that this light supports."""
+    #     return device.coldest_temperature
+    #
+    # def max_mireds(self) -> int:
+    #     """Return the warmest color_temp that this light supports."""
+    #     return device.warmest_temperature
+
+    # New
+    def min_color_temp_kelvin(self) -> int:
+        """Return the warmest color_temp that this light supports."""
+        return color_util.color_temperature_mired_to_kelvin(device.warmest_temperature)
+
+    def max_color_temp_kelvin(self) -> int:
+        """Return the coldest color_temp that this light supports."""
+        return color_util.color_temperature_mired_to_kelvin(device.coldest_temperature)
+```
+
+#### Service call
+
+```python
+from homeassistant.components.light import ATTR_COLOR_TEMP_KELVIN
+from homeassistant.util import color as color_util
+
+class MyLight(LightEntity):
+    """Representation of a light."""
+    def turn_on(self, **kwargs: Any) -> None:
+        """Turn on the light."""
+        # Old
+        # if ATTR_COLOR_TEMP in kwargs:
+        #     color_temp_mired = kwargs[ATTR_COLOR_TEMP]
+        #     color_temp_kelvin = color_util.color_temperature_mired_to_kelvin(color_temp_mired)
+
+        # Old
+        # if ATTR_KELVIN in kwargs:
+        #     color_temp_kelvin = kwargs[ATTR_KELVIN]
+        #     color_temp_mired = color_util.color_temperature_kelvin_to_mired(color_temp_kelvin)
+
+        # New
+        if ATTR_COLOR_TEMP_KELVIN in kwargs:
+            color_temp_kelvin = kwargs[ATTR_COLOR_TEMP_KELVIN]
+            color_temp_mired = color_util.color_temperature_kelvin_to_mired(color_temp_kelvin)
+```
+
+### Background information
+
+* [Community discussion about Kelvin temperature](https://community.home-assistant.io/t/wth-is-light-temperature-not-in-kelvin/467449/6)
+* [Core PR #79591: Migration to Kelvin](https://github.com/home-assistant/core/pull/79591)
+* [Architecture discussion #564](https://github.com/home-assistant/architecture/discussions/564)
diff --git a/blog/2024-12-21-moving-to-pydantic-v2.md b/blog/2024-12-21-moving-to-pydantic-v2.md
@@ -0,0 +1,14 @@
+---
+author: Joost Lekkerkerker
+authorURL: https://github.com/joostlek
+authorImageURL: https://avatars.githubusercontent.com/u/7083755?v=4
+title: "Moving to Pydantic v2"
+---
+
+Pydantic is a widely used library in Python for data validation. On June 30, 2023, Pydantic v2 was released, introducing significant changes that are not backward compatible with Pydantic v1.
+
+Starting with Home Assistant Core 2025.1, Pydantic v2 will replace v1. If your custom integration uses Pydantic, it must be updated to support Pydantic v2 to keep working in the upcoming release.
+
+Over the past year, our community has worked hard to ensure that the libraries used by Home Assistant Core are compatible with both Pydantic v1 and v2. This dual compatibility has helped make our transition to Pydantic v2 as smooth as possible.
+
+For a quick migration, you can use the Pydantic v1 shims included in Pydantic v2. Detailed information about using these shims in a v1/v2 environment can be found in the [Pydantic migration guide](https://docs.pydantic.dev/latest/migration/#using-pydantic-v1-features-in-a-v1v2-environment).
diff --git a/docs/add-ons/configuration.md b/docs/add-ons/configuration.md
@@ -157,7 +157,7 @@ Avoid using `config.yaml` as filename in your add-on for anything other than the
 | `docker_api` | bool | `false` | Allow read-only access to the Docker API for the add-on. Works only for not protected add-ons.
 | `privileged` | list | | Privilege for access to hardware/system. Available access: `BPF`, `DAC_READ_SEARCH`, `IPC_LOCK`, `NET_ADMIN`, `NET_RAW`, `PERFMON`, `SYS_ADMIN`, `SYS_MODULE`, `SYS_NICE`, `SYS_PTRACE`, `SYS_RAWIO`, `SYS_RESOURCE` or `SYS_TIME`.
 | `full_access` | bool | `false` | Give full access to hardware like the privileged mode in Docker. Works only for not protected add-ons. Consider using other add-on options instead of this, like `devices`. If you enable this option, don't add `devices`, `uart`, `usb` or `gpio` as this is not needed.
-| `apparmor` | bool/string | `false` | Enable or disable AppArmor support. If it is enabled, you can also use custom profiles with the name of the profile.
+| `apparmor` | bool/string | `true` | Enable or disable AppArmor support. If it is enabled, you can also use custom profiles with the name of the profile.
 | `map` | list | | List of Home Assistant directory types to bind mount into your container. Possible values: `homeassistant_config`, `addon_config`, `ssl`, `addons`, `backup`, `share`, `media`, `all_addon_configs`, and `data`. Defaults to read-only, which you can change by adding the property `read_only: false`. By default, all paths map to `/<type-name>` inside the addon container, but an optional `path` property can also be supplied to configure the path (Example: `path: /custom/config/path`). If used, the path must not be empty, unique from any other path defined for the addon, and not the root path. Note that the `data` directory is always mapped and writable, but the `path` property can be set using the same conventions.
 | `environment` | dict | | A dictionary of environment variables to run the add-on with.
 | `audio` | bool | `false` | Mark this add-on to use the internal audio system. We map a working PulseAudio setup into the container. If your application does not support PulseAudio, you may need to install: Alpine Linux `alsa-plugins-pulse` or Debian/Ubuntu `libasound2-plugins`.

diff --git a/docs/api_lib_auth.md b/docs/api_lib_auth.md
@@ -34,13 +34,8 @@ class Auth:
 
     async def request(self, method: str, path: str, **kwargs) -> ClientResponse:
         """Make a request."""
-        headers = kwargs.get("headers")
-
-        if headers is None:
-            headers = {}
-        else:
+        if headers := kwargs.pop("headers", {}):
             headers = dict(headers)
-
         headers["authorization"] = self.access_token
 
         return await self.websession.request(
@@ -86,13 +81,8 @@ class Auth:
 
     def request(self, method: str, path: str, **kwargs) -> requests.Response:
         """Make a request."""
-        headers = kwargs.get("headers")
-
-        if headers is None:
-            headers = {}
-        else:
+        if headers := kwargs.pop("headers", {}):
             headers = dict(headers)
-
         headers["authorization"] = self.access_token
 
         return requests.request(
@@ -142,11 +132,7 @@ class AbstractAuth(ABC):
 
     async def request(self, method, url, **kwargs) -> ClientResponse:
         """Make a request."""
-        headers = kwargs.get("headers")
-
-        if headers is None:
-            headers = {}
-        else:
+        if headers := kwargs.pop("headers", {}):
             headers = dict(headers)
 
         access_token = await self.async_get_access_token()

diff --git a/docs/config_entries_config_flow_handler.md b/docs/config_entries_config_flow_handler.md
@@ -308,7 +308,7 @@ Ensuring that the `unique_id` is unchanged should be done using `await self.asyn
 
 ## Reauthentication
 
-Gracefully handling authentication errors such as invalid, expired, or revoked tokens is needed to advance on the [Integration Quality Scale](integration_quality_scale_index.md). This example of how to add reauth to the OAuth flow created by `script.scaffold` following the pattern in [Building a Python library](api_lib_auth.md#oauth2).
+Gracefully handling authentication errors such as invalid, expired, or revoked tokens is needed to advance on the [Integration Quality Scale](core/integration-quality-scale). This example of how to add reauth to the OAuth flow created by `script.scaffold` following the pattern in [Building a Python library](api_lib_auth.md#oauth2).
 If you are looking for how to trigger the reauthentication flow, see [handling expired credentials](integration_setup_failures.md#handling-expired-credentials).
 
 This example catches an authentication exception in config entry setup in `__init__.py` and instructs the user to visit the integrations page in order to reconfigure the integration.