From d1877e1915e444569eaaa92368d0877af319e0d6 Mon Sep 17 00:00:00 2001 From: Felix Fontein Date: Thu, 5 May 2022 08:31:38 +0200 Subject: [PATCH] [stable-4] Move in-plugin docs to sidecar for filters not named like the filename that contain them (#4626) * Move in-plugin docs to sidecar for filters not named like the filename that contain them. * Update BOTMETA. --- .github/BOTMETA.yml | 4 ++ plugins/filter/groupby.py | 46 --------------- plugins/filter/groupby_as_dict.yml | 42 ++++++++++++++ plugins/filter/list.py | 92 ------------------------------ plugins/filter/lists_mergeby.yml | 88 ++++++++++++++++++++++++++++ 5 files changed, 134 insertions(+), 138 deletions(-) create mode 100644 plugins/filter/groupby_as_dict.yml create mode 100644 plugins/filter/lists_mergeby.yml diff --git a/.github/BOTMETA.yml b/.github/BOTMETA.yml index ade8a1cdbf..9b893348f0 100644 --- a/.github/BOTMETA.yml +++ b/.github/BOTMETA.yml @@ -128,6 +128,8 @@ files: maintainers: Ajpantuso $filters/groupby.py: maintainers: felixfontein + $filters/groupby_as_dict.yml: + maintainers: felixfontein $filters/hashids.py: maintainers: Ajpantuso $filters/hashids_decode.yml: @@ -139,6 +141,8 @@ files: $filters/json_query.py: {} $filters/list.py: maintainers: vbotka + $filters/lists_mergeby.yml: + maintainers: vbotka $filters/path_join_shim.py: maintainers: felixfontein $filters/random_mac.py: {} diff --git a/plugins/filter/groupby.py b/plugins/filter/groupby.py index 386a8b44cf..a2a85aa905 100644 --- a/plugins/filter/groupby.py +++ b/plugins/filter/groupby.py @@ -5,52 +5,6 @@ from __future__ import (absolute_import, division, print_function) __metaclass__ = type -DOCUMENTATION = ''' - name: groupby_as_dict - short_description: Transform a sequence of dictionaries to a dictionary where the dictionaries are indexed by an attribute - version_added: 3.1.0 - author: Felix Fontein (@felixfontein) - description: - - Transform a sequence of dictionaries to a dictionary where the dictionaries are indexed by an attribute. - positional: attribute - options: - _input: - description: A list of dictionaries - type: list - elements: dictionary - required: true - attribute: - description: The attribute to use as the key. - type: str - required: true -''' - -EXAMPLES = ''' -- name: Arrange a list of dictionaries as a dictionary of dictionaries - ansible.builtin.debug: - msg: "{{ sequence | community.general.groupby_as_dict('key') }}" - vars: - sequence: - - key: value - foo: bar - - key: other_value - baz: bar - # Produces the following nested structure: - # - # value: - # key: value - # foo: bar - # other_value: - # key: other_value - # baz: bar -''' - -RETURN = ''' - _value: - description: A dictionary containing the dictionaries from the list as values. - type: dictionary -''' - from ansible.errors import AnsibleFilterError from ansible.module_utils.common._collections_compat import Mapping, Sequence diff --git a/plugins/filter/groupby_as_dict.yml b/plugins/filter/groupby_as_dict.yml new file mode 100644 index 0000000000..dd742944da --- /dev/null +++ b/plugins/filter/groupby_as_dict.yml @@ -0,0 +1,42 @@ +DOCUMENTATION: + name: groupby_as_dict + short_description: Transform a sequence of dictionaries to a dictionary where the dictionaries are indexed by an attribute + version_added: 3.1.0 + author: Felix Fontein (@felixfontein) + description: + - Transform a sequence of dictionaries to a dictionary where the dictionaries are indexed by an attribute. + positional: attribute + options: + _input: + description: A list of dictionaries + type: list + elements: dictionary + required: true + attribute: + description: The attribute to use as the key. + type: str + required: true + +EXAMPLES: | + - name: Arrange a list of dictionaries as a dictionary of dictionaries + ansible.builtin.debug: + msg: "{{ sequence | community.general.groupby_as_dict('key') }}" + vars: + sequence: + - key: value + foo: bar + - key: other_value + baz: bar + # Produces the following nested structure: + # + # value: + # key: value + # foo: bar + # other_value: + # key: other_value + # baz: bar + +RETURN: + _value: + description: A dictionary containing the dictionaries from the list as values. + type: dictionary diff --git a/plugins/filter/list.py b/plugins/filter/list.py index 82652414ce..005e4b7c70 100644 --- a/plugins/filter/list.py +++ b/plugins/filter/list.py @@ -5,98 +5,6 @@ from __future__ import (absolute_import, division, print_function) __metaclass__ = type -DOCUMENTATION = ''' - name: lists_mergeby - short_description: Merge two or more lists of dictionaries by a given attribute - version_added: 2.0.0 - author: Vladimir Botka (@vbotka) - description: - - Merge two or more lists by attribute I(index). Optional parameters 'recursive' and 'list_merge' - control the merging of the lists in values. The function merge_hash from ansible.utils.vars - is used. To learn details on how to use the parameters 'recursive' and 'list_merge' see - Ansible User's Guide chapter "Using filters to manipulate data" section "Combining - hashes/dictionaries". - positional: another_list, index - options: - _input: - description: A list of dictionaries. - type: list - elements: dictionary - required: true - another_list: - description: Another list of dictionaries. This parameter can be specified multiple times. - type: list - elements: dictionary - index: - description: - - The dictionary key that must be present in every dictionary in every list that is used to - merge the lists. - type: string - required: true - recursive: - description: - - Should the combine recursively merge nested dictionaries (hashes). - - "B(Note:) It does not depend on the value of the C(hash_behaviour) setting in C(ansible.cfg)." - type: boolean - default: false - list_merge: - description: - - Modifies the behaviour when the dictionaries (hashes) to merge contain arrays/lists. - type: string - default: replace - choices: - - replace - - keep - - append - - prepend - - append_rp - - prepend_rp -''' - -EXAMPLES = ''' -- name: Merge two lists - ansible.builtin.debug: - msg: >- - {{ list1 | community.general.lists_mergeby( - list2, - 'index', - recursive=True, - list_merge='append' - ) }}" - vars: - list1: - - index: a - value: 123 - - index: b - value: 42 - list2: - - index: a - foo: bar - - index: c - foo: baz - # Produces the following list of dictionaries: - # { - # "index": "a", - # "foo": "bar", - # "value": 123 - # }, - # { - # "index": "b", - # "value": 42 - # }, - # { - # "index": "c", - # "foo": "baz" - # } -''' - -RETURN = ''' - _value: - description: The merged list. - type: list - elements: dictionary -''' - from ansible.errors import AnsibleFilterError from ansible.module_utils.six import string_types from ansible.module_utils.common._collections_compat import Mapping, Sequence diff --git a/plugins/filter/lists_mergeby.yml b/plugins/filter/lists_mergeby.yml new file mode 100644 index 0000000000..341973bc91 --- /dev/null +++ b/plugins/filter/lists_mergeby.yml @@ -0,0 +1,88 @@ +DOCUMENTATION: + name: lists_mergeby + short_description: Merge two or more lists of dictionaries by a given attribute + version_added: 2.0.0 + author: Vladimir Botka (@vbotka) + description: + - Merge two or more lists by attribute I(index). Optional parameters 'recursive' and 'list_merge' + control the merging of the lists in values. The function merge_hash from ansible.utils.vars + is used. To learn details on how to use the parameters 'recursive' and 'list_merge' see + Ansible User's Guide chapter "Using filters to manipulate data" section "Combining + hashes/dictionaries". + positional: another_list, index + options: + _input: + description: A list of dictionaries. + type: list + elements: dictionary + required: true + another_list: + description: Another list of dictionaries. This parameter can be specified multiple times. + type: list + elements: dictionary + index: + description: + - The dictionary key that must be present in every dictionary in every list that is used to + merge the lists. + type: string + required: true + recursive: + description: + - Should the combine recursively merge nested dictionaries (hashes). + - "B(Note:) It does not depend on the value of the C(hash_behaviour) setting in C(ansible.cfg)." + type: boolean + default: false + list_merge: + description: + - Modifies the behaviour when the dictionaries (hashes) to merge contain arrays/lists. + type: string + default: replace + choices: + - replace + - keep + - append + - prepend + - append_rp + - prepend_rp + +EXAMPLES: | + - name: Merge two lists + ansible.builtin.debug: + msg: >- + {{ list1 | community.general.lists_mergeby( + list2, + 'index', + recursive=True, + list_merge='append' + ) }}" + vars: + list1: + - index: a + value: 123 + - index: b + value: 42 + list2: + - index: a + foo: bar + - index: c + foo: baz + # Produces the following list of dictionaries: + # { + # "index": "a", + # "foo": "bar", + # "value": 123 + # }, + # { + # "index": "b", + # "value": 42 + # }, + # { + # "index": "c", + # "foo": "baz" + # } + +RETURN: + _value: + description: The merged list. + type: list + elements: dictionary