According to the message in the codebase ansible.utils.unicode.to_str is deprecated, and instead we have to use ansible.module_utils._text.to_native starting from 2.4 which is expected in mid september.
However, the package ansible.module_utils._text still have this warning:
|
… warn:: This module_util is currently internal implementation. We want to evaluate this code for stability and API suitability before making backwards compatibility guarantees. The API may change between releases. Do not use this unless you are willing to port your module code. Someone can tell me if ansible.utils.unicode.to_str will be removed even if the replacing code is not yet considered stable? Is there a expected date for when the replacing code will be expected to became stable? Thank you in advance Fabrizio
|
|
|
|
|
|
|
We do not have a stable API when using ansible as a library except in two ways: (1) ansible/module_utils/* should maintain backwards compatibility. (2) we try to maintain the interface between plugins and the main ansible engine. So ansible.utils.unicode.to_str() is not a stable interface. Since it is implemented via ansible.module_utils._text, it has changed in all the ways that module_utils._text has. And it will go away after a deprecation period.
ansible.module_utils._text has had a few changes from release to release but I’ve managed to keep the interface fairly backwards compatible (only people using it in extremely specialized ways will have had to adapt their code). I believe in both instances of backwards incompatibility, it was tweaks to the default error handler which changes things very slightly when an undecodable byte sequence is passed in (or an unencodable text string is passed in in the case of to_bytes). Because I tweaked it again for 2.4 (handling of the surrogate_or_replace error handler wasn’t sufficient to prevent tracebacks so I wrote and changed the default error handler to the similar surrogate_then_replace) I decided not to remove the stability warning this release. Probably in 2.5, though, as none of the changes I’ve had to make have resulted in any mentions of a noiced backwards incompatibility.
-Toshio