diff --git a/blog/2024-09-28-update-version-compare.md b/blog/2024-09-28-update-version-compare.md new file mode 100644 index 00000000..6e1e7025 --- /dev/null +++ b/blog/2024-09-28-update-version-compare.md @@ -0,0 +1,32 @@ +--- +author: Simone Chemelli +authorURL: https://github.com/chemelli74 +title: "Version compare for Update platform can now be overwritten" +--- + +With the merge of [core PR #124797](https://github.com/home-assistant/core/pull/124797), which will land in Home Assistant Core 2024.10, there is a new method in the update platform: `version_is_newer()`. + +Before this change, the compare logic between firmware installed version, new available version and beta version was hardcoded: + +```python +def version_is_newer(self, latest_version: str, installed_version: str) -> bool: + """Return True if latest_version is newer than installed_version.""" + return AwesomeVersion(latest_version) > installed_version +``` + +Now the new method allows developers to customize this comparison, writing their own method. +Here's an example (implemented for Shelly gen1 devices): + +```python +def version_is_newer(self, latest_version: str, installed_version: str) -> bool: + """Return True if available version is newer then installed version.""" + return AwesomeVersion( + latest_version, + find_first_match=True, + ensure_strategy=[AwesomeVersionStrategy.SEMVER], + ) > AwesomeVersion( + installed_version, + find_first_match=True, + ensure_strategy=[AwesomeVersionStrategy.SEMVER], + ) +``` diff --git a/docs/core/entity/update.md b/docs/core/entity/update.md index fec51362..b939d5b0 100644 --- a/docs/core/entity/update.md +++ b/docs/core/entity/update.md @@ -47,6 +47,27 @@ Supported features are defined by using values in the `UpdateEntityFeature` enum ## Methods +### Compare versions + +This method should be implemented when needed to override the default version comparison logic. +Here's an example: + +```python +def version_is_newer(self, latest_version: str, installed_version: str) -> bool: + """Return True if latest_version is newer than installed_version.""" + return AwesomeVersion( + latest_version, + find_first_match=True, + ensure_strategy=[AwesomeVersionStrategy.SEMVER], + ) > AwesomeVersion( + installed_version, + find_first_match=True, + ensure_strategy=[AwesomeVersionStrategy.SEMVER], + ) +``` + +It allows developers to specify custom logic for determining if one version is newer than another. First attempt should be based on the strategies provided by the [AwesomeVersion library](https://github.com/ludeeus/awesomeversion?tab=readme-ov-file#awesomeversion-class). + ### Install This method can be implemented so users can install an offered update directly