With the 1.2.0 release of the V2 Iot Device SDK for Python, a serious backwards incompatibility was introduced due to an oversight in the code generation for the constructors of service model classes. This release corrects this incompatibility and reworks service model construction with a pattern that will prevent it from happening again. In these notes we detail exactly what happened, who is affected by the breaking change, and how we are addressing it both right now and looking towards the future.
The 1.2.0 (named shadow) release saw the introduction of new APIs to support named shadows, but it also introduced a new parameter, client_token, to the GetShadow and DeleteShadow APIs. The code generator for the constructor for the request and response classes took the list of parameters and sorted them before generating the code. Since client_token comes before thing_name lexically, this resulted in client_token becoming the first parameter to the class constructor. Any programs calling GetShadow or DeleteShadow using thing_name as the first positional parameter were broken by this change (assuming an upgrade to 1.2.0). This includes the shadow sample itself.
Who was affected by this breaking change? Anyone who upgraded to a 1.2.x version of the SDK who had a program that used either the GetShadow or DeleteShadow APIs.
To fix this, we settled on the following solution:
- All class members are now initializable by keyword args in the class constructor
- Positional arguments in constructors are still supported, permanently "frozen" against the 1.2.x API model
- GetShadowRequest and DeleteShadowRequest constructors support positional parameters for both the pre-1.2.x API (thing_name only) and the 1.2.x API (client_token, thing_name)
- During construction, positional arguments take priority over keyword arguments
- Moving forward, all newly-added members will only be able to be initialized by keyword arguments
The upgrade to 1.3.x and beyond will not break any working programs built against any version of the SDK and will restore programs that were broken by 1.2.x to a working state.
Going forward, all new parameters to service model class construction will be keyword only. All samples have been updated to reflect this new pattern.
We apologize for this customer-breaking mistake and, in addition to fixing it, we are in the process of improving our CI infrastructure to help prevent breaking changes from reaching our customers again.