Skip to content

feat: add firmware_compare/firmware_at_least helper#44

Merged
Bre77 merged 1 commit into
mainfrom
fm/tfa-fw-compare-helper-h4
Jul 6, 2026
Merged

feat: add firmware_compare/firmware_at_least helper#44
Bre77 merged 1 commit into
mainfrom
fm/tfa-fw-compare-helper-h4

Conversation

@Bre77

@Bre77 Bre77 commented Jul 6, 2026

Copy link
Copy Markdown
Member

Intent / What

  • Add a firmware-version comparison helper so HA core (and any other consumer) can drop the duplicated, buggy string-comparison logic and import a shared implementation instead.
    • Source: home-assistant/core#175745, which fixed vehicle.firmware >= "2024.44.25"-style lexicographic comparisons that misorder week-based firmware ("2025.10" < "2025.9" as strings), wrongly denying streaming entities to vehicles on newer firmware.
  • tesla_fleet_api/util.py: firmware_compare(a, b) -> int (1/-1/0) as the primary helper, with firmware_at_least(firmware, minimum) -> bool as a thin wrapper (firmware_compare(...) >= 0) so the 16 HA call sites stay a clean drop-in. Both re-exported from the top-level package (from tesla_fleet_api import firmware_at_least).
    • Dependency decision: native tuple comparison, no new dependency. The HA helper leans on AwesomeVersion (already a core dependency there); this library's dependency list is narrow and purpose-built (aiohttp, aiofiles, aiolimiter, cryptography, protobuf, bleak — no general-purpose version-parsing lib), so a small native implementation is the better fit for a client library. Behavior matches the HA helper on every case exercised by its own tests and by every real threshold in the PR (2024.44.25, 2024.26, 2025.2.6, "Unknown" handling, equality, partial versions). One documented divergence: AwesomeVersion has a quirk where a version with an explicit trailing zero component (e.g. "2024.26.0") compares as neither greater, less, nor equal to "2024.26" (its __eq__ is string-identity, not section-identity) — this native implementation instead correctly treats them as equal via zero-padding. No real Tesla firmware/threshold pair in the codebase hits this edge case.
  • Tests (tests/test_firmware_at_least.py): the lexicographic bug case (2025.10 vs 2025.9), equality, partial-version comparisons, zero-padding, unparseable/"Unknown" firmware, and the real thresholds from the HA PR (2024.44.25, 2024.26).
  • Documented this library's publish process (see below) since the HA PR can only switch to importing this helper once it's actually installable from PyPI.
Release/publish process (load-bearing for the HA follow-up)

No release-please or automated version bump. This repo ships by:

  1. A Bump version to X.Y.Z commit on main that updates version in pyproject.toml and __version__ in tesla_fleet_api/__init__.py.
  2. Pushing a matching vX.Y.Z git tag.

.github/workflows/python-publish.yml runs on every push, but the build-and-publish-to-PyPI job (and the GitHub Release creation) is gated on github.ref starting with refs/tags/ — merging this PR to main alone does not publish anything. Someone (a maintainer) needs to cut a version-bump commit and push a tag afterward for firmware_at_least/firmware_compare to become importable from an installed tesla-fleet-api release. Recorded in AGENTS.md under "Release Process" for future reference.

Testing / validation

  • uv run pytest tests -q — 56 passed, 8 subtests passed
  • uv run ruff check tesla_fleet_api tests — all checks passed
  • uv run ruff format --check on new/changed files — clean (pre-existing formatting drift in unrelated files left untouched)
  • uv run pyright tesla_fleet_api — 0 errors, 0 warnings

Ported from Home Assistant core PR #175745, which found that comparing
Tesla firmware strings lexicographically (e.g. vehicle.firmware >= "2024.44.25")
misorders week-based versions such as "2025.10" sorting below "2025.9",
wrongly denying streaming entities to vehicles on newer firmware.

firmware_compare(a, b) -> int compares dotted numeric components pairwise
(returns 1/-1/0), right-padding shorter versions with zeros and treating
unparseable strings (e.g. "Unknown") as sorting behind any parseable
version. firmware_at_least(firmware, minimum) -> bool is a thin wrapper
matching the HA helper's exact call signature for a drop-in replacement.

Implemented as a native tuple comparison rather than adding an
AwesomeVersion dependency, consistent with this library's narrow,
purpose-built dependency list.
@Bre77 Bre77 merged commit 2ccad2a into main Jul 6, 2026
5 checks passed
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

1 participant