From af7bf6aead072fb7fcfba8472157330d9d656615 Mon Sep 17 00:00:00 2001 From: Felix Fontein Date: Thu, 5 May 2022 08:56:13 +0200 Subject: [PATCH] [stable-4] Move in-plugin docs to sidecar for filters not named like the filename that contain them (#4626) (#4631) * Move in-plugin docs to sidecar for filters not named like the filename that contain them. * Update BOTMETA. (cherry picked from commit d1877e1915e444569eaaa92368d0877af319e0d6) --- .github/BOTMETA.yml | 4 ++ plugins/filter/groupby.py | 46 --------------------- plugins/filter/groupby_as_dict.yml | 42 +++++++++++++++++++ plugins/filter/list.py | 66 ------------------------------ plugins/filter/lists_mergeby.yml | 62 ++++++++++++++++++++++++++++ 5 files changed, 108 insertions(+), 112 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 6ded20f8f4..c6eb119f44 100644 --- a/.github/BOTMETA.yml +++ b/.github/BOTMETA.yml @@ -126,6 +126,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: @@ -137,6 +139,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 1c2f9b47bb..460e45194f 100644 --- a/plugins/filter/list.py +++ b/plugins/filter/list.py @@ -5,72 +5,6 @@ from __future__ import (absolute_import, division, print_function) __metaclass__ = type -DOCUMENTATION = ''' - name: lists_mergeby - short_description: Merge two lists of dictionaries by a given attribute - version_added: 2.0.0 - author: Vladimir Botka (@vbotka) - description: - - Merge two lists by attribute I(index). - positional: another_list, index - options: - _input: - description: A list of dictionaries. - type: list - elements: dictionary - required: true - another_list: - description: Another list of dictionaries. - type: list - elements: dictionary - required: true - 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 -''' - -EXAMPLES = ''' -- name: Merge two lists - ansible.builtin.debug: - msg: >- - {{ list1 | community.general.lists_mergeby(list2, 'index') }}" - 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 AnsibleError, 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..4a08c2f7d0 --- /dev/null +++ b/plugins/filter/lists_mergeby.yml @@ -0,0 +1,62 @@ +DOCUMENTATION: + name: lists_mergeby + short_description: Merge two lists of dictionaries by a given attribute + version_added: 2.0.0 + author: Vladimir Botka (@vbotka) + description: + - Merge two lists by attribute I(index). + positional: another_list, index + options: + _input: + description: A list of dictionaries. + type: list + elements: dictionary + required: true + another_list: + description: Another list of dictionaries. + type: list + elements: dictionary + required: true + 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 + +EXAMPLES: | + - name: Merge two lists + ansible.builtin.debug: + msg: >- + {{ list1 | community.general.lists_mergeby(list2, 'index') }}" + 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