Split update entity's in_progress state attribute in two

[emontnemery]

Background

The update entity's in_progress state attribute currently works like this:

• None: Unknown
• False: An update is not in progress
• True: An update is in progress
• 0 - 100: An update is in progress, the number represents progress in %

This is problematic because it's somewhat difficult to use, also, Python's bool type have the integer values 0 and 1 meaning it's:

• Error prone when writing code which needs to reliably distinguish between 0/1 and False/True
• Home Asisstant's built in suppression of unneeded state changes will suppress a state change where an attribute changes between 0/1 and False/True

Proposal

• Restrict the in_progress state attribute to the values None, True and False
• Restrict the entity property in_progress to the values None, True and False with a deprecation period of one year
  • During the deprecation period, if the in_progress entity property is a number 0-100, the in_progress state attribute will be set to True and the update_percentage state attribute will be set to the number
• Add state attribute update_percentage which can have the values None or a number 0-100
• Add entity property update_percentage which can have the values None or a number 0-100

To consider

There's a feature flag UpdateEntityFeature.PROGRESS, we could consider adding an additional flag to indicate percentage support. I don't think that's needed though.

Impact on custom integrations

There are 20 or so custom integrations published on HACS which will need to updated within the deprecation period

Impact on users

The proposed change will break automations etc. which rely on the in_progress state attribute being an integer. If the automation is blueprinted, updating the automation may be difficult.

I have not been able to find any blueprints which would break because of the proposed change; the only blueprint I could find which uses the in_progress state attribute would benefit from the proposed change https://community.home-assistant.io/t/update-notifications-core-os-addons-hacs-etc/409161

Searches:
https://community.home-assistant.io/search?expanded=true&q=in:title%20update%20%23blueprints-exchange%20order:likes
https://github.com/search?q=%2F%5Cbin_progress%5Cb%2F+%2Fblueprint%3A%2F+path%3A*.yaml&type=code

[parautenbach]

This sounds problematic. :-) The ambiguity of the dynamic typing should probably be fixed.

There are 20 or so custom integrations published on HACS which will need to updated within the deprecation period

Just to clarify, as a maintainer of a HACS custom component: I don't remember updating anything to provide this functionality (to show the progress of updates). Could you perhaps elaborate?

[emontnemery]

Could you perhaps elaborate

What I meant is that custom integrations' update entities need to be updated to implement an in_progress property which returns None, True or False and a progress_percentage property which returns None or a number between 0 and 100.

[parautenbach]

Right, that makes sense.

The bit where I'm still unclear on is that in my case, the update entity exists, but I don't set anything for it in my component's code. I haven't had time to trace this yet, but obviously this must be provided by HA (as a framework) automatically.

So, I'm then interpreting your comment about the 20 HACS integrations to mean that there are some components that directly control the update entity's behaviour – the rest (like mine), won't be affected, since it relies on automatic behaviour.

[MartinHjelmare]

The HACS update entity that is created for all integrations on HACS is generated from the HACS source code, not from the custom integrations on HACS. Custom integration authors with integrations on HACS don't need to worry about that code, unless they want to contribute to it.

[parautenbach]

Thanks for the clarification.

[frenck]

Sounds good to me ✅

../Frenck

[frenck]

Implemented in home-assistant/core#128908