1.18.1 Changes the return types of several existing functions
Closed this issue · 2 comments
I'm submitting a...
[ ] Regression (a behavior that used to work and stopped working in a new release)
[ ] Bug report
[ ] Performance issue
[ ] Feature request (generic to all classes)
[x] Documentation issue or request
[ ] Other... Please describe:
1.18.1 changes the type signatures of several existing functions, adding a new, mysterious and undocumented type called "ApiResponse" to some existing Union type definitions.
It seems to me that this should probably have not been a patch version bump for starters (ie. for when you make backwards compatible bug fixes). Perhaps more importantly these ApiResponse objects are not publicly documented anywhere so it's not clear to me how we are supposed to handle these new return types.
Expected Behavior
Existing, documented functionality such as get_country_and_postal_code should return the documented type signature ie. Union[ShortAddress, Error]
Current Behavior
get_country_and_postal_code returns Union[ApiResponse, ShortAddress, Error]
Possible Solution
Document the ApiResponse object and how it should be handled. Don't introduce changes like this as patch version increments (see https://semver.org/)
Context
I am part of a team that is developing a skill for Alexa and it is not clear how we should be handling this type signature or under what conditions we should expect to receive an "ApiResponse" type from these function calls.
Hi @c22 , thanks for raising this issue. Sorry for the confusion, we should have worked on the documentation to clear this better. I will look into updating the documentation correctly.
As you can look in the device address service client's get_country_and_postal_code method implementation, this ApiResponse instance is only returned when the full_response parameter is set to True. As mentioned in the docstring, this is defaulted to False and doesn't break the existing behavior. The idea is to enhance the service client method, to provide the full response object (ApiResponse) to skill developers, instead of only providing the response body like we used to do before.
Agreed that it is not a patch release but instead a minor release, and sorry for the confusion again. We will take care of updating the release versions correctly from next time.
Hope this helps. Please let us know if you face any other issue.