diff --git a/README.md b/README.md index 2645d9b..091db35 100644 --- a/README.md +++ b/README.md @@ -24,6 +24,7 @@ Name | Description [ansible.utils.from_xml](https://github.com/ansible-collections/ansible.utils/blob/main/docs/ansible.utils.from_xml_filter.rst)|Convert given XML string to native python dictionary. [ansible.utils.get_path](https://github.com/ansible-collections/ansible.utils/blob/main/docs/ansible.utils.get_path_filter.rst)|Retrieve the value in a variable using a path [ansible.utils.index_of](https://github.com/ansible-collections/ansible.utils/blob/main/docs/ansible.utils.index_of_filter.rst)|Find the indices of items in a list matching some criteria +[ansible.utils.param_list_compare](https://github.com/ansible-collections/ansible.utils/blob/main/docs/ansible.utils.param_list_compare_filter.rst)|Generate the final param list combining/comparing base and provided parameters. [ansible.utils.to_paths](https://github.com/ansible-collections/ansible.utils/blob/main/docs/ansible.utils.to_paths_filter.rst)|Flatten a complex object into a dictionary of paths and values [ansible.utils.to_xml](https://github.com/ansible-collections/ansible.utils/blob/main/docs/ansible.utils.to_xml_filter.rst)|Convert given JSON string to XML [ansible.utils.usable_range](https://github.com/ansible-collections/ansible.utils/blob/main/docs/ansible.utils.usable_range_filter.rst)|Expand the usable IP addresses diff --git a/changelogs/fragments/param_list_compare_docs_added.yaml b/changelogs/fragments/param_list_compare_docs_added.yaml new file mode 100644 index 0000000..e78891b --- /dev/null +++ b/changelogs/fragments/param_list_compare_docs_added.yaml @@ -0,0 +1,3 @@ +--- +trivial: + - Update param_list_compare filter plugin example and add docs. diff --git a/docs/ansible.utils.param_list_compare_filter.rst b/docs/ansible.utils.param_list_compare_filter.rst new file mode 100644 index 0000000..a9d6f1e --- /dev/null +++ b/docs/ansible.utils.param_list_compare_filter.rst @@ -0,0 +1,262 @@ +.. _ansible.utils.param_list_compare_filter: + + +******************************** +ansible.utils.param_list_compare +******************************** + +**Generate the final param list combining/comparing base and provided parameters.** + + +Version added: 2.4.0 + +.. contents:: + :local: + :depth: 1 + + +Synopsis +-------- +- Generate the final list of parameters after comparing with base list and provided/target list of params/bangs. + + + + +Parameters +---------- + +.. raw:: html + + + + + + + + + + + + + + + + + + + + +
ParameterChoices/DefaultsConfigurationComments
+
+ base + +
+ list + / elements=string +
+ 		+ + +
Specify the base list.
+
+
+ target + +
+ list + / elements=string +
+ 		+ + +
Specify the target list.
+
+
+ + + + +Examples +-------- + +.. code-block:: yaml + + - set_fact: + base: ['1','2','3','4','5'] + + - set_fact: + target: ['!all','2','4'] + + - name: Get final list of parameters + register: result + set_fact: + final_params: "{{ base|param_list_compare(target) }}" + + # TASK [Target list] ********************************************************** + # ok: [localhost] => { + # "msg": { + # "actionable": [ + # "2", + # "4" + # ], + # "unsupported": [] + # } + # } + + - set_fact: + base: ['1','2','3','4','5'] + + - name: Get final list of parameters + register: result + set_fact: + final_params: "{{ base|param_list_compare(target=['2', '7', '8']) }}" + + # TASK [Get final list of parameters] ******************************************** + # ok: [localhost] => { + # "ansible_facts": { + # "final_params": { + # "actionable": [ + # "2" + # ], + # "unsupported": [ + # "7", + # "8" + # ] + # } + # }, + # "changed": false + # } + + # Network Specific Example + # ----------- + - set_fact: + ios_resources: + - "acl_interfaces" + - "acls" + - "bgp_address_family" + - "bgp_global" + - "interfaces" + - "l2_interfaces" + - "l3_interfaces" + - "lacp" + - "lacp_interfaces" + - "lag_interfaces" + - "lldp_global" + - "lldp_interfaces" + - "logging_global" + - "ospf_interfaces" + - "ospfv2" + - "ospfv3" + - "prefix_lists" + - "route_maps" + - "static_routes" + - "vlans" + + - set_fact: + target_resources: + - '!all' + - 'vlan' + - 'bgp_global' + + - name: Get final list of target resources/params + register: result + set_fact: + network_resources: "{{ ios_resources|param_list_compare(target_resources) }}" + + - name: Target list of network resources + debug: + msg: "{{ network_resources }}" + + # TASK [Target list of network resources] ******************************************************************************************************************* + # ok: [localhost] => { + # "msg": { + # "actionable": [ + # "bgp_global", + # "vlans" + # ], + # "unsupported": [] + # } + # } + + - name: Get final list of target resources/params + register: result + set_fact: + network_resources: "{{ ios_resources|param_list_compare(target=['vla', 'ntp_global', 'logging_global']) }}" + + - name: Target list of network resources + debug: + msg: "{{ network_resources }}" + + # TASK [Target list of network resources] ************************************************ + # ok: [localhost] => { + # "msg": { + # "actionable": [ + # "logging_global" + # ], + # "unsupported": [ + # "vla", + # "ntp_global" + # ] + # } + # } + + + +Return Values +------------- +Common return values are documented `here `_, the following are the fields unique to this filter: + +.. raw:: html + + + + + + + + + + + + + + + + + +
KeyReturnedDescription
+
+ actionable + +
+ list +
+ 		+
list of combined params
+
+
+
+ unsupported + +
+ list +
+ 		+
list of unsupported params
+
+
+

+ + +Status +------ + + +Authors +~~~~~~~ + +- Rohit Thakur (@rohitthakur2590) + + +.. hint:: + Configuration entries for each entry type have a low to high priority order. For example, a variable that is lower in the list will override a variable that is higher up. diff --git a/plugins/filter/param_list_compare.py b/plugins/filter/param_list_compare.py index e0268a0..54ae9ab 100644 --- a/plugins/filter/param_list_compare.py +++ b/plugins/filter/param_list_compare.py @@ -43,6 +43,30 @@ EXAMPLES = r""" # } # } +- set_fact: + base: ['1','2','3','4','5'] + +- name: Get final list of parameters + register: result + set_fact: + final_params: "{{ base|param_list_compare(target=['2', '7', '8']) }}" + +# TASK [Get final list of parameters] ******************************************** +# ok: [localhost] => { +# "ansible_facts": { +# "final_params": { +# "actionable": [ +# "2" +# ], +# "unsupported": [ +# "7", +# "8" +# ] +# } +# }, +# "changed": false +# } + # Network Specific Example # ----------- - set_fact: diff --git a/tests/sanity/ignore-2.12.txt b/tests/sanity/ignore-2.12.txt index f6a0f43..fbedf6f 100644 --- a/tests/sanity/ignore-2.12.txt +++ b/tests/sanity/ignore-2.12.txt @@ -1 +1,2 @@ plugins/module_utils/common/index_of.py pylint:ansible-bad-module-import # file's use is limited to filter and lookups on control node +tests/unit/mock/loader.py pylint:arguments-renamed