docs: fill gaps in v2 migration guide#2119
Merged
Merged
Conversation
Add the breaking changes that were missing from the v1->v2 migration guide, found by diffing the public API surface between v1.9.1 and HEAD: - Iteration over States/CommandDefinitions/StateDefinitions now yields keys (str) instead of objects (Mapping behavior) - silent change - Command is no longer a dict subclass (attribute access, to_payload()) - Event.setupoid -> Event.setup_oid rename and new fields - Setup/ActionGroup timestamp fields str -> int - Additional new exception types, Server enum members, APIType - verify_ssl constructor parameter
My first pass diffed against v1.9.1, but the actual latest v1 release is v1.20.6. Several 'gaps' were already present in v1.20.6, so drop the claims that are not actually v1->v2 changes: - verify_ssl constructor param (added in v1.x) - Setup/ActionGroup timestamp str->int (already int in v1.20.6) - 8 'new' exceptions (exist in v1.20.6; only the *Exception->*Error rename applies, already documented) - SAUTER_COZYTOUCH/THERMOR_COZYTOUCH Server members (already in v1.20.6) - APIType enum (already in v1.20.6) Verified against v1.20.6, the remaining additions are genuine v2 breaks: Mapping iteration yields keys, Command no longer a dict, Event.setupoid rename.
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
Add this suggestion to a batch that can be applied as a single commit.This suggestion is invalid because no changes were made to the code.Suggestions cannot be applied while the pull request is closed.Suggestions cannot be applied while viewing a subset of changes.Only one suggestion per line can be applied in a batch.Add this suggestion to a batch that can be applied as a single commit.Applying suggestions on deleted lines is not supported.You must change the existing code in this line in order to create a valid suggestion.Outdated suggestions cannot be applied.This suggestion has been applied or marked resolved.Suggestions cannot be applied from pending reviews.Suggestions cannot be applied on multi-line comments.Suggestions cannot be applied while the pull request is queued to merge.Suggestion cannot be applied right now. Please check back later.
Summary
Reviewed the v2 migration guide against the actual latest v1 release (
v1.20.6) to find breaking changes that were missing. Three genuine gaps remain after verification; docs-only (docs/migration-v2.md).Added
States/CommandDefinitions/StateDefinitions— these now subclasscollections.abc.Mapping, sofor x in device.statesyields keys (str) instead of the objects. Silent change (no exception), and the Home Assistant integration relies on the old behavior (sensor.py,executor.py). Added a dedicated section with adangeradmonition and.values()/.items()examples.Commandis no longer adictsubclass —command["name"]no longer works; use attribute access orto_payload(). Notes the newtypefield andOverkizCommandParamparameter support.Event.setupoid→Event.setup_oidrename (+ newactions/owner/sourcefields), added to the parameter-renames table.Note
My first pass mistakenly diffed against
v1.9.1(alphabetical tag sort hidv1.10–v1.20.6). That produced several false "gaps" —verify_ssl, timestampstr→int, eight "new" exceptions, twoServerenum members, andAPIType— all of which already shipped in v1.x. Those were removed in the second commit; everything remaining is verified againstv1.20.6.