From dc72abb96f0248f8c025610f352f649f99d2e3fb Mon Sep 17 00:00:00 2001 From: G Johansson Date: Sat, 22 Jun 2024 19:39:41 +0200 Subject: [PATCH] Use MATCH_ALL constant for recorder state attributes exclusion (#2229) Co-authored-by: Franck Nijhof --- ...ate-attributes-from-recording-match-all.md | 25 +++++++++++++++++++ docs/core/entity.md | 4 +++ 2 files changed, 29 insertions(+) create mode 100644 blog/2024-06-22-excluding-state-attributes-from-recording-match-all.md diff --git a/blog/2024-06-22-excluding-state-attributes-from-recording-match-all.md b/blog/2024-06-22-excluding-state-attributes-from-recording-match-all.md new file mode 100644 index 00000000..caac0be2 --- /dev/null +++ b/blog/2024-06-22-excluding-state-attributes-from-recording-match-all.md @@ -0,0 +1,25 @@ +--- +author: G Johansson +authorURL: https://github.com/gjohansson-ST +title: "Excluding all state attributes from recording using MATCH_ALL" +--- + +The way how state attributes are excluded from the recording was previously changed in September 2023. + +The previous implementation was limited as there was no way to handle dynamic attributes or any easy way to simply exclude all attributes instead of listing them individually. + +It is now possible within an integration to tell recording to not record any attribute by using the `MATCH_ALL` constant, which will automatically remove all attributes from recording except `device_class`, `state_class`, `unit_of_measurement`, and `friendly_name.` + +```python +from homeassistant.const import MATCH_ALL + +class ExampleEntity(Entity): + """Implementation of an entity.""" + + _unrecorded_attributes = frozenset({MATCH_ALL}) + +``` + +More details can be found in the [entity documentation](/docs/core/entity#excluding-state-attributes-from-recorder-history). + +Background for the original change is in [architecture discussion #964](https://github.com/home-assistant/architecture/discussions/964). diff --git a/docs/core/entity.md b/docs/core/entity.md index 0879da1a..d486edcb 100644 --- a/docs/core/entity.md +++ b/docs/core/entity.md @@ -461,6 +461,10 @@ State attributes which are not suitable for state history recording should be ex - `_entity_component_unrecorded_attributes: frozenset[str]` may be set in a base component class, e.g. in `light.LightEntity` - `_unrecorded_attributes: frozenset[str]` may be set in an integration's platform e.g. in an entity class defined in platform `hue.light`. +The `MATCH_ALL` constant can be used to exclude all attributes instead of typing them separately. This can be useful for integrations providing unknown attributes or when you simply want to exclude all without typing them separately. + +Using the `MATCH_ALL` constant does not stop recording for `device_class`, `state_class`, `unit_of_measurement`, and `friendly_name` as they might also serve other purposes and, therefore, should not be excluded from recording. + Examples of platform state attributes which are exluded from recording include the `entity_picture` attribute of `image` entities which will not be valid after some time, the `preset_modes` attribute of `fan` entities which is not likely to change. Examples of integration specific state attributes which are excluded from recording include `description` and `location` state attributes in platform `trafikverket.camera` which do not change.