Add to_toml filter (#11423)

* Add to_toml filter

This is based heavily on the to_yaml filter, but
with a pared-down feature set.

* Protect import

* Don't quote datetime as a string

* Use Ansible error types

* Import correct error types

* Don't use AnsibleTypeError

It doesn't seem to be available on older Ansible
core versions.

* Fix antsibull-nox errors

* Install dependencies for to_toml integration test

Co-authored-by: Felix Fontein <felix@fontein.de>

* Reduce author list to main contributor

Co-authored-by: Felix Fontein <felix@fontein.de>

* Update version added for to_toml

Co-authored-by: Felix Fontein <felix@fontein.de>

* Use AnsibleError for missing import

Co-authored-by: Felix Fontein <felix@fontein.de>

* Use AnsibleFilterError for runtime type check

Co-authored-by: Felix Fontein <felix@fontein.de>

* Move common code to plugin_utils/_tags.py

* Mark module util as private

Co-authored-by: Felix Fontein <felix@fontein.de>

* Update BOTMETA for to_toml

Co-authored-by: Felix Fontein <felix@fontein.de>

* Fix typo

* Correct version number

Co-authored-by: Felix Fontein <felix@fontein.de>

* Use to_text for to_toml dict key conversions

Co-authored-by: Felix Fontein <felix@fontein.de>

* Add tomlkit requirement to docs

Co-authored-by: Felix Fontein <felix@fontein.de>

* Add missing import

* Add aliases for for to_toml integration test

---------

Co-authored-by: Felix Fontein <felix@fontein.de>

plugins/filter/to_toml.py

@@ -0,0 +1,50 @@
+# Copyright (c) Contributors to the Ansible project
+# GNU General Public License v3.0+ (see COPYING or https://www.gnu.org/licenses/gpl-3.0.txt)
+# SPDX-License-Identifier: GPL-3.0-or-later
+
+from __future__ import annotations
+
+import typing as t
+from collections.abc import Mapping
+
+from ansible.module_utils.common.collections import is_sequence
+from ansible.module_utils.common.text.converters import to_text
+
+TOMLKIT_IMPORT_ERROR: ImportError | None
+try:
+    from tomlkit import dumps
+except ImportError as imp_exc:
+    TOMLKIT_IMPORT_ERROR = imp_exc
+else:
+    TOMLKIT_IMPORT_ERROR = None
+
+from ansible.errors import AnsibleError, AnsibleFilterError
+
+from ansible_collections.community.general.plugins.plugin_utils._tags import remove_all_tags
+
+
+def _stringify_keys(value: t.Any) -> t.Any:
+    """Recursively convert all keys to strings."""
+    if isinstance(value, Mapping):
+        return {to_text(k): _stringify_keys(v) for k, v in value.items()}
+    if is_sequence(value):
+        return [_stringify_keys(e) for e in value]
+    return value
+
+
+def to_toml(value: t.Mapping, *, redact_sensitive_values: bool = False) -> str:
+    """Serialize input as TOML."""
+    if TOMLKIT_IMPORT_ERROR:
+        raise AnsibleError("tomlkit must be installed to use this plugin") from TOMLKIT_IMPORT_ERROR
+    if not isinstance(value, Mapping):
+        raise AnsibleFilterError("to_toml only accepts dictionaries.")
+    return dumps(
+        remove_all_tags(_stringify_keys(value), redact_sensitive_values=redact_sensitive_values),
+    )
+
+
+class FilterModule:
+    def filters(self):
+        return {
+            "to_toml": to_toml,
+        }

plugins/filter/to_toml.yml

@@ -0,0 +1,42 @@
+# Copyright (c) Contributors to the Ansible project
+# GNU General Public License v3.0+ (see COPYING or https://www.gnu.org/licenses/gpl-3.0.txt)
+# SPDX-License-Identifier: GPL-3.0-or-later
+
+DOCUMENTATION:
+  name: to_toml
+  author:
+    - Matt Williaks (@milliams)
+  version_added: 12.3.0
+  short_description: Convert variable to TOML string
+  description:
+    - Converts an Ansible variable into a TOML string representation.
+    - This filter functions as a wrapper to the L(Python TOML Kit library, https://pypi.org/project/tomlkit/)'s C(tomlkit.dumps) function.
+  requirements:
+    - tomlkit
+  positional: _input
+  options:
+    _input:
+      description:
+        - A variable or expression that returns a data structure.
+      type: dict
+      required: true
+    redact_sensitive_values:
+      description:
+        - If set to V(true), vaulted strings are replaced by V(<redacted>) instead of being decrypted.
+        - With future ansible-core versions, this can extend to other strings tagged as sensitive.
+        - B(Note) that with ansible-core 2.18 and before this might not yield the expected result
+          since these versions of ansible-core strip the vault information away from strings that are
+          part of more complex data structures specified in C(vars).
+      type: bool
+      default: false
+
+EXAMPLES: |
+  ---
+  # Dump variable in a template to create a TOML document
+  value: "{{ my_config | community.general.to_toml }}"
+
+RETURN:
+  _value:
+    description:
+      - The TOML serialized string representing the variable structure inputted.
+    type: string

plugins/filter/to_yaml.py

@@ -5,7 +5,6 @@
 from __future__ import annotations
 
 import typing as t
-from collections.abc import Mapping, Set
 
 from yaml import dump
 
@@ -14,81 +13,7 @@ try:
 except ImportError:
     from yaml import SafeDumper  # type: ignore
 
-from ansible.module_utils.common.collections import is_sequence
-
-try:
-    # This is ansible-core 2.19+
-    from ansible.parsing.vault import VaultHelper, VaultLib
-    from ansible.utils.vars import transform_to_native_types
-
-    HAS_TRANSFORM_TO_NATIVE_TYPES = True
-except ImportError:
-    HAS_TRANSFORM_TO_NATIVE_TYPES = False
-
-from ansible.parsing.yaml.objects import AnsibleVaultEncryptedUnicode
-from ansible.utils.unsafe_proxy import AnsibleUnsafe
-
-
-def _to_native_types_compat(value: t.Any, *, redact_value: str | None) -> t.Any:
-    """Compatibility function for ansible-core 2.18 and before."""
-    if value is None:
-        return value
-    if isinstance(value, AnsibleUnsafe):
-        # This only works up to ansible-core 2.18:
-        return _to_native_types_compat(value._strip_unsafe(), redact_value=redact_value)  # type: ignore
-        # But that's fine, since this code path isn't taken on ansible-core 2.19+ anyway.
-    if isinstance(value, Mapping):
-        return {
-            _to_native_types_compat(key, redact_value=redact_value): _to_native_types_compat(
-                val, redact_value=redact_value
-            )
-            for key, val in value.items()
-        }
-    if isinstance(value, Set):
-        return {_to_native_types_compat(elt, redact_value=redact_value) for elt in value}
-    if is_sequence(value):
-        return [_to_native_types_compat(elt, redact_value=redact_value) for elt in value]
-    if isinstance(value, AnsibleVaultEncryptedUnicode):
-        if redact_value is not None:
-            return redact_value
-        # This only works up to ansible-core 2.18:
-        return value.data
-        # But that's fine, since this code path isn't taken on ansible-core 2.19+ anyway.
-    if isinstance(value, bytes):
-        return bytes(value)
-    if isinstance(value, str):
-        return str(value)
-
-    return value
-
-
-def _to_native_types(value: t.Any, *, redact: bool) -> t.Any:
-    if isinstance(value, Mapping):
-        return {_to_native_types(k, redact=redact): _to_native_types(v, redact=redact) for k, v in value.items()}
-    if is_sequence(value):
-        return [_to_native_types(e, redact=redact) for e in value]
-    if redact:
-        ciphertext = VaultHelper.get_ciphertext(value, with_tags=False)
-        if ciphertext and VaultLib.is_encrypted(ciphertext):
-            return "<redacted>"
-    return transform_to_native_types(value, redact=redact)
-
-
-def remove_all_tags(value: t.Any, *, redact_sensitive_values: bool = False) -> t.Any:
-    """
-    Remove all tags from all values in the input.
-
-    If ``redact_sensitive_values`` is ``True``, all sensitive values will be redacted.
-    """
-    if HAS_TRANSFORM_TO_NATIVE_TYPES:
-        return _to_native_types(value, redact=redact_sensitive_values)
-
-    return _to_native_types_compat(  # type: ignore[unreachable]
-        value,
-        redact_value="<redacted>"
-        if redact_sensitive_values
-        else None,  # same string as in ansible-core 2.19 by transform_to_native_types()
-    )
+from ansible_collections.community.general.plugins.plugin_utils._tags import remove_all_tags
 
 
 def to_yaml(

plugins/plugin_utils/_tags.py

@@ -0,0 +1,85 @@
+# Copyright (c) Contributors to the Ansible project
+# GNU General Public License v3.0+ (see COPYING or https://www.gnu.org/licenses/gpl-3.0.txt)
+# SPDX-License-Identifier: GPL-3.0-or-later
+
+# Note that this module util is **PRIVATE** to the collection. It can have breaking changes at any time.
+# Do not use this from other collections or standalone plugins/modules!
+
+import typing as t
+from collections.abc import Mapping, Set
+
+from ansible.module_utils.common.collections import is_sequence
+
+try:
+    # This is ansible-core 2.19+
+    from ansible.parsing.vault import VaultHelper, VaultLib
+    from ansible.utils.vars import transform_to_native_types
+
+    HAS_TRANSFORM_TO_NATIVE_TYPES = True
+except ImportError:
+    HAS_TRANSFORM_TO_NATIVE_TYPES = False
+
+from ansible.parsing.yaml.objects import AnsibleVaultEncryptedUnicode
+from ansible.utils.unsafe_proxy import AnsibleUnsafe
+
+
+def _to_native_types_compat(value: t.Any, *, redact_value: str | None) -> t.Any:
+    """Compatibility function for ansible-core 2.18 and before."""
+    if value is None:
+        return value
+    if isinstance(value, AnsibleUnsafe):
+        # This only works up to ansible-core 2.18:
+        return _to_native_types_compat(value._strip_unsafe(), redact_value=redact_value)  # type: ignore
+        # But that's fine, since this code path isn't taken on ansible-core 2.19+ anyway.
+    if isinstance(value, Mapping):
+        return {
+            _to_native_types_compat(key, redact_value=redact_value): _to_native_types_compat(
+                val, redact_value=redact_value
+            )
+            for key, val in value.items()
+        }
+    if isinstance(value, Set):
+        return {_to_native_types_compat(elt, redact_value=redact_value) for elt in value}
+    if is_sequence(value):
+        return [_to_native_types_compat(elt, redact_value=redact_value) for elt in value]
+    if isinstance(value, AnsibleVaultEncryptedUnicode):
+        if redact_value is not None:
+            return redact_value
+        # This only works up to ansible-core 2.18:
+        return value.data
+        # But that's fine, since this code path isn't taken on ansible-core 2.19+ anyway.
+    if isinstance(value, bytes):
+        return bytes(value)
+    if isinstance(value, str):
+        return str(value)
+
+    return value
+
+
+def _to_native_types(value: t.Any, *, redact: bool) -> t.Any:
+    if isinstance(value, Mapping):
+        return {_to_native_types(k, redact=redact): _to_native_types(v, redact=redact) for k, v in value.items()}
+    if is_sequence(value):
+        return [_to_native_types(e, redact=redact) for e in value]
+    if redact:
+        ciphertext = VaultHelper.get_ciphertext(value, with_tags=False)
+        if ciphertext and VaultLib.is_encrypted(ciphertext):
+            return "<redacted>"
+    return transform_to_native_types(value, redact=redact)
+
+
+def remove_all_tags(value: t.Any, *, redact_sensitive_values: bool = False) -> t.Any:
+    """
+    Remove all tags from all values in the input.
+
+    If ``redact_sensitive_values`` is ``True``, all sensitive values will be redacted.
+    """
+    if HAS_TRANSFORM_TO_NATIVE_TYPES:
+        return _to_native_types(value, redact=redact_sensitive_values)
+
+    return _to_native_types_compat(  # type: ignore[unreachable]
+        value,
+        redact_value="<redacted>"
+        if redact_sensitive_values
+        else None,  # same string as in ansible-core 2.19 by transform_to_native_types()
+    )