Skip to content
New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Clarify state attributes rules for entity #2437

Open
wants to merge 3 commits into
base: master
Choose a base branch
from
Open

Clarify state attributes rules for entity #2437

Changes from all commits
Commits
Show all changes
3 commits
Select commit Hold shift + click to select a range
ec175df
Clarify state attributes rules for entity
gjohansson-ST Nov 3, 2024
ee15f47
Some remarks
gjohansson-ST Nov 9, 2024
eabb8aa
Fix comment
gjohansson-ST Nov 9, 2024
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
11 changes: 11 additions & 0 deletions docs/core/entity.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -119,6 +119,17 @@ The following properties are also available on entities. However, they are for a
| state_attributes | <code>dict &#124; None</code> | `None` | State attributes of a base domain. This property is implemented by the domain base entity and should not be implemented by integrations.
| unit_of_measurement | <code>str &#124; None</code> | The unit of measurement that the entity's state is expressed in. In most cases, for example for the `number` and `sensor` domains, this is implemented by the domain base entity and should not be implemented by integrations.

## State attributes

Entities can provide additional state attributes besides the built-in ones, to provide further details to its state.
This should be done by providing a dictionary with keys and values to the `extra_state_attributes` property.

Providing state attributes comes with the following rules:

- If an attribute is expected, it should be in the dictionary. Attributes should not "come and go".
Comment on lines +122 to +129
Copy link
Member

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Should we also indicate our rules for what belongs in state attributes and what should be separate entities and what should be action calls?

Copy link
Member Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

I think that would probably be good although do we really have clear rules?
I think we could do that in a follow-up in that case.

Copy link
Member

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Frenck once mentioned this in the members channel

Some helpful guidance with that, that I apply (for myself)

  • Would someone extract it using a template into an other (binary) sensor -> Not an attribute
  • It is essential to automation on? Can it be standalone as its own entity? -> Not an attribute
  • It is static, e.g., from configuration; doesn't belong in the state machine -> Not an attribute
  • Do we want to track long term stats of the value? -> Not an attribute

Additionally:

  • Does is have historical value? If not, exlude it from being recorded.

Copy link
Member Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

I think that makes sense but I'm not sure we can classify it as rules?
Maybe as "guidelines"?

Copy link
Member

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Oh right. I think that if we are going to talk about state attributes, that we also explain that we are picky in what we want using these guidelines :)

- If an attribute is expected, but it's not providing a value right now, its value should be `None` and remain in the dictionary.
Copy link
Member

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

I think the first 2 rules are quite similar. I also think we should explain what happens when for example the entity is unavailable. What should we do then?

Copy link
Member Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

We could perhaps combine the first two as they talk about the same thing.
I'm not sure what you mean by unavailable? Should there be any special consideration for it?

Copy link
Member

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

If an entity is unavailable, does it still read the extra state attributes property when writing state? And if so, should everything be set to None?

Copy link
Member

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

State attributes are only set if the state of the entity is not unavailable. This is part of the base entity logic. Integrations should not adjust any logic concerning availability and state attributes.

- If an attribute is not expected, it should not be in the dictionary. An attribute is expected if supported by the entity, for example as indicated by `supported_features`.
Copy link
Member

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

I am not really sure what this means and how it would look in practice

Copy link
Member Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

As an example, in statistics the buffer_usage_ratio attribute is only shown if the sensor is configured to handle a buffer size. Otherwise this attribute would be irrelevant hence not showing in that case.

Copy link
Member

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

But how can someone expect it to be there? We're quite bad with describing entities in the docs, let alone describing the state attributes

Copy link
Member

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

This is the developer docs not the user docs. The attribute is expected if it's part of a supported feature and that feature is supported or if it's an extra state attribute the attribute is expected if the device has support for that attribute.


## System properties

The following properties are used and controlled by Home Assistant, and should not be overridden by integrations.
Expand Down