plugins (become, callback, filter): style adjustments (#9535)

* plugins (become, callback, filter, inventory): style adjustments

* remove inventory plugins from PR

* adjustments from review

* typo

plugins/become/pfexec.py

@@ -15,8 +15,8 @@ options:
   become_user:
     description:
       - User you 'become' to execute the task.
-      - This plugin ignores this setting as pfexec uses its own C(exec_attr) to figure this out, but it is supplied here
+      - This plugin ignores this setting as pfexec uses its own C(exec_attr) to figure this out, but it is supplied here for
-        for Ansible to make decisions needed for the task execution, like file permissions.
+        Ansible to make decisions needed for the task execution, like file permissions.
     type: string
     default: root
     ini:

plugins/callback/default_without_diff.py

@@ -29,7 +29,7 @@ ansible_config: |
   stdout_callback = community.general.default_without_diff
 
 # Enable callback with environment variables:
-environment_variable: |
+environment_variable: |-
   ANSIBLE_STDOUT_CALLBACK=community.general.default_without_diff
 """
 

plugins/callback/yaml.py

@@ -14,7 +14,8 @@ type: stdout
 short_description: YAML-ized Ansible screen output
 deprecated:
   removed_in: 13.0.0
-  why: Starting in ansible-core 2.13, the P(ansible.builtin.default#callback) callback has support for printing output in YAML format.
+  why: Starting in ansible-core 2.13, the P(ansible.builtin.default#callback) callback has support for printing output in
+    YAML format.
   alternative: Use O(ansible.builtin.default#callback:result_format=yaml).
 description:
   - Ansible output that can be quite a bit easier to read than the default JSON formatting.

plugins/filter/accumulate.py

@@ -2,31 +2,31 @@
 # 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
 
-DOCUMENTATION = '''
+DOCUMENTATION = r"""
-  name: accumulate
+name: accumulate
-  short_description: Produce a list of accumulated sums of the input list contents
+short_description: Produce a list of accumulated sums of the input list contents
-  version_added: 10.1.0
+version_added: 10.1.0
-  author: Max Gautier (@VannTen)
+author: Max Gautier (@VannTen)
-  description:
+description:
   - Passthrough to the L(Python itertools.accumulate function,https://docs.python.org/3/library/itertools.html#itertools.accumulate).
   - Transforms an input list into the cumulative list of results from applying addition to the elements of the input list.
   - Addition means the default Python implementation of C(+) for input list elements type.
-  options:
+options:
   _input:
     description: A list.
     type: list
     elements: any
     required: true
-'''
+"""
 
-RETURN = '''
+RETURN = r"""
-  _value:
+_value:
   description: A list of cumulated sums of the elements of the input list.
   type: list
   elements: any
-'''
+"""
 
-EXAMPLES = '''
+EXAMPLES = r"""
 - name: Enumerate parent directories of some path
   ansible.builtin.debug:
     var: >
@@ -34,11 +34,12 @@ EXAMPLES = '''
       | split('/') | map('split', '/')
       | community.general.accumulate | map('join', '/')
     # Produces: ['', '/some', '/some/path', '/some/path/to', '/some/path/to/my', '/some/path/to/my/file']
+
 - name: Growing string
   ansible.builtin.debug:
     var: "'abc' | community.general.accumulate"
     # Produces ['a', 'ab', 'abc']
-'''
+"""
 
 from itertools import accumulate
 from collections.abc import Sequence

plugins/filter/counter.py

@@ -6,34 +6,35 @@
 from __future__ import (absolute_import, division, print_function)
 __metaclass__ = type
 
-DOCUMENTATION = '''
+DOCUMENTATION = r"""
-  name: counter
+name: counter
-  short_description: Counts hashable elements in a sequence
+short_description: Counts hashable elements in a sequence
-  version_added: 4.3.0
+version_added: 4.3.0
-  author: Rémy Keil (@keilr)
+author: Rémy Keil (@keilr)
-  description:
+description:
   - Counts hashable elements in a sequence.
-  options:
+options:
   _input:
     description: A sequence.
     type: list
     elements: any
     required: true
-'''
+"""
 
-EXAMPLES = '''
+EXAMPLES = r"""
 - name: Count occurrences
   ansible.builtin.debug:
     msg: >-
       {{ [1, 'a', 2, 2, 'a', 'b', 'a'] | community.general.counter }}
     # Produces: {1: 1, 'a': 3, 2: 2, 'b': 1}
-'''
+"""
 
-RETURN = '''
+RETURN = r"""
-  _value:
+_value:
-    description: A dictionary with the elements of the sequence as keys, and their number of occurrences in the sequence as values.
+  description: A dictionary with the elements of the sequence as keys, and their number of occurrences in the sequence as
+    values.
   type: dictionary
-'''
+"""
 
 from ansible.errors import AnsibleFilterError
 from ansible.module_utils.common._collections_compat import Sequence

plugins/filter/crc32.py

@@ -16,33 +16,33 @@ except ImportError:
     HAS_ZLIB = False
 
 
-DOCUMENTATION = '''
+DOCUMENTATION = r"""
-  name: crc32
+name: crc32
-  short_description: Generate a CRC32 checksum
+short_description: Generate a CRC32 checksum
-  version_added: 5.4.0
+version_added: 5.4.0
-  description:
+description:
   - Checksum a string using CRC32 algorithm and return its hexadecimal representation.
-  options:
+options:
   _input:
     description:
       - The string to checksum.
     type: string
     required: true
-  author:
+author:
   - Julien Riou
-'''
+"""
 
-EXAMPLES = '''
+EXAMPLES = r"""
-  - name: Checksum a test string
+- name: Checksum a test string
   ansible.builtin.debug:
     msg: "{{ 'test' | community.general.crc32 }}"
-'''
+"""
 
-RETURN = '''
+RETURN = r"""
-  _value:
+_value:
   description: CRC32 checksum.
   type: string
-'''
+"""
 
 
 def crc32s(value):

plugins/filter/dict.py

@@ -7,22 +7,22 @@
 from __future__ import absolute_import, division, print_function
 __metaclass__ = type
 
-DOCUMENTATION = '''
+DOCUMENTATION = r"""
-  name: dict
+name: dict
-  short_description: Convert a list of tuples into a dictionary
+short_description: Convert a list of tuples into a dictionary
-  version_added: 3.0.0
+version_added: 3.0.0
-  author: Felix Fontein (@felixfontein)
+author: Felix Fontein (@felixfontein)
-  description:
+description:
   - Convert a list of tuples into a dictionary. This is a filter version of the C(dict) function.
-  options:
+options:
   _input:
     description: A list of tuples (with exactly two elements).
     type: list
     elements: tuple
     required: true
-'''
+"""
 
-EXAMPLES = '''
+EXAMPLES = r"""
 - name: Convert list of tuples into dictionary
   ansible.builtin.set_fact:
     dictionary: "{{ [[1, 2], ['a', 'b']] | community.general.dict }}"
@@ -53,13 +53,13 @@ EXAMPLES = '''
   #     "k2": 42,
   #     "k3": "b"
   #   }
-'''
+"""
 
-RETURN = '''
+RETURN = r"""
-  _value:
+_value:
   description: A dictionary with the provided key-value pairs.
   type: dictionary
-'''
+"""
 
 
 def dict_filter(sequence):

plugins/filter/dict_kv.py

@@ -6,15 +6,15 @@
 from __future__ import (absolute_import, division, print_function)
 __metaclass__ = type
 
-DOCUMENTATION = '''
+DOCUMENTATION = r"""
-  name: dict_kv
+name: dict_kv
-  short_description: Convert a value to a dictionary with a single key-value pair
+short_description: Convert a value to a dictionary with a single key-value pair
-  version_added: 1.3.0
+version_added: 1.3.0
-  author: Stanislav German-Evtushenko (@giner)
+author: Stanislav German-Evtushenko (@giner)
-  description:
+description:
   - Convert a value to a dictionary with a single key-value pair.
-  positional: key
+positional: key
-  options:
+options:
   _input:
     description: The value for the single key-value pair.
     type: any
@@ -23,20 +23,20 @@ DOCUMENTATION = '''
     description: The key for the single key-value pair.
     type: any
     required: true
-'''
+"""
 
-EXAMPLES = '''
+EXAMPLES = r"""
 - name: Create a one-element dictionary from a value
   ansible.builtin.debug:
     msg: "{{ 'myvalue' | dict_kv('mykey') }}"
     # Produces the dictionary {'mykey': 'myvalue'}
-'''
+"""
 
-RETURN = '''
+RETURN = r"""
-  _value:
+_value:
   description: A dictionary with a single key-value pair.
   type: dictionary
-'''
+"""
 
 
 def dict_kv(value, key):

plugins/filter/from_csv.py

@@ -8,14 +8,14 @@
 from __future__ import absolute_import, division, print_function
 __metaclass__ = type
 
-DOCUMENTATION = '''
+DOCUMENTATION = r"""
-  name: from_csv
+name: from_csv
-  short_description: Converts CSV text input into list of dicts
+short_description: Converts CSV text input into list of dicts
-  version_added: 2.3.0
+version_added: 2.3.0
-  author: Andrew Pantuso (@Ajpantuso)
+author: Andrew Pantuso (@Ajpantuso)
-  description:
+description:
   - Converts CSV text input into list of dictionaries.
-  options:
+options:
   _input:
     description: A string containing a CSV document.
     type: string
@@ -50,9 +50,9 @@ DOCUMENTATION = '''
       - When using this parameter, you change the default value used by O(dialect).
       - The default value depends on the dialect used.
     type: bool
-'''
+"""
 
-EXAMPLES = '''
+EXAMPLES = r"""
 - name: Parse a CSV file's contents
   ansible.builtin.debug:
     msg: >-
@@ -71,14 +71,14 @@ EXAMPLES = '''
   #     "Column 1": "bar",
   #     "Value": "42",
   #   }
-'''
+"""
 
-RETURN = '''
+RETURN = r"""
-  _value:
+_value:
   description: A list with one dictionary per row.
   type: list
   elements: dictionary
-'''
+"""
 
 from ansible.errors import AnsibleFilterError
 

plugins/filter/from_ini.py

@@ -6,43 +6,43 @@
 
 from __future__ import absolute_import, division, print_function
 
-DOCUMENTATION = r'''
+DOCUMENTATION = r"""
-  name: from_ini
+name: from_ini
-  short_description: Converts INI text input into a dictionary
+short_description: Converts INI text input into a dictionary
-  version_added: 8.2.0
+version_added: 8.2.0
-  author: Steffen Scheib (@sscheib)
+author: Steffen Scheib (@sscheib)
-  description:
+description:
   - Converts INI text input into a dictionary.
-  options:
+options:
   _input:
     description: A string containing an INI document.
     type: string
     required: true
-'''
+"""
 
-EXAMPLES = r'''
+EXAMPLES = r"""
-  - name: Slurp an INI file
+- name: Slurp an INI file
   ansible.builtin.slurp:
     src: /etc/rhsm/rhsm.conf
   register: rhsm_conf
 
-  - name: Display the INI file as dictionary
+- name: Display the INI file as dictionary
   ansible.builtin.debug:
     var: rhsm_conf.content | b64decode | community.general.from_ini
 
-  - name: Set a new dictionary fact with the contents of the INI file
+- name: Set a new dictionary fact with the contents of the INI file
   ansible.builtin.set_fact:
     rhsm_dict: >-
       {{
           rhsm_conf.content | b64decode | community.general.from_ini
       }}
-'''
+"""
 
-RETURN = '''
+RETURN = r"""
-  _value:
+_value:
   description: A dictionary representing the INI file.
   type: dictionary
-'''
+"""
 
 __metaclass__ = type
 

plugins/filter/groupby_as_dict.py

@@ -6,19 +6,19 @@
 from __future__ import (absolute_import, division, print_function)
 __metaclass__ = type
 
-DOCUMENTATION = '''
+DOCUMENTATION = r"""
-  name: groupby_as_dict
+name: groupby_as_dict
-  short_description: Transform a sequence of dictionaries to a dictionary where the dictionaries are indexed by an attribute
+short_description: Transform a sequence of dictionaries to a dictionary where the dictionaries are indexed by an attribute
-  version_added: 3.1.0
+version_added: 3.1.0
-  author: Felix Fontein (@felixfontein)
+author: Felix Fontein (@felixfontein)
-  description:
+description:
   - Transform a sequence of dictionaries to a dictionary where the dictionaries are indexed by an attribute.
-    - This filter is similar to the Jinja2 C(groupby) filter. Use the Jinja2 C(groupby) filter if you have multiple entries with the same value,
+  - This filter is similar to the Jinja2 C(groupby) filter. Use the Jinja2 C(groupby) filter if you have multiple entries
-      or when you need a dictionary with list values, or when you need to use deeply nested attributes.
+    with the same value, or when you need a dictionary with list values, or when you need to use deeply nested attributes.
-  positional: attribute
+positional: attribute
-  options:
+options:
   _input:
-      description: A list of dictionaries
+    description: A list of dictionaries.
     type: list
     elements: dictionary
     required: true
@@ -26,9 +26,9 @@ DOCUMENTATION = '''
     description: The attribute to use as the key.
     type: str
     required: true
-'''
+"""
 
-EXAMPLES = '''
+EXAMPLES = r"""
 - name: Arrange a list of dictionaries as a dictionary of dictionaries
   ansible.builtin.debug:
     msg: "{{ sequence | community.general.groupby_as_dict('key') }}"
@@ -46,13 +46,13 @@ EXAMPLES = '''
   #  other_value:
   #    key: other_value
   #    baz: bar
-'''
+"""
 
-RETURN = '''
+RETURN = r"""
-  _value:
+_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

plugins/filter/jc.py

@@ -8,16 +8,16 @@
 from __future__ import (absolute_import, division, print_function)
 __metaclass__ = type
 
-DOCUMENTATION = '''
+DOCUMENTATION = r"""
-  name: jc
+name: jc
-  short_description: Convert output of many shell commands and file-types to JSON
+short_description: Convert output of many shell commands and file-types to JSON
-  version_added: 1.1.0
+version_added: 1.1.0
-  author: Kelly Brazil (@kellyjonbrazil)
+author: Kelly Brazil (@kellyjonbrazil)
-  description:
+description:
   - Convert output of many shell commands and file-types to JSON.
   - Uses the L(jc library,https://github.com/kellyjonbrazil/jc).
-  positional: parser
+positional: parser
-  options:
+options:
   _input:
     description: The data to convert.
     type: string
@@ -26,7 +26,7 @@ DOCUMENTATION = '''
     description:
       - The correct parser for the input data.
       - For example V(ifconfig).
-        - "Note: use underscores instead of dashes (if any) in the parser module name."
+      - 'Note: use underscores instead of dashes (if any) in the parser module name.'
       - See U(https://github.com/kellyjonbrazil/jc#parsers) for the latest list of parsers.
     type: string
     required: true
@@ -38,11 +38,11 @@ DOCUMENTATION = '''
     description: Set to V(true) to return pre-processed JSON.
     type: boolean
     default: false
-  requirements:
+requirements:
   - jc installed as a Python library (U(https://pypi.org/project/jc/))
-'''
+"""
 
-EXAMPLES = '''
+EXAMPLES = r"""
 - name: Install the prereqs of the jc filter (jc Python package) on the Ansible controller
   delegate_to: localhost
   ansible.builtin.pip:
@@ -68,13 +68,13 @@ EXAMPLES = '''
   #   "operating_system": "GNU/Linux",
   #   "processor": "x86_64"
   # }
-'''
+"""
 
-RETURN = '''
+RETURN = r"""
-  _value:
+_value:
   description: The processed output.
   type: any
-'''
+"""
 
 from ansible.errors import AnsibleError, AnsibleFilterError
 import importlib

plugins/filter/json_query.py

@@ -6,13 +6,13 @@
 from __future__ import (absolute_import, division, print_function)
 __metaclass__ = type
 
-DOCUMENTATION = '''
+DOCUMENTATION = r"""
-  name: json_query
+name: json_query
-  short_description: Select a single element or a data subset from a complex data structure
+short_description: Select a single element or a data subset from a complex data structure
-  description:
+description:
   - This filter lets you query a complex JSON structure and iterate over it using a loop structure.
-  positional: expr
+positional: expr
-  options:
+options:
   _input:
     description:
       - The JSON data to query.
@@ -24,11 +24,11 @@ DOCUMENTATION = '''
       - See U(http://jmespath.org/examples.html) for examples.
     type: string
     required: true
-  requirements:
+requirements:
   - jmespath
-'''
+"""
 
-EXAMPLES = '''
+EXAMPLES = r"""
 - name: Define data to work on in the examples below
   ansible.builtin.set_fact:
     domain_definition:
@@ -99,13 +99,13 @@ EXAMPLES = '''
     msg: "{{ domain_definition | to_json | from_json | community.general.json_query(server_name_query) }}"
   vars:
     server_name_query: "domain.server[?contains(name,'server1')].port"
-'''
+"""
 
-RETURN = '''
+RETURN = r"""
-  _value:
+_value:
   description: The result of the query.
   type: any
-'''
+"""
 
 from ansible.errors import AnsibleError, AnsibleFilterError
 

plugins/filter/keep_keys.py

@@ -7,15 +7,15 @@
 from __future__ import (absolute_import, division, print_function)
 __metaclass__ = type
 
-DOCUMENTATION = '''
+DOCUMENTATION = r"""
-    name: keep_keys
+name: keep_keys
-    short_description: Keep specific keys from dictionaries in a list
+short_description: Keep specific keys from dictionaries in a list
-    version_added: "9.1.0"
+version_added: "9.1.0"
-    author:
+author:
   - Vladimir Botka (@vbotka)
   - Felix Fontein (@felixfontein)
-    description: This filter keeps only specified keys from a provided list of dictionaries.
+description: This filter keeps only specified keys from a provided list of dictionaries.
-    options:
+options:
   _input:
     description:
       - A list of dictionaries.
@@ -40,66 +40,66 @@ DOCUMENTATION = '''
       regex:
         - Matches keys that match the regular expresion provided in O(target).
         - In this case, O(target) must be a regex string or a list with single regex string.
-'''
+"""
 
-EXAMPLES = '''
+EXAMPLES = r"""
-  l:
+- l:
     - {k0_x0: A0, k1_x1: B0, k2_x2: [C0], k3_x3: foo}
     - {k0_x0: A1, k1_x1: B1, k2_x2: [C1], k3_x3: bar}
 
   # 1) By default match keys that equal any of the items in the target.
-  t: [k0_x0, k1_x1]
+- t: [k0_x0, k1_x1]
   r: "{{ l | community.general.keep_keys(target=t) }}"
 
   # 2) Match keys that start with any of the items in the target.
-  t: [k0, k1]
+- t: [k0, k1]
   r: "{{ l | community.general.keep_keys(target=t, matching_parameter='starts_with') }}"
 
   # 3) Match keys that end with any of the items in target.
-  t: [x0, x1]
+- t: [x0, x1]
   r: "{{ l | community.general.keep_keys(target=t, matching_parameter='ends_with') }}"
 
   # 4) Match keys by the regex.
-  t: ['^.*[01]_x.*$']
+- t: ['^.*[01]_x.*$']
   r: "{{ l | community.general.keep_keys(target=t, matching_parameter='regex') }}"
 
   # 5) Match keys by the regex.
-  t: '^.*[01]_x.*$'
+- t: '^.*[01]_x.*$'
   r: "{{ l | community.general.keep_keys(target=t, matching_parameter='regex') }}"
 
   # The results of above examples 1-5 are all the same.
-  r:
+- r:
     - {k0_x0: A0, k1_x1: B0}
     - {k0_x0: A1, k1_x1: B1}
 
   # 6) By default match keys that equal the target.
-  t: k0_x0
+- t: k0_x0
   r: "{{ l | community.general.keep_keys(target=t) }}"
 
   # 7) Match keys that start with the target.
-  t: k0
+- t: k0
   r: "{{ l | community.general.keep_keys(target=t, matching_parameter='starts_with') }}"
 
   # 8) Match keys that end with the target.
-  t: x0
+- t: x0
   r: "{{ l | community.general.keep_keys(target=t, matching_parameter='ends_with') }}"
 
   # 9) Match keys by the regex.
-  t: '^.*0_x.*$'
+- t: '^.*0_x.*$'
   r: "{{ l | community.general.keep_keys(target=t, matching_parameter='regex') }}"
 
   # The results of above examples 6-9 are all the same.
-  r:
+- r:
     - {k0_x0: A0}
     - {k0_x0: A1}
-'''
+"""
 
-RETURN = '''
+RETURN = r"""
-  _value:
+_value:
   description: The list of dictionaries with selected keys.
   type: list
   elements: dictionary
-'''
+"""
 
 from ansible_collections.community.general.plugins.plugin_utils.keys_filter import (
     _keys_filter_params,

plugins/filter/lists_mergeby.py

@@ -6,28 +6,23 @@
 from __future__ import (absolute_import, division, print_function)
 __metaclass__ = type
 
-DOCUMENTATION = '''
+DOCUMENTATION = r"""
-  name: lists_mergeby
+name: lists_mergeby
-  short_description: Merge two or more lists of dictionaries by a given attribute
+short_description: Merge two or more lists of dictionaries by a given attribute
-  version_added: 2.0.0
+version_added: 2.0.0
-  author: Vladimir Botka (@vbotka)
+author: Vladimir Botka (@vbotka)
-  description:
+description:
-    - Merge two or more lists by attribute O(index). Optional
+  - Merge two or more lists by attribute O(index). Optional parameters O(recursive) and O(list_merge) control the merging
-      parameters O(recursive) and O(list_merge) control the merging of
+    of the nested dictionaries and lists.
-      the nested dictionaries and lists.
   - The function C(merge_hash) from C(ansible.utils.vars) is used.
-    - To learn details on how to use the parameters O(recursive) and
+  - To learn details on how to use the parameters O(recursive) and O(list_merge) see Ansible User's Guide chapter "Using filters
-      O(list_merge) see Ansible User's Guide chapter "Using filters to
+    to manipulate data" section R(Combining hashes/dictionaries, combine_filter) or the filter P(ansible.builtin.combine#filter).
-      manipulate data" section R(Combining hashes/dictionaries, combine_filter) or the
+positional: another_list, index
-      filter P(ansible.builtin.combine#filter).
+options:
-
-  positional: another_list, index
-  options:
   _input:
     description:
       - A list of dictionaries, or a list of lists of dictionaries.
-        - The required type of the C(elements) is set to C(raw)
+      - The required type of the C(elements) is set to C(raw) because all elements of O(_input) can be either dictionaries
-          because all elements of O(_input) can be either dictionaries
         or lists.
     type: list
     elements: raw
@@ -40,14 +35,13 @@ DOCUMENTATION = '''
     elements: raw
   index:
     description:
-        - The dictionary key that must be present in every dictionary in every list that is used to
+      - The dictionary key that must be present in every dictionary in every list that is used to merge the lists.
-          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)."
+      - 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:
@@ -62,9 +56,9 @@ DOCUMENTATION = '''
       - prepend
       - append_rp
       - prepend_rp
-'''
+"""
 
-EXAMPLES = '''
+EXAMPLES = r"""
 # Some results below are manually formatted for better readability. The
 # dictionaries' keys will be sorted alphabetically in real output.
 
@@ -193,14 +187,14 @@ EXAMPLES = '''
 #  r:
 #    - {index: a, foo: {x:1, y: 3, z: 4}}
 #    - {index: b, foo: [Y1, Y2]}
-'''
+"""
 
-RETURN = '''
+RETURN = r"""
-  _value:
+_value:
   description: The merged list.
   type: list
   elements: dictionary
-'''
+"""
 
 from ansible.errors import AnsibleFilterError
 from ansible.module_utils.six import string_types

plugins/filter/random_mac.py

@@ -7,12 +7,12 @@
 from __future__ import (absolute_import, division, print_function)
 __metaclass__ = type
 
-DOCUMENTATION = '''
+DOCUMENTATION = r"""
-  name: random_mac
+name: random_mac
-  short_description: Generate a random MAC address
+short_description: Generate a random MAC address
-  description:
+description:
   - Generates random networking interfaces MAC addresses for a given prefix.
-  options:
+options:
   _input:
     description: A string prefix to use as a basis for the random MAC generated.
     type: string
@@ -23,9 +23,9 @@ DOCUMENTATION = '''
       - If no seed is provided, a system random source such as C(/dev/urandom) is used.
     required: false
     type: string
-'''
+"""
 
-EXAMPLES = '''
+EXAMPLES = r"""
 - name: Random MAC given a prefix
   ansible.builtin.debug:
     msg: "{{ '52:54:00' | community.general.random_mac }}"
@@ -34,13 +34,13 @@ EXAMPLES = '''
 - name: With a seed
   ansible.builtin.debug:
     msg: "{{ '52:54:00' | community.general.random_mac(seed=inventory_hostname) }}"
-'''
+"""
 
-RETURN = '''
+RETURN = r"""
-  _value:
+_value:
   description: The generated MAC.
   type: string
-'''
+"""
 
 import re
 from random import Random, SystemRandom

plugins/filter/remove_keys.py

@@ -7,15 +7,15 @@
 from __future__ import (absolute_import, division, print_function)
 __metaclass__ = type
 
-DOCUMENTATION = '''
+DOCUMENTATION = r"""
-    name: remove_keys
+name: remove_keys
-    short_description: Remove specific keys from dictionaries in a list
+short_description: Remove specific keys from dictionaries in a list
-    version_added: "9.1.0"
+version_added: "9.1.0"
-    author:
+author:
   - Vladimir Botka (@vbotka)
   - Felix Fontein (@felixfontein)
-    description: This filter removes only specified keys from a provided list of dictionaries.
+description: This filter removes only specified keys from a provided list of dictionaries.
-    options:
+options:
   _input:
     description:
       - A list of dictionaries.
@@ -40,66 +40,66 @@ DOCUMENTATION = '''
       regex:
         - Matches keys that match the regular expresion provided in O(target).
         - In this case, O(target) must be a regex string or a list with single regex string.
-'''
+"""
 
-EXAMPLES = '''
+EXAMPLES = r"""
-  l:
+- l:
     - {k0_x0: A0, k1_x1: B0, k2_x2: [C0], k3_x3: foo}
     - {k0_x0: A1, k1_x1: B1, k2_x2: [C1], k3_x3: bar}
 
   # 1) By default match keys that equal any of the items in the target.
-  t: [k0_x0, k1_x1]
+- t: [k0_x0, k1_x1]
   r: "{{ l | community.general.remove_keys(target=t) }}"
 
   # 2) Match keys that start with any of the items in the target.
-  t: [k0, k1]
+- t: [k0, k1]
   r: "{{ l | community.general.remove_keys(target=t, matching_parameter='starts_with') }}"
 
   # 3) Match keys that end with any of the items in target.
-  t: [x0, x1]
+- t: [x0, x1]
   r: "{{ l | community.general.remove_keys(target=t, matching_parameter='ends_with') }}"
 
   # 4) Match keys by the regex.
-  t: ['^.*[01]_x.*$']
+- t: ['^.*[01]_x.*$']
   r: "{{ l | community.general.remove_keys(target=t, matching_parameter='regex') }}"
 
   # 5) Match keys by the regex.
-  t: '^.*[01]_x.*$'
+- t: '^.*[01]_x.*$'
   r: "{{ l | community.general.remove_keys(target=t, matching_parameter='regex') }}"
 
   # The results of above examples 1-5 are all the same.
-  r:
+- r:
     - {k2_x2: [C0], k3_x3: foo}
     - {k2_x2: [C1], k3_x3: bar}
 
   # 6) By default match keys that equal the target.
-  t: k0_x0
+- t: k0_x0
   r: "{{ l | community.general.remove_keys(target=t) }}"
 
   # 7) Match keys that start with the target.
-  t: k0
+- t: k0
   r: "{{ l | community.general.remove_keys(target=t, matching_parameter='starts_with') }}"
 
   # 8) Match keys that end with the target.
-  t: x0
+- t: x0
   r: "{{ l | community.general.remove_keys(target=t, matching_parameter='ends_with') }}"
 
   # 9) Match keys by the regex.
-  t: '^.*0_x.*$'
+- t: '^.*0_x.*$'
   r: "{{ l | community.general.remove_keys(target=t, matching_parameter='regex') }}"
 
   # The results of above examples 6-9 are all the same.
-  r:
+- r:
     - {k1_x1: B0, k2_x2: [C0], k3_x3: foo}
     - {k1_x1: B1, k2_x2: [C1], k3_x3: bar}
-'''
+"""
 
-RETURN = '''
+RETURN = r"""
-  _value:
+_value:
   description: The list of dictionaries with selected keys removed.
   type: list
   elements: dictionary
-'''
+"""
 
 from ansible_collections.community.general.plugins.plugin_utils.keys_filter import (
     _keys_filter_params,

plugins/filter/replace_keys.py

@@ -7,15 +7,15 @@
 from __future__ import (absolute_import, division, print_function)
 __metaclass__ = type
 
-DOCUMENTATION = '''
+DOCUMENTATION = r"""
-    name: replace_keys
+name: replace_keys
-    short_description: Replace specific keys in a list of dictionaries
+short_description: Replace specific keys in a list of dictionaries
-    version_added: "9.1.0"
+version_added: "9.1.0"
-    author:
+author:
   - Vladimir Botka (@vbotka)
   - Felix Fontein (@felixfontein)
-    description: This filter replaces specified keys in a provided list of dictionaries.
+description: This filter replaces specified keys in a provided list of dictionaries.
-    options:
+options:
   _input:
     description:
       - A list of dictionaries.
@@ -49,87 +49,87 @@ DOCUMENTATION = '''
       starts_with: Matches keys that start with one of the O(target[].before) items.
       ends_with: Matches keys that end with one of the O(target[].before) items.
       regex: Matches keys that match one of the regular expressions provided in O(target[].before).
-'''
+"""
 
-EXAMPLES = '''
+EXAMPLES = r"""
-  l:
+- l:
     - {k0_x0: A0, k1_x1: B0, k2_x2: [C0], k3_x3: foo}
     - {k0_x0: A1, k1_x1: B1, k2_x2: [C1], k3_x3: bar}
 
   # 1) By default, replace keys that are equal any of the attributes before.
-  t:
+- t:
     - {before: k0_x0, after: a0}
     - {before: k1_x1, after: a1}
   r: "{{ l | community.general.replace_keys(target=t) }}"
 
   # 2) Replace keys that starts with any of the attributes before.
-  t:
+- t:
     - {before: k0, after: a0}
     - {before: k1, after: a1}
   r: "{{ l | community.general.replace_keys(target=t, matching_parameter='starts_with') }}"
 
   # 3) Replace keys that ends with any of the attributes before.
-  t:
+- t:
     - {before: x0, after: a0}
     - {before: x1, after: a1}
   r: "{{ l | community.general.replace_keys(target=t, matching_parameter='ends_with') }}"
 
   # 4) Replace keys that match any regex of the attributes before.
-  t:
+- t:
     - {before: "^.*0_x.*$", after: a0}
     - {before: "^.*1_x.*$", after: a1}
   r: "{{ l | community.general.replace_keys(target=t, matching_parameter='regex') }}"
 
   # The results of above examples 1-4 are all the same.
-  r:
+- r:
     - {a0: A0, a1: B0, k2_x2: [C0], k3_x3: foo}
     - {a0: A1, a1: B1, k2_x2: [C1], k3_x3: bar}
 
   # 5) If more keys match the same attribute before the last one will be used.
-  t:
+- t:
     - {before: "^.*_x.*$", after: X}
   r: "{{ l | community.general.replace_keys(target=t, matching_parameter='regex') }}"
 
   # gives
 
-  r:
+- r:
     - X: foo
     - X: bar
 
   # 6) If there are items with equal attribute before the first one will be used.
-  t:
+- t:
     - {before: "^.*_x.*$", after: X}
     - {before: "^.*_x.*$", after: Y}
   r: "{{ l | community.general.replace_keys(target=t, matching_parameter='regex') }}"
 
   # gives
 
-  r:
+- r:
     - X: foo
     - X: bar
 
   # 7) If there are more matches for a key the first one will be used.
-  l:
+- l:
     - {aaa1: A, bbb1: B, ccc1: C}
     - {aaa2: D, bbb2: E, ccc2: F}
-  t:
+- t:
     - {before: a, after: X}
     - {before: aa, after: Y}
   r: "{{ l | community.general.replace_keys(target=t, matching_parameter='starts_with') }}"
 
   # gives
 
-  r:
+- r:
     - {X: A, bbb1: B, ccc1: C}
     - {X: D, bbb2: E, ccc2: F}
-'''
+"""
 
-RETURN = '''
+RETURN = r"""
-  _value:
+_value:
   description: The list of dictionaries with replaced keys.
   type: list
   elements: dictionary
-'''
+"""
 
 from ansible_collections.community.general.plugins.plugin_utils.keys_filter import (
     _keys_filter_params,

plugins/filter/reveal_ansible_type.py

@@ -6,13 +6,13 @@
 from __future__ import (absolute_import, division, print_function)
 __metaclass__ = type
 
-DOCUMENTATION = '''
+DOCUMENTATION = r"""
-    name: reveal_ansible_type
+name: reveal_ansible_type
-    short_description: Return input type
+short_description: Return input type
-    version_added: "9.2.0"
+version_added: "9.2.0"
-    author: Vladimir Botka (@vbotka)
+author: Vladimir Botka (@vbotka)
-    description: This filter returns input type.
+description: This filter returns input type.
-    options:
+options:
   _input:
     description: Input data.
     type: raw
@@ -21,101 +21,101 @@ DOCUMENTATION = '''
     description: Data type aliases.
     default: {}
     type: dictionary
-'''
+"""
 
-EXAMPLES = '''
+EXAMPLES = r"""
 # Substitution converts str to AnsibleUnicode
 # -------------------------------------------
 
 # String. AnsibleUnicode.
-data: "abc"
+- data: "abc"
-result: '{{ data | community.general.reveal_ansible_type }}'
+  result: '{{ data | community.general.reveal_ansible_type }}'
 # result => AnsibleUnicode
 
 # String. AnsibleUnicode alias str.
-alias: {"AnsibleUnicode": "str"}
+- alias: {"AnsibleUnicode": "str"}
-data: "abc"
+  data: "abc"
-result: '{{ data | community.general.reveal_ansible_type(alias) }}'
+  result: '{{ data | community.general.reveal_ansible_type(alias) }}'
 # result => str
 
 # List. All items are AnsibleUnicode.
-data: ["a", "b", "c"]
+- data: ["a", "b", "c"]
-result: '{{ data | community.general.reveal_ansible_type }}'
+  result: '{{ data | community.general.reveal_ansible_type }}'
 # result => list[AnsibleUnicode]
 
 # Dictionary. All keys are AnsibleUnicode. All values are AnsibleUnicode.
-data: {"a": "foo", "b": "bar", "c": "baz"}
+- data: {"a": "foo", "b": "bar", "c": "baz"}
-result: '{{ data | community.general.reveal_ansible_type }}'
+  result: '{{ data | community.general.reveal_ansible_type }}'
 # result => dict[AnsibleUnicode, AnsibleUnicode]
 
 # No substitution and no alias. Type of strings is str
 # ----------------------------------------------------
 
 # String
-result: '{{ "abc" | community.general.reveal_ansible_type }}'
+- result: '{{ "abc" | community.general.reveal_ansible_type }}'
 # result => str
 
 # Integer
-result: '{{ 123 | community.general.reveal_ansible_type }}'
+- result: '{{ 123 | community.general.reveal_ansible_type }}'
 # result => int
 
 # Float
-result: '{{ 123.45 | community.general.reveal_ansible_type }}'
+- result: '{{ 123.45 | community.general.reveal_ansible_type }}'
 # result => float
 
 # Boolean
-result: '{{ true | community.general.reveal_ansible_type }}'
+- result: '{{ true | community.general.reveal_ansible_type }}'
 # result => bool
 
 # List. All items are strings.
-result: '{{ ["a", "b", "c"] | community.general.reveal_ansible_type }}'
+- result: '{{ ["a", "b", "c"] | community.general.reveal_ansible_type }}'
 # result => list[str]
 
 # List of dictionaries.
-result: '{{ [{"a": 1}, {"b": 2}] | community.general.reveal_ansible_type }}'
+- result: '{{ [{"a": 1}, {"b": 2}] | community.general.reveal_ansible_type }}'
 # result => list[dict]
 
 # Dictionary. All keys are strings. All values are integers.
-result: '{{ {"a": 1} | community.general.reveal_ansible_type }}'
+- result: '{{ {"a": 1} | community.general.reveal_ansible_type }}'
 # result => dict[str, int]
 
 # Dictionary. All keys are strings. All values are integers.
-result: '{{ {"a": 1, "b": 2} | community.general.reveal_ansible_type }}'
+- result: '{{ {"a": 1, "b": 2} | community.general.reveal_ansible_type }}'
 # result => dict[str, int]
 
 # Type of strings is AnsibleUnicode or str
 # ----------------------------------------
 
 # Dictionary. The keys are integers or strings. All values are strings.
-alias: {"AnsibleUnicode": "str"}
+- alias: {"AnsibleUnicode": "str"}
-data: {1: 'a', 'b': 'b'}
+  data: {1: 'a', 'b': 'b'}
-result: '{{ data | community.general.reveal_ansible_type(alias) }}'
+  result: '{{ data | community.general.reveal_ansible_type(alias) }}'
 # result => dict[int|str, str]
 
 # Dictionary. All keys are integers. All values are keys.
-alias: {"AnsibleUnicode": "str"}
+- alias: {"AnsibleUnicode": "str"}
-data: {1: 'a', 2: 'b'}
+  data: {1: 'a', 2: 'b'}
-result: '{{ data | community.general.reveal_ansible_type(alias) }}'
+  result: '{{ data | community.general.reveal_ansible_type(alias) }}'
 # result => dict[int, str]
 
 # Dictionary. All keys are strings. Multiple types values.
-alias: {"AnsibleUnicode": "str"}
+- alias: {"AnsibleUnicode": "str"}
-data: {'a': 1, 'b': 1.1, 'c': 'abc', 'd': True, 'e': ['x', 'y', 'z'], 'f': {'x': 1, 'y': 2}}
+  data: {'a': 1, 'b': 1.1, 'c': 'abc', 'd': true, 'e': ['x', 'y', 'z'], 'f': {'x': 1, 'y': 2}}
-result: '{{ data | community.general.reveal_ansible_type(alias) }}'
+  result: '{{ data | community.general.reveal_ansible_type(alias) }}'
 # result => dict[str, bool|dict|float|int|list|str]
 
 # List. Multiple types items.
-alias: {"AnsibleUnicode": "str"}
+- alias: {"AnsibleUnicode": "str"}
-data: [1, 2, 1.1, 'abc', True, ['x', 'y', 'z'], {'x': 1, 'y': 2}]
+  data: [1, 2, 1.1, 'abc', true, ['x', 'y', 'z'], {'x': 1, 'y': 2}]
-result: '{{ data | community.general.reveal_ansible_type(alias) }}'
+  result: '{{ data | community.general.reveal_ansible_type(alias) }}'
 # result => list[bool|dict|float|int|list|str]
-'''
+"""
 
-RETURN = '''
+RETURN = r"""
-  _value:
+_value:
   description: Type of the data.
   type: str
-'''
+"""
 
 from ansible_collections.community.general.plugins.plugin_utils.ansible_type import _ansible_type
 

plugins/filter/to_ini.py

@@ -6,22 +6,22 @@
 
 from __future__ import absolute_import, division, print_function
 
-DOCUMENTATION = r'''
+DOCUMENTATION = r"""
-  name: to_ini
+name: to_ini
-  short_description: Converts a dictionary to the INI file format
+short_description: Converts a dictionary to the INI file format
-  version_added: 8.2.0
+version_added: 8.2.0
-  author: Steffen Scheib (@sscheib)
+author: Steffen Scheib (@sscheib)
-  description:
+description:
   - Converts a dictionary to the INI file format.
-  options:
+options:
   _input:
     description: The dictionary that should be converted to the INI format.
     type: dictionary
     required: true
-'''
+"""
 
-EXAMPLES = r'''
+EXAMPLES = r"""
-  - name: Define a dictionary
+- name: Define a dictionary
   ansible.builtin.set_fact:
     my_dict:
       section_name:
@@ -30,7 +30,7 @@ EXAMPLES = r'''
       another_section:
         connection: 'ssh'
 
-  - name: Write dictionary to INI file
+- name: Write dictionary to INI file
   ansible.builtin.copy:
     dest: /tmp/test.ini
     content: '{{ my_dict | community.general.to_ini }}'
@@ -41,13 +41,13 @@ EXAMPLES = r'''
   #
   # [another_section]
   # connection = ssh
-'''
+"""
 
-RETURN = r'''
+RETURN = r"""
-  _value:
+_value:
   description: A string formatted as INI file.
   type: string
-'''
+"""
 
 
 __metaclass__ = type

plugins/filter/unicode_normalize.py

@@ -7,15 +7,15 @@
 from __future__ import absolute_import, division, print_function
 __metaclass__ = type
 
-DOCUMENTATION = '''
+DOCUMENTATION = r"""
-  name: unicode_normalize
+name: unicode_normalize
-  short_description: Normalizes unicode strings to facilitate comparison of characters with normalized forms
+short_description: Normalizes unicode strings to facilitate comparison of characters with normalized forms
-  version_added: 3.7.0
+version_added: 3.7.0
-  author: Andrew Pantuso (@Ajpantuso)
+author: Andrew Pantuso (@Ajpantuso)
-  description:
+description:
   - Normalizes unicode strings to facilitate comparison of characters with normalized forms.
-  positional: form
+positional: form
-  options:
+options:
   _input:
     description: A unicode string.
     type: string
@@ -31,21 +31,21 @@ DOCUMENTATION = '''
       - NFD
       - NFKC
       - NFKD
-'''
+"""
 
-EXAMPLES = '''
+EXAMPLES = r"""
 - name: Normalize unicode string
   ansible.builtin.set_fact:
     dictionary: "{{ 'ä' | community.general.unicode_normalize('NFKD') }}"
     # The resulting string has length 2: one letter is 'a', the other
     # the diacritic combiner.
-'''
+"""
 
-RETURN = '''
+RETURN = r"""
-  _value:
+_value:
   description: The normalized unicode string of the specified normal form.
   type: string
-'''
+"""
 
 from unicodedata import normalize
 

plugins/filter/version_sort.py

@@ -6,34 +6,34 @@
 from __future__ import (absolute_import, division, print_function)
 __metaclass__ = type
 
-DOCUMENTATION = '''
+DOCUMENTATION = r"""
-  name: version_sort
+name: version_sort
-  short_description: Sort a list according to version order instead of pure alphabetical one
+short_description: Sort a list according to version order instead of pure alphabetical one
-  version_added: 2.2.0
+version_added: 2.2.0
-  author: Eric L. (@ericzolf)
+author: Eric L. (@ericzolf)
-  description:
+description:
   - Sort a list according to version order instead of pure alphabetical one.
-  options:
+options:
   _input:
     description: A list of strings to sort.
     type: list
     elements: string
     required: true
-'''
+"""
 
-EXAMPLES = '''
+EXAMPLES = r"""
 - name: Convert list of tuples into dictionary
   ansible.builtin.set_fact:
     dictionary: "{{ ['2.1', '2.10', '2.9'] | community.general.version_sort }}"
     # Result is ['2.1', '2.9', '2.10']
-'''
+"""
 
-RETURN = '''
+RETURN = r"""
-  _value:
+_value:
   description: The list of strings sorted by version.
   type: list
   elements: string
-'''
+"""
 
 from ansible_collections.community.general.plugins.module_utils.version import LooseVersion