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>

tests/integration/targets/filter_to_toml/aliases

@@ -0,0 +1,5 @@
+# Copyright (c) Ansible Project
+# GNU General Public License v3.0+ (see LICENSES/GPL-3.0-or-later.txt or https://www.gnu.org/licenses/gpl-3.0.txt)
+# SPDX-License-Identifier: GPL-3.0-or-later
+
+azp/posix/3

tests/integration/targets/filter_to_toml/main.yml

@@ -0,0 +1,84 @@
+---
+# Copyright (c) Ansible Project
+# GNU General Public License v3.0+ (see LICENSES/GPL-3.0-or-later.txt or https://www.gnu.org/licenses/gpl-3.0.txt)
+# SPDX-License-Identifier: GPL-3.0-or-later
+
+- hosts: localhost
+  gather_facts: false
+  vars_files:
+    - vaulted_vars.yml
+  vars:
+    timestamp: 2025-01-02T03:04:05Z
+    bar: "foobarbaz"
+  tasks:
+    - name: Convert more complex data structure (from vars file)
+      set_fact:
+        complex: "{{ foobar | community.general.to_toml }}"
+        complex_redact: "{{ foobar | community.general.to_toml(redact_sensitive_values=true) }}"
+
+    - assert:
+        that:
+          - complex == exp_complex
+          - complex_redact == exp_complex_redact
+      vars:
+        exp_complex: |
+          a_value = 123
+          a_list = ["bar", 2025-02-03T04:05:06, "Hello!", true, false]
+        exp_complex_redact: |
+          a_value = 123
+          a_list = ["<redacted>", 2025-02-03T04:05:06, "Hello!", true, false]
+
+    - name: Convert more complex data structure (from vars)
+      set_fact:
+        complex: "{{ data | community.general.to_toml }}"
+        complex_redact: "{{ data | community.general.to_toml(redact_sensitive_values=true) }}"
+      vars:
+        data:
+          foo: 123
+          bar: 1.23
+          baz: true
+          bam: foobar
+          bang:
+            - "{{ timestamp }}"
+            - "{{ bar }}"
+            - "{{ foo }}"
+
+    - when: ansible_version.full is version("2.19", "<")
+      assert:
+        that:
+          - complex == exp_complex
+          # With ansible-core 2.18 and before, the vaulted string is decrypted before it reaches the filter,
+          # so the redaction does not work there.
+          - complex_redact == exp_complex
+      vars:
+        exp_complex: |
+          foo = 123
+          bar = 1.23
+          baz = true
+          bam = "foobar"
+          bang = ["2025-01-02 03:04:05+00:00", "foobarbaz", "bar"]
+        exp_complex_redact: |
+          foo = 123
+          bar = 1.23
+          baz = true
+          bam = "foobar"
+          bang = ["2025-01-02 03:04:05+00:00", "foobarbaz", "bar"]
+
+    - when: ansible_version.full is version("2.19", ">=")
+      assert:
+        that:
+          - complex == exp_complex
+          - complex_redact == exp_complex_redact
+      vars:
+        exp_complex: |
+          foo = 123
+          bar = 1.23
+          baz = true
+          bam = "foobar"
+          bang = [2025-01-02T03:04:05Z, "foobarbaz", "bar"]
+        exp_complex_redact: |
+          foo = 123
+          bar = 1.23
+          baz = true
+          bam = "foobar"
+          bang = [2025-01-02T03:04:05Z, "foobarbaz", "<redacted>"]

tests/integration/targets/filter_to_toml/password

@@ -0,0 +1 @@
+secret

tests/integration/targets/filter_to_toml/password.license

@@ -0,0 +1,3 @@
+Copyright (c) Ansible Project
+GNU General Public License v3.0+ (see LICENSES/GPL-3.0-or-later.txt or https://www.gnu.org/licenses/gpl-3.0.txt)
+SPDX-License-Identifier: GPL-3.0-or-later

tests/integration/targets/filter_to_toml/runme.sh

@@ -0,0 +1,15 @@
+#!/usr/bin/env bash
+# Copyright (c) Ansible Project
+# GNU General Public License v3.0+ (see LICENSES/GPL-3.0-or-later.txt or https://www.gnu.org/licenses/gpl-3.0.txt)
+# SPDX-License-Identifier: GPL-3.0-or-later
+
+set -eux
+
+source virtualenv.sh
+
+# Requirements have to be installed prior to running ansible-playbook
+# because plugins and requirements are loaded before the task runs
+
+pip install tomlkit
+
+ansible-playbook --vault-password-file password main.yml "$@"

tests/integration/targets/filter_to_toml/vaulted_vars.yml

@@ -0,0 +1,27 @@
+---
+# Copyright (c) Ansible Project
+# GNU General Public License v3.0+ (see LICENSES/GPL-3.0-or-later.txt or https://www.gnu.org/licenses/gpl-3.0.txt)
+# SPDX-License-Identifier: GPL-3.0-or-later
+
+foo: !vault |
+  $ANSIBLE_VAULT;1.1;AES256
+  32336431346561346535396563363438333131636539653331376466383331663838303835353862
+  3536306130663166393533626530646435383938323066320a303366613035323835373030303262
+  35633636653362393531653961396665663965356562346538643863336562393734376234313134
+  3562663234326435390a376464633234373636643538353562326133316439343863373333363265
+  6239
+
+foobar:
+  a_value: 123
+  a_list:
+    - !vault |
+      $ANSIBLE_VAULT;1.1;AES256
+      32336431346561346535396563363438333131636539653331376466383331663838303835353862
+      3536306130663166393533626530646435383938323066320a303366613035323835373030303262
+      35633636653362393531653961396665663965356562346538643863336562393734376234313134
+      3562663234326435390a376464633234373636643538353562326133316439343863373333363265
+      6239
+    - 2025-02-03 04:05:06
+    - Hello!
+    - true
+    - false