From 3a01ceb355b69ba9e7f8a6242fdcb8e0bdd074cf Mon Sep 17 00:00:00 2001 From: "patchback[bot]" <45432694+patchback[bot]@users.noreply.github.com> Date: Fri, 5 Jul 2024 08:53:55 +0200 Subject: [PATCH] [PR #8482/caecb229 backport][stable-9] Feature. Add chapter 'Lists of dictionaries' to docsite (#8582) Feature. Add chapter 'Lists of dictionaries' to docsite (#8482) * Feature. Add chapter 'Lists of dictionaries' * Fix copyright and licensing. * Add maintainers for docsite chapter 'Lists of dictionaries'. * Generate docs keep_keys and remove_keys * Update integration tests of keep_keys and remove_keys * Update docs helpers of keep_keys and remove_keys * Fix copyright and licensing. * Fix remove license from templates. Cleanup. * Add docs helper replace_keys * Update integration test filter_replace_keys * Generate and update: filter_guide-abstract_informations-lists_of_dictionaries-replace_keys.rst * Formatting improved. * Fix results Jinja quotation marks. * Update docs/docsite/helper/keep_keys/filter_guide-abstract_informations-lists_of_dictionaries-keep_keys.rst.j2 Co-authored-by: Felix Fontein * Update docs/docsite/helper/keep_keys/filter_guide-abstract_informations-lists_of_dictionaries-keep_keys.rst.j2 Co-authored-by: Felix Fontein * Fix references. * Updated helpers. * Fix licenses. Simplified templates. * Fix licenses. * Fix README. --------- Co-authored-by: Felix Fontein (cherry picked from commit caecb2297fbf8cfb9ae80926ead10b4fb11a003f) Co-authored-by: Vladimir Botka --- .github/BOTMETA.yml | 8 + docs/docsite/helper/keep_keys/README.md | 61 ++++++ ...ons-lists_of_dictionaries-keep_keys.rst.j2 | 80 ++++++++ .../helper/keep_keys/keep_keys.rst.sha1 | 1 + .../keep_keys/keep_keys.rst.sha1.license | 3 + docs/docsite/helper/keep_keys/playbook.yml | 79 ++++++++ docs/docsite/helper/keep_keys/tests.yml.sha1 | 1 + .../helper/keep_keys/tests.yml.sha1.license | 3 + docs/docsite/helper/remove_keys/README.md | 61 ++++++ ...s-lists_of_dictionaries-remove_keys.rst.j2 | 80 ++++++++ docs/docsite/helper/remove_keys/playbook.yml | 79 ++++++++ .../helper/remove_keys/remove_keys.rst.sha1 | 1 + .../remove_keys/remove_keys.rst.sha1.license | 3 + .../docsite/helper/remove_keys/tests.yml.sha1 | 1 + .../helper/remove_keys/tests.yml.sha1.license | 3 + docs/docsite/helper/replace_keys/README.md | 61 ++++++ ...-lists_of_dictionaries-replace_keys.rst.j2 | 110 +++++++++++ docs/docsite/helper/replace_keys/playbook.yml | 79 ++++++++ .../helper/replace_keys/replace_keys.rst.sha1 | 1 + .../replace_keys.rst.sha1.license | 3 + .../helper/replace_keys/tests.yml.sha1 | 1 + .../replace_keys/tests.yml.sha1.license | 3 + ...ations-lists_of_dictionaries-keep_keys.rst | 151 +++++++++++++++ ...ions-lists_of_dictionaries-remove_keys.rst | 159 ++++++++++++++++ ...ons-lists_of_dictionaries-replace_keys.rst | 175 ++++++++++++++++++ ...act_informations-lists_of_dictionaries.rst | 18 ++ .../filter_guide_abstract_informations.rst | 1 + .../filter_keep_keys/tasks/keep_keys.yml | 79 -------- .../targets/filter_keep_keys/tasks/main.yml | 4 +- .../targets/filter_keep_keys/tasks/tests.yml | 31 ++++ .../filter_keep_keys/templates/default.j2 | 1 + .../templates/default.j2.license | 3 + .../targets/filter_keep_keys/templates/mp.j2 | 1 + .../filter_keep_keys/templates/mp.j2.license | 3 + .../targets/filter_keep_keys/vars/main.yml | 33 ---- .../filter_keep_keys/vars/main/tests.yml | 40 ++++ .../targets/filter_remove_keys/tasks/main.yml | 4 +- .../filter_remove_keys/tasks/remove_keys.yml | 79 -------- .../filter_remove_keys/tasks/tests.yml | 31 ++++ .../filter_remove_keys/templates/default.j2 | 1 + .../templates/default.j2.license | 3 + .../filter_remove_keys/templates/mp.j2 | 1 + .../templates/mp.j2.license | 3 + .../targets/filter_remove_keys/vars/main.yml | 33 ---- .../filter_remove_keys/vars/main/tests.yml | 40 ++++ .../tasks/fn-test-replace_keys.yml | 21 --- .../filter_replace_keys/tasks/main.yml | 4 +- .../tasks/replace_keys.yml | 56 ------ .../filter_replace_keys/tasks/tests.yml | 31 ++++ .../filter_replace_keys/templates/default.j2 | 1 + .../templates/default.j2.license | 3 + .../filter_replace_keys/templates/mp.j2 | 1 + .../templates/mp.j2.license | 3 + .../targets/filter_replace_keys/vars/main.yml | 58 ------ .../filter_replace_keys/vars/main/tests.yml | 71 +++++++ 55 files changed, 1500 insertions(+), 365 deletions(-) create mode 100644 docs/docsite/helper/keep_keys/README.md create mode 100644 docs/docsite/helper/keep_keys/filter_guide-abstract_informations-lists_of_dictionaries-keep_keys.rst.j2 create mode 100644 docs/docsite/helper/keep_keys/keep_keys.rst.sha1 create mode 100644 docs/docsite/helper/keep_keys/keep_keys.rst.sha1.license create mode 100644 docs/docsite/helper/keep_keys/playbook.yml create mode 100644 docs/docsite/helper/keep_keys/tests.yml.sha1 create mode 100644 docs/docsite/helper/keep_keys/tests.yml.sha1.license create mode 100644 docs/docsite/helper/remove_keys/README.md create mode 100644 docs/docsite/helper/remove_keys/filter_guide-abstract_informations-lists_of_dictionaries-remove_keys.rst.j2 create mode 100644 docs/docsite/helper/remove_keys/playbook.yml create mode 100644 docs/docsite/helper/remove_keys/remove_keys.rst.sha1 create mode 100644 docs/docsite/helper/remove_keys/remove_keys.rst.sha1.license create mode 100644 docs/docsite/helper/remove_keys/tests.yml.sha1 create mode 100644 docs/docsite/helper/remove_keys/tests.yml.sha1.license create mode 100644 docs/docsite/helper/replace_keys/README.md create mode 100644 docs/docsite/helper/replace_keys/filter_guide-abstract_informations-lists_of_dictionaries-replace_keys.rst.j2 create mode 100644 docs/docsite/helper/replace_keys/playbook.yml create mode 100644 docs/docsite/helper/replace_keys/replace_keys.rst.sha1 create mode 100644 docs/docsite/helper/replace_keys/replace_keys.rst.sha1.license create mode 100644 docs/docsite/helper/replace_keys/tests.yml.sha1 create mode 100644 docs/docsite/helper/replace_keys/tests.yml.sha1.license create mode 100644 docs/docsite/rst/filter_guide-abstract_informations-lists_of_dictionaries-keep_keys.rst create mode 100644 docs/docsite/rst/filter_guide-abstract_informations-lists_of_dictionaries-remove_keys.rst create mode 100644 docs/docsite/rst/filter_guide-abstract_informations-lists_of_dictionaries-replace_keys.rst create mode 100644 docs/docsite/rst/filter_guide-abstract_informations-lists_of_dictionaries.rst delete mode 100644 tests/integration/targets/filter_keep_keys/tasks/keep_keys.yml create mode 100644 tests/integration/targets/filter_keep_keys/tasks/tests.yml create mode 100644 tests/integration/targets/filter_keep_keys/templates/default.j2 create mode 100644 tests/integration/targets/filter_keep_keys/templates/default.j2.license create mode 100644 tests/integration/targets/filter_keep_keys/templates/mp.j2 create mode 100644 tests/integration/targets/filter_keep_keys/templates/mp.j2.license delete mode 100644 tests/integration/targets/filter_keep_keys/vars/main.yml create mode 100644 tests/integration/targets/filter_keep_keys/vars/main/tests.yml delete mode 100644 tests/integration/targets/filter_remove_keys/tasks/remove_keys.yml create mode 100644 tests/integration/targets/filter_remove_keys/tasks/tests.yml create mode 100644 tests/integration/targets/filter_remove_keys/templates/default.j2 create mode 100644 tests/integration/targets/filter_remove_keys/templates/default.j2.license create mode 100644 tests/integration/targets/filter_remove_keys/templates/mp.j2 create mode 100644 tests/integration/targets/filter_remove_keys/templates/mp.j2.license delete mode 100644 tests/integration/targets/filter_remove_keys/vars/main.yml create mode 100644 tests/integration/targets/filter_remove_keys/vars/main/tests.yml delete mode 100644 tests/integration/targets/filter_replace_keys/tasks/fn-test-replace_keys.yml delete mode 100644 tests/integration/targets/filter_replace_keys/tasks/replace_keys.yml create mode 100644 tests/integration/targets/filter_replace_keys/tasks/tests.yml create mode 100644 tests/integration/targets/filter_replace_keys/templates/default.j2 create mode 100644 tests/integration/targets/filter_replace_keys/templates/default.j2.license create mode 100644 tests/integration/targets/filter_replace_keys/templates/mp.j2 create mode 100644 tests/integration/targets/filter_replace_keys/templates/mp.j2.license delete mode 100644 tests/integration/targets/filter_replace_keys/vars/main.yml create mode 100644 tests/integration/targets/filter_replace_keys/vars/main/tests.yml diff --git a/.github/BOTMETA.yml b/.github/BOTMETA.yml index faedb42605..17659231fb 100644 --- a/.github/BOTMETA.yml +++ b/.github/BOTMETA.yml @@ -1444,6 +1444,14 @@ files: maintainers: felixfontein docs/docsite/rst/filter_guide_abstract_informations_lists_helper.rst: maintainers: cfiehe + docs/docsite/rst/filter_guide-abstract_informations-lists_of_dictionaries-keep_keys.rst: + maintainers: vbotka + docs/docsite/rst/filter_guide-abstract_informations-lists_of_dictionaries-remove_keys.rst: + maintainers: vbotka + docs/docsite/rst/filter_guide-abstract_informations-lists_of_dictionaries-replace_keys.rst: + maintainers: vbotka + docs/docsite/rst/filter_guide-abstract_informations-lists_of_dictionaries.rst: + maintainers: vbotka docs/docsite/rst/filter_guide_abstract_informations_merging_lists_of_dictionaries.rst: maintainers: vbotka docs/docsite/rst/filter_guide_conversions.rst: diff --git a/docs/docsite/helper/keep_keys/README.md b/docs/docsite/helper/keep_keys/README.md new file mode 100644 index 0000000000..69a4076ef9 --- /dev/null +++ b/docs/docsite/helper/keep_keys/README.md @@ -0,0 +1,61 @@ + + +# Docs helper. Create RST file. + +The playbook `playbook.yml` writes a RST file that can be used in +docs/docsite/rst. The usage of this helper is recommended but not +mandatory. You can stop reading here and update the RST file manually +if you don't want to use this helper. + +## Run the playbook + +If you want to generate the RST file by this helper fit the variables +in the playbook and the template to your needs. Then, run the play + +```sh +shell> ansible-playbook playbook.yml +``` + +## Copy RST to docs/docsite/rst + +Copy the RST file to `docs/docsite/rst` and remove it from this +directory. + +## Update the checksums + +Substitute the variables and run the below commands + +```sh +shell> sha1sum {{ target_vars }} > {{ target_sha1 }} +shell> sha1sum {{ file_rst }} > {{ file_sha1 }} +``` + +## Playbook explained + +The playbook includes the variable *tests* from the integration tests +and creates the RST file from the template. The playbook will +terminate if: + +* The file with the variable *tests* was changed +* The RST file was changed + +This means that this helper is probably not up to date. + +### The file with the variable *tests* was changed + +This means that somebody updated the integration tests. Review the +changes and update the template if needed. Update the checksum to pass +the integrity test. The playbook message provides you with the +command. + +### The RST file was changed + +This means that somebody updated the RST file manually. Review the +changes and update the template. Update the checksum to pass the +integrity test. The playbook message provides you with the +command. Make sure that the updated template will create identical RST +file. Only then apply your changes. diff --git a/docs/docsite/helper/keep_keys/filter_guide-abstract_informations-lists_of_dictionaries-keep_keys.rst.j2 b/docs/docsite/helper/keep_keys/filter_guide-abstract_informations-lists_of_dictionaries-keep_keys.rst.j2 new file mode 100644 index 0000000000..77281549ba --- /dev/null +++ b/docs/docsite/helper/keep_keys/filter_guide-abstract_informations-lists_of_dictionaries-keep_keys.rst.j2 @@ -0,0 +1,80 @@ +.. + 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 + +keep_keys +""""""""" + +Use the filter :ansplugin:`community.general.keep_keys#filter` if you have a list of dictionaries and want to keep certain keys only. + +.. note:: The output of the examples in this section use the YAML callback plugin. Quoting: "Ansible output that can be quite a bit easier to read than the default JSON formatting." See :ansplugin:`the documentation for the community.general.yaml callback plugin `. + + +Let us use the below list in the following examples: + +.. code-block:: yaml + + input: + {{ tests.0.input | to_yaml(indent=2) | indent(5) }} + +{% for i in tests[0:1]|subelements('group') %} +* {{ i.1.d }} + +.. code-block:: yaml+jinja + :emphasize-lines: 1 + + target: {{ i.1.tt }} + result: "{{ lookup('file', target ~ '/templates/' ~ i.0.template) }}" + +{% endfor %} + +gives + +.. code-block:: yaml + :emphasize-lines: 1- + + result: + {{ tests.0.result | to_yaml(indent=2) | indent(5) }} + +.. versionadded:: 9.1.0 + +* The results of the below examples 1-5 are all the same: + +.. code-block:: yaml + :emphasize-lines: 1- + + result: + {{ tests.1.result | to_yaml(indent=2) | indent(5) }} + +{% for i in tests[1:2]|subelements('group') %} +{{ loop.index }}. {{ i.1.d }} + +.. code-block:: yaml+jinja + :emphasize-lines: 1,2 + + mp: {{ i.1.mp }} + target: {{ i.1.tt }} + result: "{{ lookup('file', target ~ '/templates/' ~ i.0.template) }}" + +{% endfor %} + +* The results of the below examples 6-9 are all the same: + +.. code-block:: yaml + :emphasize-lines: 1- + + result: + {{ tests.2.result | to_yaml(indent=2) | indent(5) }} + +{% for i in tests[2:3]|subelements('group') %} +{{ loop.index + 5 }}. {{ i.1.d }} + +.. code-block:: yaml+jinja + :emphasize-lines: 1,2 + + mp: {{ i.1.mp }} + target: {{ i.1.tt }} + result: "{{ lookup('file', target ~ '/templates/' ~ i.0.template) }}" + +{% endfor %} diff --git a/docs/docsite/helper/keep_keys/keep_keys.rst.sha1 b/docs/docsite/helper/keep_keys/keep_keys.rst.sha1 new file mode 100644 index 0000000000..532c6a192c --- /dev/null +++ b/docs/docsite/helper/keep_keys/keep_keys.rst.sha1 @@ -0,0 +1 @@ +8690afce792abc95693c2f61f743ee27388b1592 ../../rst/filter_guide-abstract_informations-lists_of_dictionaries-keep_keys.rst diff --git a/docs/docsite/helper/keep_keys/keep_keys.rst.sha1.license b/docs/docsite/helper/keep_keys/keep_keys.rst.sha1.license new file mode 100644 index 0000000000..a1390a69ed --- /dev/null +++ b/docs/docsite/helper/keep_keys/keep_keys.rst.sha1.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 diff --git a/docs/docsite/helper/keep_keys/playbook.yml b/docs/docsite/helper/keep_keys/playbook.yml new file mode 100644 index 0000000000..75ef90385b --- /dev/null +++ b/docs/docsite/helper/keep_keys/playbook.yml @@ -0,0 +1,79 @@ +--- +# 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 + +# - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - +# Create docs REST files +# shell> ansible-playbook playbook.yml +# +# Proofread and copy created *.rst file into the directory +# docs/docsite/rst. Do not add *.rst in this directory to the version +# control. +# +# - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - +# community.general/docs/docsite/helper/keep_keys/playbook.yml + +- name: Create RST file for docs/docsite/rst + hosts: localhost + gather_facts: false + + vars: + + plugin: keep_keys + plugin_type: filter + docs_path: + - filter_guide + - abstract_informations + - lists_of_dictionaries + + file_base: "{{ (docs_path + [plugin]) | join('-') }}" + file_rst: ../../rst/{{ file_base }}.rst + file_sha1: "{{ plugin }}.rst.sha1" + + target: "../../../../tests/integration/targets/{{ plugin_type }}_{{ plugin }}" + target_vars: "{{ target }}/vars/main/tests.yml" + target_sha1: tests.yml.sha1 + + tasks: + + - name: Test integrity tests.yml + when: + - integrity | d(true) | bool + - lookup('file', target_sha1) != lookup('pipe', 'sha1sum ' ~ target_vars) + block: + + - name: Changed tests.yml + ansible.builtin.debug: + msg: | + Changed {{ target_vars }} + Review the changes and update {{ target_sha1 }} + shell> sha1sum {{ target_vars }} > {{ target_sha1 }} + + - name: Changed tests.yml end host + ansible.builtin.meta: end_play + + - name: Test integrity RST file + when: + - integrity | d(true) | bool + - lookup('file', file_sha1) != lookup('pipe', 'sha1sum ' ~ file_rst) + block: + + - name: Changed RST file + ansible.builtin.debug: + msg: | + Changed {{ file_rst }} + Review the changes and update {{ file_sha1 }} + shell> sha1sum {{ file_rst }} > {{ file_sha1 }} + + - name: Changed RST file end host + ansible.builtin.meta: end_play + + - name: Include target vars + include_vars: + file: "{{ target_vars }}" + + - name: Create RST file + ansible.builtin.template: + src: "{{ file_base }}.rst.j2" + dest: "{{ file_base }}.rst" diff --git a/docs/docsite/helper/keep_keys/tests.yml.sha1 b/docs/docsite/helper/keep_keys/tests.yml.sha1 new file mode 100644 index 0000000000..fcf41a4347 --- /dev/null +++ b/docs/docsite/helper/keep_keys/tests.yml.sha1 @@ -0,0 +1 @@ +c6fc4ee2017d9222675bcd13cc4f88ba8d14f38d ../../../../tests/integration/targets/filter_keep_keys/vars/main/tests.yml diff --git a/docs/docsite/helper/keep_keys/tests.yml.sha1.license b/docs/docsite/helper/keep_keys/tests.yml.sha1.license new file mode 100644 index 0000000000..a1390a69ed --- /dev/null +++ b/docs/docsite/helper/keep_keys/tests.yml.sha1.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 diff --git a/docs/docsite/helper/remove_keys/README.md b/docs/docsite/helper/remove_keys/README.md new file mode 100644 index 0000000000..69a4076ef9 --- /dev/null +++ b/docs/docsite/helper/remove_keys/README.md @@ -0,0 +1,61 @@ + + +# Docs helper. Create RST file. + +The playbook `playbook.yml` writes a RST file that can be used in +docs/docsite/rst. The usage of this helper is recommended but not +mandatory. You can stop reading here and update the RST file manually +if you don't want to use this helper. + +## Run the playbook + +If you want to generate the RST file by this helper fit the variables +in the playbook and the template to your needs. Then, run the play + +```sh +shell> ansible-playbook playbook.yml +``` + +## Copy RST to docs/docsite/rst + +Copy the RST file to `docs/docsite/rst` and remove it from this +directory. + +## Update the checksums + +Substitute the variables and run the below commands + +```sh +shell> sha1sum {{ target_vars }} > {{ target_sha1 }} +shell> sha1sum {{ file_rst }} > {{ file_sha1 }} +``` + +## Playbook explained + +The playbook includes the variable *tests* from the integration tests +and creates the RST file from the template. The playbook will +terminate if: + +* The file with the variable *tests* was changed +* The RST file was changed + +This means that this helper is probably not up to date. + +### The file with the variable *tests* was changed + +This means that somebody updated the integration tests. Review the +changes and update the template if needed. Update the checksum to pass +the integrity test. The playbook message provides you with the +command. + +### The RST file was changed + +This means that somebody updated the RST file manually. Review the +changes and update the template. Update the checksum to pass the +integrity test. The playbook message provides you with the +command. Make sure that the updated template will create identical RST +file. Only then apply your changes. diff --git a/docs/docsite/helper/remove_keys/filter_guide-abstract_informations-lists_of_dictionaries-remove_keys.rst.j2 b/docs/docsite/helper/remove_keys/filter_guide-abstract_informations-lists_of_dictionaries-remove_keys.rst.j2 new file mode 100644 index 0000000000..62b25c344c --- /dev/null +++ b/docs/docsite/helper/remove_keys/filter_guide-abstract_informations-lists_of_dictionaries-remove_keys.rst.j2 @@ -0,0 +1,80 @@ +.. + 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 + +remove_keys +""""""""""" + +Use the filter :ansplugin:`community.general.remove_keys#filter` if you have a list of dictionaries and want to remove certain keys. + +.. note:: The output of the examples in this section use the YAML callback plugin. Quoting: "Ansible output that can be quite a bit easier to read than the default JSON formatting." See See :ansplugin:`the documentation for the community.general.yaml callback plugin `. + + +Let us use the below list in the following examples: + +.. code-block:: yaml + + input: + {{ tests.0.input | to_yaml(indent=2) | indent(5) }} + +{% for i in tests[0:1]|subelements('group') %} +* {{ i.1.d }} + +.. code-block:: yaml+jinja + :emphasize-lines: 1 + + target: {{ i.1.tt }} + result: "{{ lookup('file', target ~ '/templates/' ~ i.0.template) }}" + +{% endfor %} + +gives + +.. code-block:: yaml + :emphasize-lines: 1- + + result: + {{ tests.0.result | to_yaml(indent=2) | indent(5) }} + +.. versionadded:: 9.1.0 + +* The results of the below examples 1-5 are all the same: + +.. code-block:: yaml + :emphasize-lines: 1- + + result: + {{ tests.1.result | to_yaml(indent=2) | indent(5) }} + +{% for i in tests[1:2]|subelements('group') %} +{{ loop.index }}. {{ i.1.d }} + +.. code-block:: yaml+jinja + :emphasize-lines: 1,2 + + mp: {{ i.1.mp }} + target: {{ i.1.tt }} + result: "{{ lookup('file', target ~ '/templates/' ~ i.0.template) }}" + +{% endfor %} + +* The results of the below examples 6-9 are all the same: + +.. code-block:: yaml + :emphasize-lines: 1- + + result: + {{ tests.2.result | to_yaml(indent=2) | indent(5) }} + +{% for i in tests[2:3]|subelements('group') %} +{{ loop.index + 5 }}. {{ i.1.d }} + +.. code-block:: yaml+jinja + :emphasize-lines: 1,2 + + mp: {{ i.1.mp }} + target: {{ i.1.tt }} + result: "{{ lookup('file', target ~ '/templates/' ~ i.0.template) }}" + +{% endfor %} diff --git a/docs/docsite/helper/remove_keys/playbook.yml b/docs/docsite/helper/remove_keys/playbook.yml new file mode 100644 index 0000000000..a2243d992e --- /dev/null +++ b/docs/docsite/helper/remove_keys/playbook.yml @@ -0,0 +1,79 @@ +--- +# 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 + +# - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - +# Create docs REST files +# shell> ansible-playbook playbook.yml +# +# Proofread and copy created *.rst file into the directory +# docs/docsite/rst. Do not add *.rst in this directory to the version +# control. +# +# - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - +# community.general/docs/docsite/helper/remove_keys/playbook.yml + +- name: Create RST file for docs/docsite/rst + hosts: localhost + gather_facts: false + + vars: + + plugin: remove_keys + plugin_type: filter + docs_path: + - filter_guide + - abstract_informations + - lists_of_dictionaries + + file_base: "{{ (docs_path + [plugin]) | join('-') }}" + file_rst: ../../rst/{{ file_base }}.rst + file_sha1: "{{ plugin }}.rst.sha1" + + target: "../../../../tests/integration/targets/{{ plugin_type }}_{{ plugin }}" + target_vars: "{{ target }}/vars/main/tests.yml" + target_sha1: tests.yml.sha1 + + tasks: + + - name: Test integrity tests.yml + when: + - integrity | d(true) | bool + - lookup('file', target_sha1) != lookup('pipe', 'sha1sum ' ~ target_vars) + block: + + - name: Changed tests.yml + ansible.builtin.debug: + msg: | + Changed {{ target_vars }} + Review the changes and update {{ target_sha1 }} + shell> sha1sum {{ target_vars }} > {{ target_sha1 }} + + - name: Changed tests.yml end host + ansible.builtin.meta: end_play + + - name: Test integrity RST file + when: + - integrity | d(true) | bool + - lookup('file', file_sha1) != lookup('pipe', 'sha1sum ' ~ file_rst) + block: + + - name: Changed RST file + ansible.builtin.debug: + msg: | + Changed {{ file_rst }} + Review the changes and update {{ file_sha1 }} + shell> sha1sum {{ file_rst }} > {{ file_sha1 }} + + - name: Changed RST file end host + ansible.builtin.meta: end_play + + - name: Include target vars + include_vars: + file: "{{ target_vars }}" + + - name: Create RST file + ansible.builtin.template: + src: "{{ file_base }}.rst.j2" + dest: "{{ file_base }}.rst" diff --git a/docs/docsite/helper/remove_keys/remove_keys.rst.sha1 b/docs/docsite/helper/remove_keys/remove_keys.rst.sha1 new file mode 100644 index 0000000000..a1c9e18210 --- /dev/null +++ b/docs/docsite/helper/remove_keys/remove_keys.rst.sha1 @@ -0,0 +1 @@ +3cc606b42e3d450cf6323f25930f7c5a591fa086 ../../rst/filter_guide-abstract_informations-lists_of_dictionaries-remove_keys.rst diff --git a/docs/docsite/helper/remove_keys/remove_keys.rst.sha1.license b/docs/docsite/helper/remove_keys/remove_keys.rst.sha1.license new file mode 100644 index 0000000000..a1390a69ed --- /dev/null +++ b/docs/docsite/helper/remove_keys/remove_keys.rst.sha1.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 diff --git a/docs/docsite/helper/remove_keys/tests.yml.sha1 b/docs/docsite/helper/remove_keys/tests.yml.sha1 new file mode 100644 index 0000000000..107a64d73c --- /dev/null +++ b/docs/docsite/helper/remove_keys/tests.yml.sha1 @@ -0,0 +1 @@ +0554335045f02d8c37b824355b0cf86864cee9a5 ../../../../tests/integration/targets/filter_remove_keys/vars/main/tests.yml diff --git a/docs/docsite/helper/remove_keys/tests.yml.sha1.license b/docs/docsite/helper/remove_keys/tests.yml.sha1.license new file mode 100644 index 0000000000..a1390a69ed --- /dev/null +++ b/docs/docsite/helper/remove_keys/tests.yml.sha1.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 diff --git a/docs/docsite/helper/replace_keys/README.md b/docs/docsite/helper/replace_keys/README.md new file mode 100644 index 0000000000..69a4076ef9 --- /dev/null +++ b/docs/docsite/helper/replace_keys/README.md @@ -0,0 +1,61 @@ + + +# Docs helper. Create RST file. + +The playbook `playbook.yml` writes a RST file that can be used in +docs/docsite/rst. The usage of this helper is recommended but not +mandatory. You can stop reading here and update the RST file manually +if you don't want to use this helper. + +## Run the playbook + +If you want to generate the RST file by this helper fit the variables +in the playbook and the template to your needs. Then, run the play + +```sh +shell> ansible-playbook playbook.yml +``` + +## Copy RST to docs/docsite/rst + +Copy the RST file to `docs/docsite/rst` and remove it from this +directory. + +## Update the checksums + +Substitute the variables and run the below commands + +```sh +shell> sha1sum {{ target_vars }} > {{ target_sha1 }} +shell> sha1sum {{ file_rst }} > {{ file_sha1 }} +``` + +## Playbook explained + +The playbook includes the variable *tests* from the integration tests +and creates the RST file from the template. The playbook will +terminate if: + +* The file with the variable *tests* was changed +* The RST file was changed + +This means that this helper is probably not up to date. + +### The file with the variable *tests* was changed + +This means that somebody updated the integration tests. Review the +changes and update the template if needed. Update the checksum to pass +the integrity test. The playbook message provides you with the +command. + +### The RST file was changed + +This means that somebody updated the RST file manually. Review the +changes and update the template. Update the checksum to pass the +integrity test. The playbook message provides you with the +command. Make sure that the updated template will create identical RST +file. Only then apply your changes. diff --git a/docs/docsite/helper/replace_keys/filter_guide-abstract_informations-lists_of_dictionaries-replace_keys.rst.j2 b/docs/docsite/helper/replace_keys/filter_guide-abstract_informations-lists_of_dictionaries-replace_keys.rst.j2 new file mode 100644 index 0000000000..fb0af32f2f --- /dev/null +++ b/docs/docsite/helper/replace_keys/filter_guide-abstract_informations-lists_of_dictionaries-replace_keys.rst.j2 @@ -0,0 +1,110 @@ +.. + 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 + +replace_keys +"""""""""""" + +Use the filter :ansplugin:`community.general.replace_keys#filter` if you have a list of dictionaries and want to replace certain keys. + +.. note:: The output of the examples in this section use the YAML callback plugin. Quoting: "Ansible output that can be quite a bit easier to read than the default JSON formatting." See :ansplugin:`the documentation for the community.general.yaml callback plugin `. + + +Let us use the below list in the following examples: + +.. code-block:: yaml + + input: + {{ tests.0.input | to_yaml(indent=2) | indent(5) }} + +{% for i in tests[0:1]|subelements('group') %} +* {{ i.1.d }} + +.. code-block:: yaml+jinja + :emphasize-lines: 1-3 + + target: + {{ i.1.tt | to_yaml(indent=2) | indent(5) }} + result: "{{ lookup('file', target ~ '/templates/' ~ i.0.template) }}" + +{% endfor %} + +gives + +.. code-block:: yaml + :emphasize-lines: 1- + + result: + {{ tests.0.result | to_yaml(indent=2) | indent(5) }} + +.. versionadded:: 9.1.0 + +* The results of the below examples 1-3 are all the same: + +.. code-block:: yaml + :emphasize-lines: 1- + + result: + {{ tests.1.result | to_yaml(indent=2) | indent(5) }} + +{% for i in tests[1:2]|subelements('group') %} +{{ loop.index }}. {{ i.1.d }} + +.. code-block:: yaml+jinja + :emphasize-lines: 1-4 + + mp: {{ i.1.mp }} + target: + {{ i.1.tt | to_yaml(indent=2) | indent(5) }} + result: "{{ lookup('file', target ~ '/templates/' ~ i.0.template) }}" + +{% endfor %} + +* The results of the below examples 4-5 are the same: + +.. code-block:: yaml + :emphasize-lines: 1- + + result: + {{ tests.2.result | to_yaml(indent=2) | indent(5) }} + +{% for i in tests[2:3]|subelements('group') %} +{{ loop.index + 3 }}. {{ i.1.d }} + +.. code-block:: yaml+jinja + :emphasize-lines: 1-3 + + mp: {{ i.1.mp }} + target: + {{ i.1.tt | to_yaml(indent=2) | indent(5) }} + result: "{{ lookup('file', target ~ '/templates/' ~ i.0.template) }}" + +{% endfor %} + +{% for i in tests[3:4]|subelements('group') %} +{{ loop.index + 5 }}. {{ i.1.d }} + +.. code-block:: yaml + :emphasize-lines: 1- + + input: + {{ i.0.input | to_yaml(indent=2) | indent(5) }} + +.. code-block:: yaml+jinja + :emphasize-lines: 1-4 + + mp: {{ i.1.mp }} + target: + {{ i.1.tt | to_yaml(indent=2) | indent(5) }} + result: "{{ lookup('file', target ~ '/templates/' ~ i.0.template) }}" + +gives + +.. code-block:: yaml + :emphasize-lines: 1- + + result: + {{ i.0.result | to_yaml(indent=2) | indent(5) }} + +{% endfor %} diff --git a/docs/docsite/helper/replace_keys/playbook.yml b/docs/docsite/helper/replace_keys/playbook.yml new file mode 100644 index 0000000000..3619000144 --- /dev/null +++ b/docs/docsite/helper/replace_keys/playbook.yml @@ -0,0 +1,79 @@ +--- +# 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 + +# - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - +# Create docs REST files +# shell> ansible-playbook playbook.yml +# +# Proofread and copy created *.rst file into the directory +# docs/docsite/rst. Do not add *.rst in this directory to the version +# control. +# +# - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - +# community.general/docs/docsite/helper/replace_keys/playbook.yml + +- name: Create RST file for docs/docsite/rst + hosts: localhost + gather_facts: false + + vars: + + plugin: replace_keys + plugin_type: filter + docs_path: + - filter_guide + - abstract_informations + - lists_of_dictionaries + + file_base: "{{ (docs_path + [plugin]) | join('-') }}" + file_rst: ../../rst/{{ file_base }}.rst + file_sha1: "{{ plugin }}.rst.sha1" + + target: "../../../../tests/integration/targets/{{ plugin_type }}_{{ plugin }}" + target_vars: "{{ target }}/vars/main/tests.yml" + target_sha1: tests.yml.sha1 + + tasks: + + - name: Test integrity tests.yml + when: + - integrity | d(true) | bool + - lookup('file', target_sha1) != lookup('pipe', 'sha1sum ' ~ target_vars) + block: + + - name: Changed tests.yml + ansible.builtin.debug: + msg: | + Changed {{ target_vars }} + Review the changes and update {{ target_sha1 }} + shell> sha1sum {{ target_vars }} > {{ target_sha1 }} + + - name: Changed tests.yml end host + ansible.builtin.meta: end_play + + - name: Test integrity RST file + when: + - integrity | d(true) | bool + - lookup('file', file_sha1) != lookup('pipe', 'sha1sum ' ~ file_rst) + block: + + - name: Changed RST file + ansible.builtin.debug: + msg: | + Changed {{ file_rst }} + Review the changes and update {{ file_sha1 }} + shell> sha1sum {{ file_rst }} > {{ file_sha1 }} + + - name: Changed RST file end host + ansible.builtin.meta: end_play + + - name: Include target vars + include_vars: + file: "{{ target_vars }}" + + - name: Create RST file + ansible.builtin.template: + src: "{{ file_base }}.rst.j2" + dest: "{{ file_base }}.rst" diff --git a/docs/docsite/helper/replace_keys/replace_keys.rst.sha1 b/docs/docsite/helper/replace_keys/replace_keys.rst.sha1 new file mode 100644 index 0000000000..2ae692f3cc --- /dev/null +++ b/docs/docsite/helper/replace_keys/replace_keys.rst.sha1 @@ -0,0 +1 @@ +403f23c02ac02b1c3b611cb14f9b3ba59dc3f587 ../../rst/filter_guide-abstract_informations-lists_of_dictionaries-replace_keys.rst diff --git a/docs/docsite/helper/replace_keys/replace_keys.rst.sha1.license b/docs/docsite/helper/replace_keys/replace_keys.rst.sha1.license new file mode 100644 index 0000000000..a1390a69ed --- /dev/null +++ b/docs/docsite/helper/replace_keys/replace_keys.rst.sha1.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 diff --git a/docs/docsite/helper/replace_keys/tests.yml.sha1 b/docs/docsite/helper/replace_keys/tests.yml.sha1 new file mode 100644 index 0000000000..53944ddf74 --- /dev/null +++ b/docs/docsite/helper/replace_keys/tests.yml.sha1 @@ -0,0 +1 @@ +2e54f3528c95cca746d5748f1ed7ada56ad0890e ../../../../tests/integration/targets/filter_replace_keys/vars/main/tests.yml diff --git a/docs/docsite/helper/replace_keys/tests.yml.sha1.license b/docs/docsite/helper/replace_keys/tests.yml.sha1.license new file mode 100644 index 0000000000..a1390a69ed --- /dev/null +++ b/docs/docsite/helper/replace_keys/tests.yml.sha1.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 diff --git a/docs/docsite/rst/filter_guide-abstract_informations-lists_of_dictionaries-keep_keys.rst b/docs/docsite/rst/filter_guide-abstract_informations-lists_of_dictionaries-keep_keys.rst new file mode 100644 index 0000000000..488cb2ce7d --- /dev/null +++ b/docs/docsite/rst/filter_guide-abstract_informations-lists_of_dictionaries-keep_keys.rst @@ -0,0 +1,151 @@ +.. + 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 + +keep_keys +""""""""" + +Use the filter :ansplugin:`community.general.keep_keys#filter` if you have a list of dictionaries and want to keep certain keys only. + +.. note:: The output of the examples in this section use the YAML callback plugin. Quoting: "Ansible output that can be quite a bit easier to read than the default JSON formatting." See :ansplugin:`the documentation for the community.general.yaml callback plugin `. + + +Let us use the below list in the following examples: + +.. code-block:: yaml + + input: + - k0_x0: A0 + k1_x1: B0 + k2_x2: [C0] + k3_x3: foo + - k0_x0: A1 + k1_x1: B1 + k2_x2: [C1] + k3_x3: bar + + +* By default, match keys that equal any of the items in the target. + +.. code-block:: yaml+jinja + :emphasize-lines: 1 + + target: ['k0_x0', 'k1_x1'] + result: "{{ input | community.general.keep_keys(target=target) }}" + + +gives + +.. code-block:: yaml + :emphasize-lines: 1- + + result: + - {k0_x0: A0, k1_x1: B0} + - {k0_x0: A1, k1_x1: B1} + + +.. versionadded:: 9.1.0 + +* The results of the below examples 1-5 are all the same: + +.. code-block:: yaml + :emphasize-lines: 1- + + result: + - {k0_x0: A0, k1_x1: B0} + - {k0_x0: A1, k1_x1: B1} + + +1. Match keys that equal any of the items in the target. + +.. code-block:: yaml+jinja + :emphasize-lines: 1,2 + + mp: equal + target: ['k0_x0', 'k1_x1'] + result: "{{ input | community.general.keep_keys(target=target, matching_parameter=mp) }}" + +2. Match keys that start with any of the items in the target. + +.. code-block:: yaml+jinja + :emphasize-lines: 1,2 + + mp: starts_with + target: ['k0', 'k1'] + result: "{{ input | community.general.keep_keys(target=target, matching_parameter=mp) }}" + +3. Match keys that end with any of the items in target. + +.. code-block:: yaml+jinja + :emphasize-lines: 1,2 + + mp: ends_with + target: ['x0', 'x1'] + result: "{{ input | community.general.keep_keys(target=target, matching_parameter=mp) }}" + +4. Match keys by the regex. + +.. code-block:: yaml+jinja + :emphasize-lines: 1,2 + + mp: regex + target: ['^.*[01]_x.*$'] + result: "{{ input | community.general.keep_keys(target=target, matching_parameter=mp) }}" + +5. Match keys by the regex. + +.. code-block:: yaml+jinja + :emphasize-lines: 1,2 + + mp: regex + target: ^.*[01]_x.*$ + result: "{{ input | community.general.keep_keys(target=target, matching_parameter=mp) }}" + + +* The results of the below examples 6-9 are all the same: + +.. code-block:: yaml + :emphasize-lines: 1- + + result: + - {k0_x0: A0} + - {k0_x0: A1} + + +6. Match keys that equal the target. + +.. code-block:: yaml+jinja + :emphasize-lines: 1,2 + + mp: equal + target: k0_x0 + result: "{{ input | community.general.keep_keys(target=target, matching_parameter=mp) }}" + +7. Match keys that start with the target. + +.. code-block:: yaml+jinja + :emphasize-lines: 1,2 + + mp: starts_with + target: k0 + result: "{{ input | community.general.keep_keys(target=target, matching_parameter=mp) }}" + +8. Match keys that end with the target. + +.. code-block:: yaml+jinja + :emphasize-lines: 1,2 + + mp: ends_with + target: x0 + result: "{{ input | community.general.keep_keys(target=target, matching_parameter=mp) }}" + +9. Match keys by the regex. + +.. code-block:: yaml+jinja + :emphasize-lines: 1,2 + + mp: regex + target: ^.*0_x.*$ + result: "{{ input | community.general.keep_keys(target=target, matching_parameter=mp) }}" + diff --git a/docs/docsite/rst/filter_guide-abstract_informations-lists_of_dictionaries-remove_keys.rst b/docs/docsite/rst/filter_guide-abstract_informations-lists_of_dictionaries-remove_keys.rst new file mode 100644 index 0000000000..03d4710f3a --- /dev/null +++ b/docs/docsite/rst/filter_guide-abstract_informations-lists_of_dictionaries-remove_keys.rst @@ -0,0 +1,159 @@ +.. + 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 + +remove_keys +""""""""""" + +Use the filter :ansplugin:`community.general.remove_keys#filter` if you have a list of dictionaries and want to remove certain keys. + +.. note:: The output of the examples in this section use the YAML callback plugin. Quoting: "Ansible output that can be quite a bit easier to read than the default JSON formatting." See See :ansplugin:`the documentation for the community.general.yaml callback plugin `. + + +Let us use the below list in the following examples: + +.. code-block:: yaml + + input: + - k0_x0: A0 + k1_x1: B0 + k2_x2: [C0] + k3_x3: foo + - k0_x0: A1 + k1_x1: B1 + k2_x2: [C1] + k3_x3: bar + + +* By default, match keys that equal any of the items in the target. + +.. code-block:: yaml+jinja + :emphasize-lines: 1 + + target: ['k0_x0', 'k1_x1'] + result: "{{ input | community.general.remove_keys(target=target) }}" + + +gives + +.. code-block:: yaml + :emphasize-lines: 1- + + result: + - k2_x2: [C0] + k3_x3: foo + - k2_x2: [C1] + k3_x3: bar + + +.. versionadded:: 9.1.0 + +* The results of the below examples 1-5 are all the same: + +.. code-block:: yaml + :emphasize-lines: 1- + + result: + - k2_x2: [C0] + k3_x3: foo + - k2_x2: [C1] + k3_x3: bar + + +1. Match keys that equal any of the items in the target. + +.. code-block:: yaml+jinja + :emphasize-lines: 1,2 + + mp: equal + target: ['k0_x0', 'k1_x1'] + result: "{{ input | community.general.remove_keys(target=target, matching_parameter=mp) }}" + +2. Match keys that start with any of the items in the target. + +.. code-block:: yaml+jinja + :emphasize-lines: 1,2 + + mp: starts_with + target: ['k0', 'k1'] + result: "{{ input | community.general.remove_keys(target=target, matching_parameter=mp) }}" + +3. Match keys that end with any of the items in target. + +.. code-block:: yaml+jinja + :emphasize-lines: 1,2 + + mp: ends_with + target: ['x0', 'x1'] + result: "{{ input | community.general.remove_keys(target=target, matching_parameter=mp) }}" + +4. Match keys by the regex. + +.. code-block:: yaml+jinja + :emphasize-lines: 1,2 + + mp: regex + target: ['^.*[01]_x.*$'] + result: "{{ input | community.general.remove_keys(target=target, matching_parameter=mp) }}" + +5. Match keys by the regex. + +.. code-block:: yaml+jinja + :emphasize-lines: 1,2 + + mp: regex + target: ^.*[01]_x.*$ + result: "{{ input | community.general.remove_keys(target=target, matching_parameter=mp) }}" + + +* The results of the below examples 6-9 are all the same: + +.. code-block:: yaml + :emphasize-lines: 1- + + result: + - k1_x1: B0 + k2_x2: [C0] + k3_x3: foo + - k1_x1: B1 + k2_x2: [C1] + k3_x3: bar + + +6. Match keys that equal the target. + +.. code-block:: yaml+jinja + :emphasize-lines: 1,2 + + mp: equal + target: k0_x0 + result: "{{ input | community.general.remove_keys(target=target, matching_parameter=mp) }}" + +7. Match keys that start with the target. + +.. code-block:: yaml+jinja + :emphasize-lines: 1,2 + + mp: starts_with + target: k0 + result: "{{ input | community.general.remove_keys(target=target, matching_parameter=mp) }}" + +8. Match keys that end with the target. + +.. code-block:: yaml+jinja + :emphasize-lines: 1,2 + + mp: ends_with + target: x0 + result: "{{ input | community.general.remove_keys(target=target, matching_parameter=mp) }}" + +9. Match keys by the regex. + +.. code-block:: yaml+jinja + :emphasize-lines: 1,2 + + mp: regex + target: ^.*0_x.*$ + result: "{{ input | community.general.remove_keys(target=target, matching_parameter=mp) }}" + diff --git a/docs/docsite/rst/filter_guide-abstract_informations-lists_of_dictionaries-replace_keys.rst b/docs/docsite/rst/filter_guide-abstract_informations-lists_of_dictionaries-replace_keys.rst new file mode 100644 index 0000000000..ba1bcad502 --- /dev/null +++ b/docs/docsite/rst/filter_guide-abstract_informations-lists_of_dictionaries-replace_keys.rst @@ -0,0 +1,175 @@ +.. + 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 + +replace_keys +"""""""""""" + +Use the filter :ansplugin:`community.general.replace_keys#filter` if you have a list of dictionaries and want to replace certain keys. + +.. note:: The output of the examples in this section use the YAML callback plugin. Quoting: "Ansible output that can be quite a bit easier to read than the default JSON formatting." See :ansplugin:`the documentation for the community.general.yaml callback plugin `. + + +Let us use the below list in the following examples: + +.. code-block:: yaml + + input: + - k0_x0: A0 + k1_x1: B0 + k2_x2: [C0] + k3_x3: foo + - k0_x0: A1 + k1_x1: B1 + k2_x2: [C1] + k3_x3: bar + + +* By default, match keys that equal any of the attributes before. + +.. code-block:: yaml+jinja + :emphasize-lines: 1-3 + + target: + - {after: a0, before: k0_x0} + - {after: a1, before: k1_x1} + + result: "{{ input | community.general.replace_keys(target=target) }}" + + +gives + +.. code-block:: yaml + :emphasize-lines: 1- + + result: + - a0: A0 + a1: B0 + k2_x2: [C0] + k3_x3: foo + - a0: A1 + a1: B1 + k2_x2: [C1] + k3_x3: bar + + +.. versionadded:: 9.1.0 + +* The results of the below examples 1-3 are all the same: + +.. code-block:: yaml + :emphasize-lines: 1- + + result: + - a0: A0 + a1: B0 + k2_x2: [C0] + k3_x3: foo + - a0: A1 + a1: B1 + k2_x2: [C1] + k3_x3: bar + + +1. Replace keys that starts with any of the attributes before. + +.. code-block:: yaml+jinja + :emphasize-lines: 1-4 + + mp: starts_with + target: + - {after: a0, before: k0} + - {after: a1, before: k1} + + result: "{{ input | community.general.replace_keys(target=target, matching_parameter=mp) }}" + +2. Replace keys that ends with any of the attributes before. + +.. code-block:: yaml+jinja + :emphasize-lines: 1-4 + + mp: ends_with + target: + - {after: a0, before: x0} + - {after: a1, before: x1} + + result: "{{ input | community.general.replace_keys(target=target, matching_parameter=mp) }}" + +3. Replace keys that match any regex of the attributes before. + +.. code-block:: yaml+jinja + :emphasize-lines: 1-4 + + mp: regex + target: + - {after: a0, before: ^.*0_x.*$} + - {after: a1, before: ^.*1_x.*$} + + result: "{{ input | community.general.replace_keys(target=target, matching_parameter=mp) }}" + + +* The results of the below examples 4-5 are the same: + +.. code-block:: yaml + :emphasize-lines: 1- + + result: + - {X: foo} + - {X: bar} + + +4. If more keys match the same attribute before the last one will be used. + +.. code-block:: yaml+jinja + :emphasize-lines: 1-3 + + mp: regex + target: + - {after: X, before: ^.*_x.*$} + + result: "{{ input | community.general.replace_keys(target=target, matching_parameter=mp) }}" + +5. If there are items with equal attribute before the first one will be used. + +.. code-block:: yaml+jinja + :emphasize-lines: 1-3 + + mp: regex + target: + - {after: X, before: ^.*_x.*$} + - {after: Y, before: ^.*_x.*$} + + result: "{{ input | community.general.replace_keys(target=target, matching_parameter=mp) }}" + + +6. If there are more matches for a key the first one will be used. + +.. code-block:: yaml + :emphasize-lines: 1- + + input: + - {aaa1: A, bbb1: B, ccc1: C} + - {aaa2: D, bbb2: E, ccc2: F} + + +.. code-block:: yaml+jinja + :emphasize-lines: 1-4 + + mp: starts_with + target: + - {after: X, before: a} + - {after: Y, before: aa} + + result: "{{ input | community.general.replace_keys(target=target, matching_parameter=mp) }}" + +gives + +.. code-block:: yaml + :emphasize-lines: 1- + + result: + - {X: A, bbb1: B, ccc1: C} + - {X: D, bbb2: E, ccc2: F} + + diff --git a/docs/docsite/rst/filter_guide-abstract_informations-lists_of_dictionaries.rst b/docs/docsite/rst/filter_guide-abstract_informations-lists_of_dictionaries.rst new file mode 100644 index 0000000000..42737c44b7 --- /dev/null +++ b/docs/docsite/rst/filter_guide-abstract_informations-lists_of_dictionaries.rst @@ -0,0 +1,18 @@ +.. + 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 + +.. _ansible_collections.community.general.docsite.filter_guide.filter_guide_abstract_informations.lists_of_dicts: + +Lists of dictionaries +^^^^^^^^^^^^^^^^^^^^^ + +Filters to manage keys in a list of dictionaries: + +.. toctree:: + :maxdepth: 1 + + filter_guide-abstract_informations-lists_of_dictionaries-keep_keys + filter_guide-abstract_informations-lists_of_dictionaries-remove_keys + filter_guide-abstract_informations-lists_of_dictionaries-replace_keys diff --git a/docs/docsite/rst/filter_guide_abstract_informations.rst b/docs/docsite/rst/filter_guide_abstract_informations.rst index cac85089a0..818c09f02c 100644 --- a/docs/docsite/rst/filter_guide_abstract_informations.rst +++ b/docs/docsite/rst/filter_guide_abstract_informations.rst @@ -11,6 +11,7 @@ Abstract transformations filter_guide_abstract_informations_dictionaries filter_guide_abstract_informations_grouping + filter_guide-abstract_informations-lists_of_dictionaries filter_guide_abstract_informations_merging_lists_of_dictionaries filter_guide_abstract_informations_lists_helper filter_guide_abstract_informations_counting_elements_in_sequence diff --git a/tests/integration/targets/filter_keep_keys/tasks/keep_keys.yml b/tests/integration/targets/filter_keep_keys/tasks/keep_keys.yml deleted file mode 100644 index 94825c9d61..0000000000 --- a/tests/integration/targets/filter_keep_keys/tasks/keep_keys.yml +++ /dev/null @@ -1,79 +0,0 @@ ---- -# 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: Debug ansible_version - ansible.builtin.debug: - var: ansible_version - when: not quite_test | d(true) | bool - tags: ansible_version - -- name: Test keep keys equal (default) - ansible.builtin.assert: - that: - - (rr | difference(result1) | length) == 0 - success_msg: | - [OK] result: - {{ rr | to_yaml }} - fail_msg: | - [ERR] result: - {{ rr | to_yaml }} - quiet: "{{ quiet_test | d(true) | bool }}" - vars: - rr: "{{ list1 | community.general.keep_keys(target=tt) }}" - tt: [k0_x0, k1_x1] - tags: equal_default - -- name: Test keep keys regex string - ansible.builtin.assert: - that: - - (rr | difference(result1) | length) == 0 - success_msg: | - [OK] result: - {{ rr | to_yaml }} - fail_msg: | - [ERR] result: - {{ rr | to_yaml }} - quiet: "{{ quiet_test | d(true) | bool }}" - vars: - rr: "{{ list1 | community.general.keep_keys(target=tt, matching_parameter=mp) }}" - mp: regex - tt: '^.*[01]_x.*$' - tags: regex_string - -- name: Test keep keys targets1 - ansible.builtin.assert: - that: - - (rr | difference(result1) | length) == 0 - success_msg: | - [OK] result: - {{ rr | to_yaml }} - fail_msg: | - [ERR] result: - {{ rr | to_yaml }} - quiet: "{{ quiet_test | d(true) | bool }}" - loop: "{{ targets1 }}" - loop_control: - label: "{{ item.mp }}: {{ item.tt }}" - vars: - rr: "{{ list1 | community.general.keep_keys(target=item.tt, matching_parameter=item.mp) }}" - tags: targets1 - -- name: Test keep keys targets2 - ansible.builtin.assert: - that: - - (rr | difference(result2) | length) == 0 - success_msg: | - [OK] result: - {{ rr | to_yaml }} - fail_msg: | - [ERR] result: - {{ rr | to_yaml }} - quiet: "{{ quiet_test | d(true) | bool }}" - loop: "{{ targets2 }}" - loop_control: - label: "{{ item.mp }}: {{ item.tt }}" - vars: - rr: "{{ list2 | community.general.keep_keys(target=item.tt, matching_parameter=item.mp) }}" - tags: targets2 diff --git a/tests/integration/targets/filter_keep_keys/tasks/main.yml b/tests/integration/targets/filter_keep_keys/tasks/main.yml index 23457d1e11..9c0674780e 100644 --- a/tests/integration/targets/filter_keep_keys/tasks/main.yml +++ b/tests/integration/targets/filter_keep_keys/tasks/main.yml @@ -3,5 +3,5 @@ # 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: Test keep_keys - import_tasks: keep_keys.yml +- name: Tests + import_tasks: tests.yml diff --git a/tests/integration/targets/filter_keep_keys/tasks/tests.yml b/tests/integration/targets/filter_keep_keys/tasks/tests.yml new file mode 100644 index 0000000000..fa821702f0 --- /dev/null +++ b/tests/integration/targets/filter_keep_keys/tasks/tests.yml @@ -0,0 +1,31 @@ +--- +# 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: Debug ansible_version + ansible.builtin.debug: + var: ansible_version + when: not quite_test | d(true) | bool + tags: ansible_version + +- name: Tests + ansible.builtin.assert: + that: + - (result | difference(i.0.result) | length) == 0 + success_msg: | + [OK] result: + {{ result | to_yaml }} + fail_msg: | + [ERR] result: + {{ result | to_yaml }} + quiet: "{{ quiet_test | d(true) | bool }}" + loop: "{{ tests | subelements('group') }}" + loop_control: + loop_var: i + label: "{{ i.1.mp | d('default') }}: {{ i.1.tt }}" + vars: + input: "{{ i.0.input }}" + target: "{{ i.1.tt }}" + mp: "{{ i.1.mp | d('default') }}" + result: "{{ lookup('template', i.0.template) }}" diff --git a/tests/integration/targets/filter_keep_keys/templates/default.j2 b/tests/integration/targets/filter_keep_keys/templates/default.j2 new file mode 100644 index 0000000000..cb1232f9ee --- /dev/null +++ b/tests/integration/targets/filter_keep_keys/templates/default.j2 @@ -0,0 +1 @@ +{{ input | community.general.keep_keys(target=target) }} diff --git a/tests/integration/targets/filter_keep_keys/templates/default.j2.license b/tests/integration/targets/filter_keep_keys/templates/default.j2.license new file mode 100644 index 0000000000..a1390a69ed --- /dev/null +++ b/tests/integration/targets/filter_keep_keys/templates/default.j2.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 diff --git a/tests/integration/targets/filter_keep_keys/templates/mp.j2 b/tests/integration/targets/filter_keep_keys/templates/mp.j2 new file mode 100644 index 0000000000..753698d420 --- /dev/null +++ b/tests/integration/targets/filter_keep_keys/templates/mp.j2 @@ -0,0 +1 @@ +{{ input | community.general.keep_keys(target=target, matching_parameter=mp) }} diff --git a/tests/integration/targets/filter_keep_keys/templates/mp.j2.license b/tests/integration/targets/filter_keep_keys/templates/mp.j2.license new file mode 100644 index 0000000000..a1390a69ed --- /dev/null +++ b/tests/integration/targets/filter_keep_keys/templates/mp.j2.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 diff --git a/tests/integration/targets/filter_keep_keys/vars/main.yml b/tests/integration/targets/filter_keep_keys/vars/main.yml deleted file mode 100644 index b25325253d..0000000000 --- a/tests/integration/targets/filter_keep_keys/vars/main.yml +++ /dev/null @@ -1,33 +0,0 @@ ---- -# 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 - -targets1: - - {mp: equal, tt: [k0_x0, k1_x1]} - - {mp: starts_with, tt: [k0, k1]} - - {mp: ends_with, tt: [x0, x1]} - - {mp: regex, tt: ['^.*[01]_x.*$']} - - {mp: regex, tt: '^.*[01]_x.*$'} - -list1: - - {k0_x0: A0, k1_x1: B0, k2_x2: [C0], k3_x3: foo} - - {k0_x0: A1, k1_x1: B1, k2_x2: [C1], k3_x3: bar} - -result1: - - {k0_x0: A0, k1_x1: B0} - - {k0_x0: A1, k1_x1: B1} - -targets2: - - {mp: equal, tt: k0_x0} - - {mp: starts_with, tt: k0} - - {mp: ends_with, tt: x0} - - {mp: regex, tt: '^.*0_x.*$'} - -list2: - - {k0_x0: A0, k1_x1: B0, k2_x2: [C0], k3_x3: foo} - - {k0_x0: A1, k1_x1: B1, k2_x2: [C1], k3_x3: bar} - -result2: - - {k0_x0: A0} - - {k0_x0: A1} diff --git a/tests/integration/targets/filter_keep_keys/vars/main/tests.yml b/tests/integration/targets/filter_keep_keys/vars/main/tests.yml new file mode 100644 index 0000000000..f1abceddda --- /dev/null +++ b/tests/integration/targets/filter_keep_keys/vars/main/tests.yml @@ -0,0 +1,40 @@ +--- +# 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: + - template: default.j2 + group: + - {tt: [k0_x0, k1_x1], d: 'By default, match keys that equal any of the items in the target.'} + input: + - {k0_x0: A0, k1_x1: B0, k2_x2: [C0], k3_x3: foo} + - {k0_x0: A1, k1_x1: B1, k2_x2: [C1], k3_x3: bar} + result: + - {k0_x0: A0, k1_x1: B0} + - {k0_x0: A1, k1_x1: B1} + - template: mp.j2 + group: + - {mp: equal, tt: [k0_x0, k1_x1], d: Match keys that equal any of the items in the target.} + - {mp: starts_with, tt: [k0, k1], d: Match keys that start with any of the items in the target.} + - {mp: ends_with, tt: [x0, x1], d: Match keys that end with any of the items in target.} + - {mp: regex, tt: ['^.*[01]_x.*$'], d: Match keys by the regex.} + - {mp: regex, tt: '^.*[01]_x.*$', d: Match keys by the regex.} + input: + - {k0_x0: A0, k1_x1: B0, k2_x2: [C0], k3_x3: foo} + - {k0_x0: A1, k1_x1: B1, k2_x2: [C1], k3_x3: bar} + result: + - {k0_x0: A0, k1_x1: B0} + - {k0_x0: A1, k1_x1: B1} + - template: mp.j2 + group: + - {mp: equal, tt: k0_x0, d: Match keys that equal the target.} + - {mp: starts_with, tt: k0, d: Match keys that start with the target.} + - {mp: ends_with, tt: x0, d: Match keys that end with the target.} + - {mp: regex, tt: '^.*0_x.*$', d: Match keys by the regex.} + input: + - {k0_x0: A0, k1_x1: B0, k2_x2: [C0], k3_x3: foo} + - {k0_x0: A1, k1_x1: B1, k2_x2: [C1], k3_x3: bar} + result: + - {k0_x0: A0} + - {k0_x0: A1} diff --git a/tests/integration/targets/filter_remove_keys/tasks/main.yml b/tests/integration/targets/filter_remove_keys/tasks/main.yml index d4215d8c59..9c0674780e 100644 --- a/tests/integration/targets/filter_remove_keys/tasks/main.yml +++ b/tests/integration/targets/filter_remove_keys/tasks/main.yml @@ -3,5 +3,5 @@ # 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: Test remove_keys - import_tasks: remove_keys.yml +- name: Tests + import_tasks: tests.yml diff --git a/tests/integration/targets/filter_remove_keys/tasks/remove_keys.yml b/tests/integration/targets/filter_remove_keys/tasks/remove_keys.yml deleted file mode 100644 index 121cd88cfd..0000000000 --- a/tests/integration/targets/filter_remove_keys/tasks/remove_keys.yml +++ /dev/null @@ -1,79 +0,0 @@ ---- -# 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: Debug ansible_version - ansible.builtin.debug: - var: ansible_version - when: not quite_test | d(true) | bool - tags: ansible_version - -- name: Test remove keys equal (default) - ansible.builtin.assert: - that: - - (rr | difference(result1) | length) == 0 - success_msg: | - [OK] result: - {{ rr | to_yaml }} - fail_msg: | - [ERR] result: - {{ rr | to_yaml }} - quiet: "{{ quiet_test | d(true) | bool }}" - vars: - rr: "{{ list1 | community.general.remove_keys(target=tt) }}" - tt: [k0_x0, k1_x1] - tags: equal_default - -- name: Test remove keys regex string - ansible.builtin.assert: - that: - - (rr | difference(result1) | length) == 0 - success_msg: | - [OK] result: - {{ rr | to_yaml }} - fail_msg: | - [ERR] result: - {{ rr | to_yaml }} - quiet: "{{ quiet_test | d(true) | bool }}" - vars: - rr: "{{ list1 | community.general.remove_keys(target=tt, matching_parameter=mp) }}" - mp: regex - tt: '^.*[01]_x.*$' - tags: regex_string - -- name: Test remove keys targets1 - ansible.builtin.assert: - that: - - (rr | difference(result1) | length) == 0 - success_msg: | - [OK] result: - {{ rr | to_yaml }} - fail_msg: | - [ERR] result: - {{ rr | to_yaml }} - quiet: "{{ quiet_test | d(true) | bool }}" - loop: "{{ targets1 }}" - loop_control: - label: "{{ item.mp }}: {{ item.tt }}" - vars: - rr: "{{ list1 | community.general.remove_keys(target=item.tt, matching_parameter=item.mp) }}" - tags: targets1 - -- name: Test remove keys targets2 - ansible.builtin.assert: - that: - - (rr | difference(result2) | length) == 0 - success_msg: | - [OK] result: - {{ rr | to_yaml }} - fail_msg: | - [ERR] result: - {{ rr | to_yaml }} - quiet: "{{ quiet_test | d(true) | bool }}" - loop: "{{ targets2 }}" - loop_control: - label: "{{ item.mp }}: {{ item.tt }}" - vars: - rr: "{{ list2 | community.general.remove_keys(target=item.tt, matching_parameter=item.mp) }}" - tags: targets1 diff --git a/tests/integration/targets/filter_remove_keys/tasks/tests.yml b/tests/integration/targets/filter_remove_keys/tasks/tests.yml new file mode 100644 index 0000000000..fa821702f0 --- /dev/null +++ b/tests/integration/targets/filter_remove_keys/tasks/tests.yml @@ -0,0 +1,31 @@ +--- +# 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: Debug ansible_version + ansible.builtin.debug: + var: ansible_version + when: not quite_test | d(true) | bool + tags: ansible_version + +- name: Tests + ansible.builtin.assert: + that: + - (result | difference(i.0.result) | length) == 0 + success_msg: | + [OK] result: + {{ result | to_yaml }} + fail_msg: | + [ERR] result: + {{ result | to_yaml }} + quiet: "{{ quiet_test | d(true) | bool }}" + loop: "{{ tests | subelements('group') }}" + loop_control: + loop_var: i + label: "{{ i.1.mp | d('default') }}: {{ i.1.tt }}" + vars: + input: "{{ i.0.input }}" + target: "{{ i.1.tt }}" + mp: "{{ i.1.mp | d('default') }}" + result: "{{ lookup('template', i.0.template) }}" diff --git a/tests/integration/targets/filter_remove_keys/templates/default.j2 b/tests/integration/targets/filter_remove_keys/templates/default.j2 new file mode 100644 index 0000000000..0dbc26323f --- /dev/null +++ b/tests/integration/targets/filter_remove_keys/templates/default.j2 @@ -0,0 +1 @@ +{{ input | community.general.remove_keys(target=target) }} diff --git a/tests/integration/targets/filter_remove_keys/templates/default.j2.license b/tests/integration/targets/filter_remove_keys/templates/default.j2.license new file mode 100644 index 0000000000..a1390a69ed --- /dev/null +++ b/tests/integration/targets/filter_remove_keys/templates/default.j2.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 diff --git a/tests/integration/targets/filter_remove_keys/templates/mp.j2 b/tests/integration/targets/filter_remove_keys/templates/mp.j2 new file mode 100644 index 0000000000..5caa27a9b8 --- /dev/null +++ b/tests/integration/targets/filter_remove_keys/templates/mp.j2 @@ -0,0 +1 @@ +{{ input | community.general.remove_keys(target=target, matching_parameter=mp) }} diff --git a/tests/integration/targets/filter_remove_keys/templates/mp.j2.license b/tests/integration/targets/filter_remove_keys/templates/mp.j2.license new file mode 100644 index 0000000000..a1390a69ed --- /dev/null +++ b/tests/integration/targets/filter_remove_keys/templates/mp.j2.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 diff --git a/tests/integration/targets/filter_remove_keys/vars/main.yml b/tests/integration/targets/filter_remove_keys/vars/main.yml deleted file mode 100644 index a52d09a34a..0000000000 --- a/tests/integration/targets/filter_remove_keys/vars/main.yml +++ /dev/null @@ -1,33 +0,0 @@ ---- -# 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 - -targets1: - - {mp: equal, tt: [k0_x0, k1_x1]} - - {mp: starts_with, tt: [k0, k1]} - - {mp: ends_with, tt: [x0, x1]} - - {mp: regex, tt: ['^.*[01]_x.*$']} - - {mp: regex, tt: '^.*[01]_x.*$'} - -list1: - - {k0_x0: A0, k1_x1: B0, k2_x2: [C0], k3_x3: foo} - - {k0_x0: A1, k1_x1: B1, k2_x2: [C1], k3_x3: bar} - -result1: - - {k2_x2: [C0], k3_x3: foo} - - {k2_x2: [C1], k3_x3: bar} - -targets2: - - {mp: equal, tt: k0_x0} - - {mp: starts_with, tt: k0} - - {mp: ends_with, tt: x0} - - {mp: regex, tt: '^.*0_x.*$'} - -list2: - - {k0_x0: A0, k1_x1: B0, k2_x2: [C0], k3_x3: foo} - - {k0_x0: A1, k1_x1: B1, k2_x2: [C1], k3_x3: bar} - -result2: - - {k1_x1: B0, k2_x2: [C0], k3_x3: foo} - - {k1_x1: B1, k2_x2: [C1], k3_x3: bar} diff --git a/tests/integration/targets/filter_remove_keys/vars/main/tests.yml b/tests/integration/targets/filter_remove_keys/vars/main/tests.yml new file mode 100644 index 0000000000..a4767ea799 --- /dev/null +++ b/tests/integration/targets/filter_remove_keys/vars/main/tests.yml @@ -0,0 +1,40 @@ +--- +# 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: + - template: default.j2 + group: + - {tt: [k0_x0, k1_x1], d: 'By default, match keys that equal any of the items in the target.'} + input: + - {k0_x0: A0, k1_x1: B0, k2_x2: [C0], k3_x3: foo} + - {k0_x0: A1, k1_x1: B1, k2_x2: [C1], k3_x3: bar} + result: + - {k2_x2: [C0], k3_x3: foo} + - {k2_x2: [C1], k3_x3: bar} + - template: mp.j2 + group: + - {mp: equal, tt: [k0_x0, k1_x1], d: Match keys that equal any of the items in the target.} + - {mp: starts_with, tt: [k0, k1], d: Match keys that start with any of the items in the target.} + - {mp: ends_with, tt: [x0, x1], d: Match keys that end with any of the items in target.} + - {mp: regex, tt: ['^.*[01]_x.*$'], d: Match keys by the regex.} + - {mp: regex, tt: '^.*[01]_x.*$', d: Match keys by the regex.} + input: + - {k0_x0: A0, k1_x1: B0, k2_x2: [C0], k3_x3: foo} + - {k0_x0: A1, k1_x1: B1, k2_x2: [C1], k3_x3: bar} + result: + - {k2_x2: [C0], k3_x3: foo} + - {k2_x2: [C1], k3_x3: bar} + - template: mp.j2 + group: + - {mp: equal, tt: k0_x0, d: Match keys that equal the target.} + - {mp: starts_with, tt: k0, d: Match keys that start with the target.} + - {mp: ends_with, tt: x0, d: Match keys that end with the target.} + - {mp: regex, tt: '^.*0_x.*$', d: Match keys by the regex.} + input: + - {k0_x0: A0, k1_x1: B0, k2_x2: [C0], k3_x3: foo} + - {k0_x0: A1, k1_x1: B1, k2_x2: [C1], k3_x3: bar} + result: + - {k1_x1: B0, k2_x2: [C0], k3_x3: foo} + - {k1_x1: B1, k2_x2: [C1], k3_x3: bar} diff --git a/tests/integration/targets/filter_replace_keys/tasks/fn-test-replace_keys.yml b/tests/integration/targets/filter_replace_keys/tasks/fn-test-replace_keys.yml deleted file mode 100644 index e324376a5a..0000000000 --- a/tests/integration/targets/filter_replace_keys/tasks/fn-test-replace_keys.yml +++ /dev/null @@ -1,21 +0,0 @@ ---- -# 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: Test replace keys - ansible.builtin.assert: - that: - - (rr | difference(item.result) | length) == 0 - success_msg: | - [OK] {{ item.label }} - result: - {{ rr | to_nice_yaml(indent=2) | indent(2) }} - fail_msg: | - [ERR] {{ item.label }} - result: - {{ rr | to_nice_yaml(indent=2) | indent(2) }} - quiet: "{{ quiet_test | d(true) | bool }}" - vars: - rr: "{{ item.data | - community.general.replace_keys(target=item.target, matching_parameter=item.match) }}" diff --git a/tests/integration/targets/filter_replace_keys/tasks/main.yml b/tests/integration/targets/filter_replace_keys/tasks/main.yml index 35addaf946..9c0674780e 100644 --- a/tests/integration/targets/filter_replace_keys/tasks/main.yml +++ b/tests/integration/targets/filter_replace_keys/tasks/main.yml @@ -3,5 +3,5 @@ # 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: Test replace_keys - import_tasks: replace_keys.yml +- name: Tests + import_tasks: tests.yml diff --git a/tests/integration/targets/filter_replace_keys/tasks/replace_keys.yml b/tests/integration/targets/filter_replace_keys/tasks/replace_keys.yml deleted file mode 100644 index a57921b81b..0000000000 --- a/tests/integration/targets/filter_replace_keys/tasks/replace_keys.yml +++ /dev/null @@ -1,56 +0,0 @@ ---- -# 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: Debug ansible_version - ansible.builtin.debug: - var: ansible_version - when: not quiet_test | d(true) | bool - tags: ansible_version - -- name: Test replace keys equal (default) - ansible.builtin.assert: - that: - - (rr | difference(result1) | length) == 0 - success_msg: | - [OK] result: - {{ rr | to_yaml }} - fail_msg: | - [ERR] result: - {{ rr | to_yaml }} - quiet: "{{ quiet_test | d(true) | bool }}" - vars: - rr: "{{ list1 | community.general.replace_keys(target=tt) }}" - tt: - - {before: k0_x0, after: a0} - - {before: k1_x1, after: a1} - tags: equal_default - -- name: Test replace keys targets1 - ansible.builtin.assert: - that: - - (rr | difference(result1) | length) == 0 - success_msg: | - [OK] result: - {{ rr | to_yaml }} - fail_msg: | - [ERR] result: - {{ rr | to_yaml }} - quiet: "{{ quiet_test | d(true) | bool }}" - loop: "{{ targets1 | dict2items }}" - loop_control: - label: "{{ item.key }}" - vars: - rr: "{{ list1 | community.general.replace_keys(target=item.value, matching_parameter=item.key) }}" - tags: targets1 - -- name: Test replace keys targets2 - include_tasks: - file: fn-test-replace_keys.yml - apply: - tags: targets2 - loop: "{{ targets2 }}" - loop_control: - label: "{{ item.label }}" - tags: targets2 diff --git a/tests/integration/targets/filter_replace_keys/tasks/tests.yml b/tests/integration/targets/filter_replace_keys/tasks/tests.yml new file mode 100644 index 0000000000..fa821702f0 --- /dev/null +++ b/tests/integration/targets/filter_replace_keys/tasks/tests.yml @@ -0,0 +1,31 @@ +--- +# 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: Debug ansible_version + ansible.builtin.debug: + var: ansible_version + when: not quite_test | d(true) | bool + tags: ansible_version + +- name: Tests + ansible.builtin.assert: + that: + - (result | difference(i.0.result) | length) == 0 + success_msg: | + [OK] result: + {{ result | to_yaml }} + fail_msg: | + [ERR] result: + {{ result | to_yaml }} + quiet: "{{ quiet_test | d(true) | bool }}" + loop: "{{ tests | subelements('group') }}" + loop_control: + loop_var: i + label: "{{ i.1.mp | d('default') }}: {{ i.1.tt }}" + vars: + input: "{{ i.0.input }}" + target: "{{ i.1.tt }}" + mp: "{{ i.1.mp | d('default') }}" + result: "{{ lookup('template', i.0.template) }}" diff --git a/tests/integration/targets/filter_replace_keys/templates/default.j2 b/tests/integration/targets/filter_replace_keys/templates/default.j2 new file mode 100644 index 0000000000..6ba66cd690 --- /dev/null +++ b/tests/integration/targets/filter_replace_keys/templates/default.j2 @@ -0,0 +1 @@ +{{ input | community.general.replace_keys(target=target) }} diff --git a/tests/integration/targets/filter_replace_keys/templates/default.j2.license b/tests/integration/targets/filter_replace_keys/templates/default.j2.license new file mode 100644 index 0000000000..a1390a69ed --- /dev/null +++ b/tests/integration/targets/filter_replace_keys/templates/default.j2.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 diff --git a/tests/integration/targets/filter_replace_keys/templates/mp.j2 b/tests/integration/targets/filter_replace_keys/templates/mp.j2 new file mode 100644 index 0000000000..70c5009d91 --- /dev/null +++ b/tests/integration/targets/filter_replace_keys/templates/mp.j2 @@ -0,0 +1 @@ +{{ input | community.general.replace_keys(target=target, matching_parameter=mp) }} diff --git a/tests/integration/targets/filter_replace_keys/templates/mp.j2.license b/tests/integration/targets/filter_replace_keys/templates/mp.j2.license new file mode 100644 index 0000000000..a1390a69ed --- /dev/null +++ b/tests/integration/targets/filter_replace_keys/templates/mp.j2.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 diff --git a/tests/integration/targets/filter_replace_keys/vars/main.yml b/tests/integration/targets/filter_replace_keys/vars/main.yml deleted file mode 100644 index 167e083960..0000000000 --- a/tests/integration/targets/filter_replace_keys/vars/main.yml +++ /dev/null @@ -1,58 +0,0 @@ ---- -# 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 - -list1: - - {k0_x0: A0, k1_x1: B0, k2_x2: [C0], k3_x3: foo} - - {k0_x0: A1, k1_x1: B1, k2_x2: [C1], k3_x3: bar} - -result1: - - {a0: A0, a1: B0, k2_x2: [C0], k3_x3: foo} - - {a0: A1, a1: B1, k2_x2: [C1], k3_x3: bar} - -targets1: - equal: - - {before: k0_x0, after: a0} - - {before: k1_x1, after: a1} - starts_with: - - {before: k0, after: a0} - - {before: k1, after: a1} - ends_with: - - {before: x0, after: a0} - - {before: x1, after: a1} - regex: - - {before: "^.*0_x.*$", after: a0} - - {before: "^.*1_x.*$", after: a1} - -list2: - - {aaa1: A, bbb1: B, ccc1: C} - - {aaa2: D, bbb2: E, ccc2: F} - -targets2: - - label: If more keys match the same attribute before the last one will be used. - match: regex - target: - - {before: "^.*_x.*$", after: X} - data: "{{ list1 }}" - result: - - X: foo - - X: bar - - label: If there are items with equal attribute before the first one will be used. - match: regex - target: - - {before: "^.*_x.*$", after: X} - - {before: "^.*_x.*$", after: Y} - data: "{{ list1 }}" - result: - - X: foo - - X: bar - - label: If there are more matches for a key the first one will be used. - match: starts_with - target: - - {before: a, after: X} - - {before: aa, after: Y} - data: "{{ list2 }}" - result: - - {X: A, bbb1: B, ccc1: C} - - {X: D, bbb2: E, ccc2: F} diff --git a/tests/integration/targets/filter_replace_keys/vars/main/tests.yml b/tests/integration/targets/filter_replace_keys/vars/main/tests.yml new file mode 100644 index 0000000000..ca906a770b --- /dev/null +++ b/tests/integration/targets/filter_replace_keys/vars/main/tests.yml @@ -0,0 +1,71 @@ +--- +# 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: + - template: default.j2 + group: + - d: By default, match keys that equal any of the attributes before. + tt: + - {before: k0_x0, after: a0} + - {before: k1_x1, after: a1} + input: + - {k0_x0: A0, k1_x1: B0, k2_x2: [C0], k3_x3: foo} + - {k0_x0: A1, k1_x1: B1, k2_x2: [C1], k3_x3: bar} + result: + - {a0: A0, a1: B0, k2_x2: [C0], k3_x3: foo} + - {a0: A1, a1: B1, k2_x2: [C1], k3_x3: bar} + - template: mp.j2 + group: + - d: Replace keys that starts with any of the attributes before. + mp: starts_with + tt: + - {before: k0, after: a0} + - {before: k1, after: a1} + - d: Replace keys that ends with any of the attributes before. + mp: ends_with + tt: + - {before: x0, after: a0} + - {before: x1, after: a1} + - d: Replace keys that match any regex of the attributes before. + mp: regex + tt: + - {before: "^.*0_x.*$", after: a0} + - {before: "^.*1_x.*$", after: a1} + input: + - {k0_x0: A0, k1_x1: B0, k2_x2: [C0], k3_x3: foo} + - {k0_x0: A1, k1_x1: B1, k2_x2: [C1], k3_x3: bar} + result: + - {a0: A0, a1: B0, k2_x2: [C0], k3_x3: foo} + - {a0: A1, a1: B1, k2_x2: [C1], k3_x3: bar} + - template: mp.j2 + group: + - d: If more keys match the same attribute before the last one will be used. + mp: regex + tt: + - {before: "^.*_x.*$", after: X} + - d: If there are items with equal attribute before the first one will be used. + mp: regex + tt: + - {before: "^.*_x.*$", after: X} + - {before: "^.*_x.*$", after: Y} + input: + - {k0_x0: A0, k1_x1: B0, k2_x2: [C0], k3_x3: foo} + - {k0_x0: A1, k1_x1: B1, k2_x2: [C1], k3_x3: bar} + result: + - X: foo + - X: bar + - template: mp.j2 + group: + - d: If there are more matches for a key the first one will be used. + mp: starts_with + tt: + - {before: a, after: X} + - {before: aa, after: Y} + input: + - {aaa1: A, bbb1: B, ccc1: C} + - {aaa2: D, bbb2: E, ccc2: F} + result: + - {X: A, bbb1: B, ccc1: C} + - {X: D, bbb2: E, ccc2: F}