[PR #12081/8faf8c38 backport][stable-13] Add from_toml filter (#12081) (#12125)

Add `from_toml` filter (#12081) (#12081)

* Add `from_toml` filter (#12081)

* Use tasks/main.yml instead of runme.sh for integration tests

* Renamed filter back to to_toml.py, moved from_toml filter to its own file making use of python's native tomllib

* Remove task to install tomlkit library as it's no longer required for the from_toml filter

* Replace deprecated t.Mapping with collections.abc.Mapping (https://docs.python.org/3/library/typing.html#typing.Mapping)

* Type is not determined when function is called. Let isinstance check ensure value has string type.

(cherry picked from commit 8faf8c3838)

Co-authored-by: spike77453 <spike77453@users.noreply.github.com>

.github/BOTMETA.yml

@@ -159,6 +159,10 @@ files:
     maintainers: Ajpantuso
   $filters/from_ini.py:
     maintainers: sscheib
+  $filters/from_toml.py:
+    maintainers: spike77453
+  $filters/from_toml.yml:
+    maintainers: spike77453
   $filters/groupby_as_dict.py:
     maintainers: felixfontein
   $filters/hashids.py:

plugins/filter/from_toml.py

@@ -0,0 +1,24 @@
+# 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
+
+import tomllib
+from ansible.errors import AnsibleFilterError
+
+
+def from_toml(value: t.Any) -> Mapping:
+    if not isinstance(value, str):
+        raise AnsibleFilterError("from_toml only accepts strings.")
+    return tomllib.loads(value)
+
+
+class FilterModule:
+    def filters(self):
+        return {
+            "from_toml": from_toml,
+        }

plugins/filter/from_toml.yml

@@ -0,0 +1,37 @@
+---
+# 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: from_toml
+  author:
+    - Christian Schürmann (@spike77453)
+  version_added: 13.1.0
+  short_description: Convert TOML string into dictionary
+  description:
+    - Converts a string containing a TOML document into an Ansible variable
+  positional: _input
+  options:
+    _input:
+      description:
+        - A string that contains a TOML document.
+      type: str
+      required: true
+
+EXAMPLES: |
+  - name: Slurp TOML file
+    ansible.builtin.slurp:
+      src: config.toml
+    register: config
+
+  - name: Convert data into dictionary
+    ansible.builtin.set_fact:
+      my_config: "{{ config['content'] | b64decode | community.general.from_toml }}"
+
+
+RETURN:
+  _value:
+    description:
+      - Dictionary representing the data from the TOML string.
+    type: dict

tests/integration/targets/filter_from_toml/tasks/main.yml

@@ -0,0 +1,12 @@
+---
+# 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
+
+- name: Convert TOML string to dictionary
+  set_fact:
+    actual_dict: "{{ toml_document | community.general.from_toml }}"
+
+- assert:
+    that:
+      - expected_dict == actual_dict

tests/integration/targets/filter_from_toml/vars/main.yml

@@ -0,0 +1,54 @@
+---
+# 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
+
+toml_document: |-
+  # This is a TOML document
+
+  title = "TOML Example"
+
+  [owner]
+  name = "Tom Preston-Werner"
+  dob = 1979-05-27T07:32:00-08:00
+
+  [database]
+  enabled = true
+  ports = [ 8000, 8001, 8002 ]
+  data = [ ["delta", "phi"], [3.14] ]
+  temp_targets = { cpu = 79.5, case = 72.0 }
+
+  [servers]
+
+  [servers.alpha]
+  ip = "10.0.0.1"
+  role = "frontend"
+
+  [servers.beta]
+  ip = "10.0.0.2"
+  role = "backend"
+
+expected_dict:
+  "title": "TOML Example"
+  "owner":
+    "name": "Tom Preston-Werner"
+    "dob": 1979-05-27T07:32:00-08:00
+  "database":
+    "enabled": true
+    "ports":
+      - 8000
+      - 8001
+      - 8002
+    "data":
+      - ["delta", "phi"]
+      - [3.14]
+    "temp_targets":
+      "case": 72.0
+      "cpu": 79.5
+  "servers":
+    "alpha":
+      "ip": "10.0.0.1"
+      "role": "frontend"
+    "beta":
+      "ip": "10.0.0.2"
+      "role": "backend"