Improve error/warning messages w.r.t. YAML quoting (#1205)

* Remove superfluous conversions/assignments.

* Improve messages.

plugins/connection/docker.py

@@ -266,7 +266,9 @@ class Connection(ConnectionBase):
                     if not isinstance(val, str):
                         raise AnsibleConnectionFailure(
                             f"Non-string {what.lower()} found for extra_env option. Ambiguous env options must be "
-                            f"wrapped in quotes to avoid them being interpreted. {what}: {val!r}"
+                            "wrapped in quotes to avoid them being interpreted when directly specified "
+                            "in YAML, or explicitly converted to strings when the option is templated. "
+                            f"{what}: {val!r}"
                         )
                 local_cmd += [
                     b"-e",

plugins/connection/docker_api.py

@@ -282,11 +282,11 @@ class Connection(ConnectionBase):
                     if not isinstance(val, str):
                         raise AnsibleConnectionFailure(
                             f"Non-string {what.lower()} found for extra_env option. Ambiguous env options must be "
-                            f"wrapped in quotes to avoid them being interpreted. {what}: {val!r}"
+                            "wrapped in quotes to avoid them being interpreted when directly specified "
+                            "in YAML, or explicitly converted to strings when the option is templated. "
+                            f"{what}: {val!r}"
                         )
-                kk = to_text(k, errors="surrogate_or_strict")
+                data["Env"].append(f"{k}={v}")
-                vv = to_text(v, errors="surrogate_or_strict")
-                data["Env"].append(f"{kk}={vv}")
 
         if self.get_option("working_dir") is not None:
             data["WorkingDir"] = self.get_option("working_dir")

plugins/module_utils/_module_container/base.py

@@ -659,7 +659,9 @@ def _preprocess_env(
             if not isinstance(value, str):
                 module.fail_json(
                     msg="Non-string value found for env option. Ambiguous env options must be "
-                    f"wrapped in quotes to avoid them being interpreted. Key: {name}"
+                    "wrapped in quotes to avoid them being interpreted when directly specified "
+                    "in YAML, or explicitly converted to strings when the option is templated. "
+                    f"Key: {name}"
                 )
             final_env[name] = to_text(value, errors="surrogate_or_strict")
     formatted_env = []
@@ -947,7 +949,8 @@ def _preprocess_log(
                 value = to_text(v, errors="surrogate_or_strict")
                 module.warn(
                     f"Non-string value found for log_options option '{k}'. The value is automatically converted to {value!r}. "
-                    "If this is not correct, or you want to avoid such warnings, please quote the value."
+                    "If this is not correct, or you want to avoid such warnings, please quote the value,"
+                    " or explicitly convert the values to strings when templating them."
                 )
                 v = value
             options[k] = v

plugins/modules/docker_compose_v2_exec.py

@@ -210,13 +210,14 @@ class ExecManager(BaseComposeManager):
             self.stdin += "\n"
 
         if self.env is not None:
-            for name, value in list(self.env.items()):
+            for name, value in self.env.items():
                 if not isinstance(value, str):
                     self.fail(
                         "Non-string value found for env option. Ambiguous env options must be "
-                        f"wrapped in quotes to avoid them being interpreted. Key: {name}"
+                        "wrapped in quotes to avoid them being interpreted when directly specified "
+                        "in YAML, or explicitly converted to strings when the option is templated. "
+                        f"Key: {name}"
                     )
-                self.env[name] = to_text(value, errors="surrogate_or_strict")
 
     def get_exec_cmd(self, dry_run: bool) -> list[str]:
         args = self.get_base_args(plain_progress=True) + ["exec"]

plugins/modules/docker_compose_v2_run.py

@@ -296,13 +296,14 @@ class ExecManager(BaseComposeManager):
             self.stdin += "\n"
 
         if self.env is not None:
-            for name, value in list(self.env.items()):
+            for name, value in self.env.items():
                 if not isinstance(value, str):
                     self.fail(
                         "Non-string value found for env option. Ambiguous env options must be "
-                        f"wrapped in quotes to avoid them being interpreted. Key: {name}"
+                        "wrapped in quotes to avoid them being interpreted when directly specified "
+                        "in YAML, or explicitly converted to strings when the option is templated. "
+                        f"Key: {name}"
                     )
-                self.env[name] = to_text(value, errors="surrogate_or_strict")
 
     def get_run_cmd(self, dry_run: bool) -> list[str]:
         args = self.get_base_args(plain_progress=True) + ["run"]

plugins/modules/docker_container_exec.py

@@ -221,16 +221,17 @@ def main() -> None:
     stdin: str | None = client.module.params["stdin"]
     strip_empty_ends: bool = client.module.params["strip_empty_ends"]
     tty: bool = client.module.params["tty"]
-    env: dict[str, t.Any] = client.module.params["env"]
+    env: dict[str, t.Any] | None = client.module.params["env"]
 
     if env is not None:
-        for name, value in list(env.items()):
+        for name, value in env.items():
             if not isinstance(value, str):
                 client.module.fail_json(
                     msg="Non-string value found for env option. Ambiguous env options must be "
-                    f"wrapped in quotes to avoid them being interpreted. Key: {name}"
+                    "wrapped in quotes to avoid them being interpreted when directly specified "
+                    "in YAML, or explicitly converted to strings when the option is templated. "
+                    f"Key: {name}"
                 )
-            env[name] = to_text(value, errors="surrogate_or_strict")
 
     if command is not None:
         argv = shlex.split(command)

plugins/modules/docker_swarm_service.py

@@ -914,8 +914,10 @@ def get_docker_environment(
         for name, value in env.items():
             if not isinstance(value, str):
                 raise ValueError(
-                    "Non-string value found for env option. "
+                    "Non-string value found for env option. Ambiguous env options must be "
-                    f"Ambiguous env options must be wrapped in quotes to avoid YAML parsing. Key: {name}"
+                    "wrapped in quotes to avoid them being interpreted when directly specified "
+                    "in YAML, or explicitly converted to strings when the option is templated. "
+                    f"Key: {name}"
                 )
             env_dict[name] = str(value)
     elif env is not None and isinstance(env, list):

tests/integration/targets/docker_container/tasks/tests/options.yml

@@ -3077,10 +3077,14 @@
     that:
       - log_options_1 is changed
       - log_options_2 is not changed
-      - "'Non-string value found for log_options option \\'max-file\\'. The value is automatically converted to \\'5\\'. If this is not correct, or you want to
+      - message in (log_options_2.warnings | default([]))
-  avoid such warnings, please quote the value.' in (log_options_2.warnings | default([]))"
       - log_options_3 is not changed
       - log_options_4 is changed
+  vars:
+    message: >-
+      Non-string value found for log_options option 'max-file'. The value is automatically converted to '5'.
+      If this is not correct, or you want to avoid such warnings, please quote the value,
+      or explicitly convert the values to strings when templating them.
 
 ####################################################################
 ## mac_address #####################################################