diff --git a/plugins/become/pfexec.py b/plugins/become/pfexec.py index 62d22bdb61c..b23509281cc 100644 --- a/plugins/become/pfexec.py +++ b/plugins/become/pfexec.py @@ -15,8 +15,8 @@ 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 - for Ansible to make decisions needed for the task execution, like file permissions. + - This plugin ignores this setting as pfexec uses its own C(exec_attr) to figure this out, but it is supplied here for + Ansible to make decisions needed for the task execution, like file permissions. type: string default: root ini: diff --git a/plugins/callback/default_without_diff.py b/plugins/callback/default_without_diff.py index 8f300d8e4f2..b6ef75ce91d 100644 --- a/plugins/callback/default_without_diff.py +++ b/plugins/callback/default_without_diff.py @@ -29,7 +29,7 @@ stdout_callback = community.general.default_without_diff # Enable callback with environment variables: -environment_variable: | +environment_variable: |- ANSIBLE_STDOUT_CALLBACK=community.general.default_without_diff """ diff --git a/plugins/callback/yaml.py b/plugins/callback/yaml.py index 0484f80a34b..a68c590cf75 100644 --- a/plugins/callback/yaml.py +++ b/plugins/callback/yaml.py @@ -14,7 +14,8 @@ 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. diff --git a/plugins/filter/accumulate.py b/plugins/filter/accumulate.py index 9400936e1d4..c48afa04672 100644 --- a/plugins/filter/accumulate.py +++ b/plugins/filter/accumulate.py @@ -2,43 +2,44 @@ # 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 = ''' - name: accumulate - short_description: Produce a list of accumulated sums of the input list contents - version_added: 10.1.0 - author: Max Gautier (@VannTen) - 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: - _input: - description: A list. - type: list - elements: any - required: true -''' - -RETURN = ''' - _value: - description: A list of cumulated sums of the elements of the input list. +DOCUMENTATION = r""" +name: accumulate +short_description: Produce a list of accumulated sums of the input list contents +version_added: 10.1.0 +author: Max Gautier (@VannTen) +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: + _input: + description: A list. type: list elements: any -''' + required: true +""" -EXAMPLES = ''' +RETURN = r""" +_value: + description: A list of cumulated sums of the elements of the input list. + type: list + elements: any +""" + +EXAMPLES = r""" - name: Enumerate parent directories of some path ansible.builtin.debug: var: > - "/some/path/to/my/file" - | split('/') | map('split', '/') - | community.general.accumulate | map('join', '/') + "/some/path/to/my/file" + | 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 diff --git a/plugins/filter/counter.py b/plugins/filter/counter.py index 1b79294b59f..93ffa64d018 100644 --- a/plugins/filter/counter.py +++ b/plugins/filter/counter.py @@ -6,34 +6,35 @@ from __future__ import (absolute_import, division, print_function) __metaclass__ = type -DOCUMENTATION = ''' - name: counter - short_description: Counts hashable elements in a sequence - version_added: 4.3.0 - author: Rémy Keil (@keilr) - description: - - Counts hashable elements in a sequence. - options: - _input: - description: A sequence. - type: list - elements: any - required: true -''' +DOCUMENTATION = r""" +name: counter +short_description: Counts hashable elements in a sequence +version_added: 4.3.0 +author: Rémy Keil (@keilr) +description: + - Counts hashable elements in a sequence. +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 = ''' - _value: - description: A dictionary with the elements of the sequence as keys, and their number of occurrences in the sequence as values. - type: dictionary -''' +RETURN = r""" +_value: + 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 diff --git a/plugins/filter/crc32.py b/plugins/filter/crc32.py index 1f0aa2e9b03..bdf6d51614a 100644 --- a/plugins/filter/crc32.py +++ b/plugins/filter/crc32.py @@ -16,33 +16,33 @@ HAS_ZLIB = False -DOCUMENTATION = ''' - name: crc32 - short_description: Generate a CRC32 checksum - version_added: 5.4.0 - description: - - Checksum a string using CRC32 algorithm and return its hexadecimal representation. - options: - _input: - description: - - The string to checksum. - type: string - required: true - author: - - Julien Riou -''' +DOCUMENTATION = r""" +name: crc32 +short_description: Generate a CRC32 checksum +version_added: 5.4.0 +description: + - Checksum a string using CRC32 algorithm and return its hexadecimal representation. +options: + _input: + description: + - The string to checksum. + type: string + required: true +author: + - Julien Riou +""" -EXAMPLES = ''' - - name: Checksum a test string - ansible.builtin.debug: - msg: "{{ 'test' | community.general.crc32 }}" -''' +EXAMPLES = r""" +- name: Checksum a test string + ansible.builtin.debug: + msg: "{{ 'test' | community.general.crc32 }}" +""" -RETURN = ''' - _value: - description: CRC32 checksum. - type: string -''' +RETURN = r""" +_value: + description: CRC32 checksum. + type: string +""" def crc32s(value): diff --git a/plugins/filter/dict.py b/plugins/filter/dict.py index 3e0558bb616..b3e81bd4ab7 100644 --- a/plugins/filter/dict.py +++ b/plugins/filter/dict.py @@ -7,22 +7,22 @@ from __future__ import absolute_import, division, print_function __metaclass__ = type -DOCUMENTATION = ''' - name: dict - short_description: Convert a list of tuples into a dictionary - version_added: 3.0.0 - author: Felix Fontein (@felixfontein) - description: - - Convert a list of tuples into a dictionary. This is a filter version of the C(dict) function. - options: - _input: - description: A list of tuples (with exactly two elements). - type: list - elements: tuple - required: true -''' +DOCUMENTATION = r""" +name: dict +short_description: Convert a list of tuples into a dictionary +version_added: 3.0.0 +author: Felix Fontein (@felixfontein) +description: + - Convert a list of tuples into a dictionary. This is a filter version of the C(dict) function. +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 @@ # "k2": 42, # "k3": "b" # } -''' +""" -RETURN = ''' - _value: - description: A dictionary with the provided key-value pairs. - type: dictionary -''' +RETURN = r""" +_value: + description: A dictionary with the provided key-value pairs. + type: dictionary +""" def dict_filter(sequence): diff --git a/plugins/filter/dict_kv.py b/plugins/filter/dict_kv.py index 59595f95737..8c4fb017525 100644 --- a/plugins/filter/dict_kv.py +++ b/plugins/filter/dict_kv.py @@ -6,37 +6,37 @@ from __future__ import (absolute_import, division, print_function) __metaclass__ = type -DOCUMENTATION = ''' - name: dict_kv - short_description: Convert a value to a dictionary with a single key-value pair - version_added: 1.3.0 - author: Stanislav German-Evtushenko (@giner) - description: - - Convert a value to a dictionary with a single key-value pair. - positional: key - options: - _input: - description: The value for the single key-value pair. - type: any - required: true - key: - description: The key for the single key-value pair. - type: any - required: true -''' - -EXAMPLES = ''' +DOCUMENTATION = r""" +name: dict_kv +short_description: Convert a value to a dictionary with a single key-value pair +version_added: 1.3.0 +author: Stanislav German-Evtushenko (@giner) +description: + - Convert a value to a dictionary with a single key-value pair. +positional: key +options: + _input: + description: The value for the single key-value pair. + type: any + required: true + key: + description: The key for the single key-value pair. + type: any + required: true +""" + +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 = ''' - _value: - description: A dictionary with a single key-value pair. - type: dictionary -''' +RETURN = r""" +_value: + description: A dictionary with a single key-value pair. + type: dictionary +""" def dict_kv(value, key): diff --git a/plugins/filter/from_csv.py b/plugins/filter/from_csv.py index 617f3147945..3a05769365d 100644 --- a/plugins/filter/from_csv.py +++ b/plugins/filter/from_csv.py @@ -8,51 +8,51 @@ from __future__ import absolute_import, division, print_function __metaclass__ = type -DOCUMENTATION = ''' - name: from_csv - short_description: Converts CSV text input into list of dicts - version_added: 2.3.0 - author: Andrew Pantuso (@Ajpantuso) - description: - - Converts CSV text input into list of dictionaries. - options: - _input: - description: A string containing a CSV document. - type: string - required: true - dialect: - description: - - The CSV dialect to use when parsing the CSV file. - - Possible values include V(excel), V(excel-tab) or V(unix). - type: str - default: excel - fieldnames: - description: - - A list of field names for every column. - - This is needed if the CSV does not have a header. - type: list - elements: str - delimiter: - description: - - A one-character string used to separate fields. - - When using this parameter, you change the default value used by O(dialect). - - The default value depends on the dialect used. - type: str - skipinitialspace: - description: - - Whether to ignore any whitespaces immediately following the delimiter. - - When using this parameter, you change the default value used by O(dialect). - - The default value depends on the dialect used. - type: bool - strict: - description: - - Whether to raise an exception on bad CSV input. - - When using this parameter, you change the default value used by O(dialect). - - The default value depends on the dialect used. - type: bool -''' - -EXAMPLES = ''' +DOCUMENTATION = r""" +name: from_csv +short_description: Converts CSV text input into list of dicts +version_added: 2.3.0 +author: Andrew Pantuso (@Ajpantuso) +description: + - Converts CSV text input into list of dictionaries. +options: + _input: + description: A string containing a CSV document. + type: string + required: true + dialect: + description: + - The CSV dialect to use when parsing the CSV file. + - Possible values include V(excel), V(excel-tab) or V(unix). + type: str + default: excel + fieldnames: + description: + - A list of field names for every column. + - This is needed if the CSV does not have a header. + type: list + elements: str + delimiter: + description: + - A one-character string used to separate fields. + - When using this parameter, you change the default value used by O(dialect). + - The default value depends on the dialect used. + type: str + skipinitialspace: + description: + - Whether to ignore any whitespaces immediately following the delimiter. + - When using this parameter, you change the default value used by O(dialect). + - The default value depends on the dialect used. + type: bool + strict: + description: + - Whether to raise an exception on bad CSV input. + - When using this parameter, you change the default value used by O(dialect). + - The default value depends on the dialect used. + type: bool +""" + +EXAMPLES = r""" - name: Parse a CSV file's contents ansible.builtin.debug: msg: >- @@ -71,14 +71,14 @@ # "Column 1": "bar", # "Value": "42", # } -''' - -RETURN = ''' - _value: - description: A list with one dictionary per row. - type: list - elements: dictionary -''' +""" + +RETURN = r""" +_value: + description: A list with one dictionary per row. + type: list + elements: dictionary +""" from ansible.errors import AnsibleFilterError diff --git a/plugins/filter/from_ini.py b/plugins/filter/from_ini.py index 5b4bd4a3af4..01ae150d087 100644 --- a/plugins/filter/from_ini.py +++ b/plugins/filter/from_ini.py @@ -6,43 +6,43 @@ from __future__ import absolute_import, division, print_function -DOCUMENTATION = r''' - name: from_ini - short_description: Converts INI text input into a dictionary - version_added: 8.2.0 - author: Steffen Scheib (@sscheib) - description: - - Converts INI text input into a dictionary. - options: - _input: - description: A string containing an INI document. - type: string - required: true -''' - -EXAMPLES = r''' - - name: Slurp an INI file - ansible.builtin.slurp: - src: /etc/rhsm/rhsm.conf - register: rhsm_conf - - - 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 - ansible.builtin.set_fact: - rhsm_dict: >- - {{ - rhsm_conf.content | b64decode | community.general.from_ini - }} -''' - -RETURN = ''' - _value: - description: A dictionary representing the INI file. - type: dictionary -''' +DOCUMENTATION = r""" +name: from_ini +short_description: Converts INI text input into a dictionary +version_added: 8.2.0 +author: Steffen Scheib (@sscheib) +description: + - Converts INI text input into a dictionary. +options: + _input: + description: A string containing an INI document. + type: string + required: true +""" + +EXAMPLES = r""" +- name: Slurp an INI file + ansible.builtin.slurp: + src: /etc/rhsm/rhsm.conf + register: rhsm_conf + +- 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 + ansible.builtin.set_fact: + rhsm_dict: >- + {{ + rhsm_conf.content | b64decode | community.general.from_ini + }} +""" + +RETURN = r""" +_value: + description: A dictionary representing the INI file. + type: dictionary +""" __metaclass__ = type diff --git a/plugins/filter/groupby_as_dict.py b/plugins/filter/groupby_as_dict.py index 8e29c5863c0..80c7ad7885d 100644 --- a/plugins/filter/groupby_as_dict.py +++ b/plugins/filter/groupby_as_dict.py @@ -6,29 +6,29 @@ 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. - - 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, - or when you need a dictionary with list values, or when you need to use deeply nested attributes. - 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 -''' +DOCUMENTATION = r""" +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. + - 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, or when you need a dictionary with list values, or when you need to use deeply nested attributes. +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 = ''' +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 @@ # other_value: # key: other_value # baz: bar -''' +""" -RETURN = ''' - _value: - description: A dictionary containing the dictionaries from the list as values. - type: dictionary -''' +RETURN = r""" +_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/jc.py b/plugins/filter/jc.py index 2fe3ef9d734..388fcf0d3fb 100644 --- a/plugins/filter/jc.py +++ b/plugins/filter/jc.py @@ -8,41 +8,41 @@ from __future__ import (absolute_import, division, print_function) __metaclass__ = type -DOCUMENTATION = ''' - name: jc - short_description: Convert output of many shell commands and file-types to JSON - version_added: 1.1.0 - author: Kelly Brazil (@kellyjonbrazil) - description: - - Convert output of many shell commands and file-types to JSON. - - Uses the L(jc library,https://github.com/kellyjonbrazil/jc). - positional: parser - options: - _input: - description: The data to convert. - type: string - required: true - parser: - 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." - - See U(https://github.com/kellyjonbrazil/jc#parsers) for the latest list of parsers. - type: string - required: true - quiet: - description: Set to V(false) to not suppress warnings. - type: boolean - default: true - raw: - description: Set to V(true) to return pre-processed JSON. - type: boolean - default: false - requirements: - - jc installed as a Python library (U(https://pypi.org/project/jc/)) -''' - -EXAMPLES = ''' +DOCUMENTATION = r""" +name: jc +short_description: Convert output of many shell commands and file-types to JSON +version_added: 1.1.0 +author: Kelly Brazil (@kellyjonbrazil) +description: + - Convert output of many shell commands and file-types to JSON. + - Uses the L(jc library,https://github.com/kellyjonbrazil/jc). +positional: parser +options: + _input: + description: The data to convert. + type: string + required: true + parser: + 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.' + - See U(https://github.com/kellyjonbrazil/jc#parsers) for the latest list of parsers. + type: string + required: true + quiet: + description: Set to V(false) to not suppress warnings. + type: boolean + default: true + raw: + description: Set to V(true) to return pre-processed JSON. + type: boolean + default: false +requirements: + - jc installed as a Python library (U(https://pypi.org/project/jc/)) +""" + +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 @@ # "operating_system": "GNU/Linux", # "processor": "x86_64" # } -''' +""" -RETURN = ''' - _value: - description: The processed output. - type: any -''' +RETURN = r""" +_value: + description: The processed output. + type: any +""" from ansible.errors import AnsibleError, AnsibleFilterError import importlib diff --git a/plugins/filter/json_query.py b/plugins/filter/json_query.py index 9e8fa4ef2e7..61223b07026 100644 --- a/plugins/filter/json_query.py +++ b/plugins/filter/json_query.py @@ -6,29 +6,29 @@ from __future__ import (absolute_import, division, print_function) __metaclass__ = type -DOCUMENTATION = ''' - name: json_query - short_description: Select a single element or a data subset from a complex data structure - description: - - This filter lets you query a complex JSON structure and iterate over it using a loop structure. - positional: expr - options: - _input: - description: - - The JSON data to query. - type: any - required: true - expr: - description: - - The query expression. - - See U(http://jmespath.org/examples.html) for examples. - type: string - required: true - requirements: - - jmespath -''' - -EXAMPLES = ''' +DOCUMENTATION = r""" +name: json_query +short_description: Select a single element or a data subset from a complex data structure +description: + - This filter lets you query a complex JSON structure and iterate over it using a loop structure. +positional: expr +options: + _input: + description: + - The JSON data to query. + type: any + required: true + expr: + description: + - The query expression. + - See U(http://jmespath.org/examples.html) for examples. + type: string + required: true +requirements: + - jmespath +""" + +EXAMPLES = r""" - name: Define data to work on in the examples below ansible.builtin.set_fact: domain_definition: @@ -99,13 +99,13 @@ 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 = ''' - _value: - description: The result of the query. - type: any -''' +RETURN = r""" +_value: + description: The result of the query. + type: any +""" from ansible.errors import AnsibleError, AnsibleFilterError diff --git a/plugins/filter/keep_keys.py b/plugins/filter/keep_keys.py index 97b706a9506..4cff4405fc0 100644 --- a/plugins/filter/keep_keys.py +++ b/plugins/filter/keep_keys.py @@ -7,99 +7,99 @@ from __future__ import (absolute_import, division, print_function) __metaclass__ = type -DOCUMENTATION = ''' - name: keep_keys - short_description: Keep specific keys from dictionaries in a list - version_added: "9.1.0" - author: - - Vladimir Botka (@vbotka) - - Felix Fontein (@felixfontein) - description: This filter keeps only specified keys from a provided list of dictionaries. - options: - _input: - description: - - A list of dictionaries. - - Top level keys must be strings. - type: list - elements: dictionary - required: true - target: - description: - - A single key or key pattern to keep, or a list of keys or keys patterns to keep. - - If O(matching_parameter=regex) there must be exactly one pattern provided. - type: raw - required: true - matching_parameter: - description: Specify the matching option of target keys. - type: str - default: equal - choices: - equal: Matches keys of exactly one of the O(target) items. - starts_with: Matches keys that start with one of the O(target) items. - ends_with: Matches keys that end with one of the O(target) items. - 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 = ''' - l: +DOCUMENTATION = r""" +name: keep_keys +short_description: Keep specific keys from dictionaries in a list +version_added: "9.1.0" +author: + - Vladimir Botka (@vbotka) + - Felix Fontein (@felixfontein) +description: This filter keeps only specified keys from a provided list of dictionaries. +options: + _input: + description: + - A list of dictionaries. + - Top level keys must be strings. + type: list + elements: dictionary + required: true + target: + description: + - A single key or key pattern to keep, or a list of keys or keys patterns to keep. + - If O(matching_parameter=regex) there must be exactly one pattern provided. + type: raw + required: true + matching_parameter: + description: Specify the matching option of target keys. + type: str + default: equal + choices: + equal: Matches keys of exactly one of the O(target) items. + starts_with: Matches keys that start with one of the O(target) items. + ends_with: Matches keys that end with one of the O(target) items. + 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 = r""" +- 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 = ''' - _value: - description: The list of dictionaries with selected keys. - type: list - elements: dictionary -''' +""" + +RETURN = r""" +_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, diff --git a/plugins/filter/lists_mergeby.py b/plugins/filter/lists_mergeby.py index 0e47d50172d..b34246993ca 100644 --- a/plugins/filter/lists_mergeby.py +++ b/plugins/filter/lists_mergeby.py @@ -6,65 +6,59 @@ 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 O(index). Optional - parameters O(recursive) and O(list_merge) control the merging of - 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 - O(list_merge) see Ansible User's Guide chapter "Using filters to - manipulate data" section R(Combining hashes/dictionaries, combine_filter) or the - filter P(ansible.builtin.combine#filter). - - 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) - because all elements of O(_input) can be either dictionaries - or lists. - type: list - elements: raw - required: true - another_list: - description: - - Another list of dictionaries, or a list of lists of dictionaries. - - This parameter can be specified multiple times. - type: list - elements: raw - 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 = ''' +DOCUMENTATION = r""" +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 O(index). Optional parameters O(recursive) and O(list_merge) control the merging + of 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 O(list_merge) see Ansible User's Guide chapter "Using filters + to manipulate data" section R(Combining hashes/dictionaries, combine_filter) or the filter P(ansible.builtin.combine#filter). +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) because all elements of O(_input) can be either dictionaries + or lists. + type: list + elements: raw + required: true + another_list: + description: + - Another list of dictionaries, or a list of lists of dictionaries. + - This parameter can be specified multiple times. + type: list + elements: raw + 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 = r""" # Some results below are manually formatted for better readability. The # dictionaries' keys will be sorted alphabetically in real output. @@ -193,14 +187,14 @@ # r: # - {index: a, foo: {x:1, y: 3, z: 4}} # - {index: b, foo: [Y1, Y2]} -''' - -RETURN = ''' - _value: - description: The merged list. - type: list - elements: dictionary -''' +""" + +RETURN = r""" +_value: + description: The merged list. + type: list + elements: dictionary +""" from ansible.errors import AnsibleFilterError from ansible.module_utils.six import string_types diff --git a/plugins/filter/random_mac.py b/plugins/filter/random_mac.py index 662c62b07cd..49910bc6be1 100644 --- a/plugins/filter/random_mac.py +++ b/plugins/filter/random_mac.py @@ -7,25 +7,25 @@ from __future__ import (absolute_import, division, print_function) __metaclass__ = type -DOCUMENTATION = ''' - name: random_mac - short_description: Generate a random MAC address - description: - - Generates random networking interfaces MAC addresses for a given prefix. - options: - _input: - description: A string prefix to use as a basis for the random MAC generated. - type: string - required: true - seed: - description: - - A randomization seed to initialize the process, used to get repeatable results. - - If no seed is provided, a system random source such as C(/dev/urandom) is used. - required: false - type: string -''' - -EXAMPLES = ''' +DOCUMENTATION = r""" +name: random_mac +short_description: Generate a random MAC address +description: + - Generates random networking interfaces MAC addresses for a given prefix. +options: + _input: + description: A string prefix to use as a basis for the random MAC generated. + type: string + required: true + seed: + description: + - A randomization seed to initialize the process, used to get repeatable results. + - If no seed is provided, a system random source such as C(/dev/urandom) is used. + required: false + type: string +""" + +EXAMPLES = r""" - name: Random MAC given a prefix ansible.builtin.debug: msg: "{{ '52:54:00' | community.general.random_mac }}" @@ -34,13 +34,13 @@ - name: With a seed ansible.builtin.debug: msg: "{{ '52:54:00' | community.general.random_mac(seed=inventory_hostname) }}" -''' +""" -RETURN = ''' - _value: - description: The generated MAC. - type: string -''' +RETURN = r""" +_value: + description: The generated MAC. + type: string +""" import re from random import Random, SystemRandom diff --git a/plugins/filter/remove_keys.py b/plugins/filter/remove_keys.py index 7a4d912d349..7baee12695f 100644 --- a/plugins/filter/remove_keys.py +++ b/plugins/filter/remove_keys.py @@ -7,99 +7,99 @@ from __future__ import (absolute_import, division, print_function) __metaclass__ = type -DOCUMENTATION = ''' - name: remove_keys - short_description: Remove specific keys from dictionaries in a list - version_added: "9.1.0" - author: - - Vladimir Botka (@vbotka) - - Felix Fontein (@felixfontein) - description: This filter removes only specified keys from a provided list of dictionaries. - options: - _input: - description: - - A list of dictionaries. - - Top level keys must be strings. - type: list - elements: dictionary - required: true - target: - description: - - A single key or key pattern to remove, or a list of keys or keys patterns to remove. - - If O(matching_parameter=regex) there must be exactly one pattern provided. - type: raw - required: true - matching_parameter: - description: Specify the matching option of target keys. - type: str - default: equal - choices: - equal: Matches keys of exactly one of the O(target) items. - starts_with: Matches keys that start with one of the O(target) items. - ends_with: Matches keys that end with one of the O(target) items. - 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 = ''' - l: +DOCUMENTATION = r""" +name: remove_keys +short_description: Remove specific keys from dictionaries in a list +version_added: "9.1.0" +author: + - Vladimir Botka (@vbotka) + - Felix Fontein (@felixfontein) +description: This filter removes only specified keys from a provided list of dictionaries. +options: + _input: + description: + - A list of dictionaries. + - Top level keys must be strings. + type: list + elements: dictionary + required: true + target: + description: + - A single key or key pattern to remove, or a list of keys or keys patterns to remove. + - If O(matching_parameter=regex) there must be exactly one pattern provided. + type: raw + required: true + matching_parameter: + description: Specify the matching option of target keys. + type: str + default: equal + choices: + equal: Matches keys of exactly one of the O(target) items. + starts_with: Matches keys that start with one of the O(target) items. + ends_with: Matches keys that end with one of the O(target) items. + 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 = r""" +- 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 = ''' - _value: - description: The list of dictionaries with selected keys removed. - type: list - elements: dictionary -''' +""" + +RETURN = r""" +_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, diff --git a/plugins/filter/replace_keys.py b/plugins/filter/replace_keys.py index 70b264eba6a..f317144be4e 100644 --- a/plugins/filter/replace_keys.py +++ b/plugins/filter/replace_keys.py @@ -7,129 +7,129 @@ from __future__ import (absolute_import, division, print_function) __metaclass__ = type -DOCUMENTATION = ''' - name: replace_keys - short_description: Replace specific keys in a list of dictionaries - version_added: "9.1.0" - author: - - Vladimir Botka (@vbotka) - - Felix Fontein (@felixfontein) - description: This filter replaces specified keys in a provided list of dictionaries. - options: - _input: - description: - - A list of dictionaries. - - Top level keys must be strings. - type: list - elements: dictionary - required: true - target: +DOCUMENTATION = r""" +name: replace_keys +short_description: Replace specific keys in a list of dictionaries +version_added: "9.1.0" +author: + - Vladimir Botka (@vbotka) + - Felix Fontein (@felixfontein) +description: This filter replaces specified keys in a provided list of dictionaries. +options: + _input: + description: + - A list of dictionaries. + - Top level keys must be strings. + type: list + elements: dictionary + required: true + target: + description: + - A list of dictionaries with attributes C(before) and C(after). + - The value of O(target[].after) replaces key matching O(target[].before). + type: list + elements: dictionary + required: true + suboptions: + before: description: - - A list of dictionaries with attributes C(before) and C(after). - - The value of O(target[].after) replaces key matching O(target[].before). - type: list - elements: dictionary - required: true - suboptions: - before: - description: - - A key or key pattern to change. - - The interpretation of O(target[].before) depends on O(matching_parameter). - - For a key that matches multiple O(target[].before)s, the B(first) matching O(target[].after) will be used. - type: str - after: - description: A matching key change to. - type: str - matching_parameter: - description: Specify the matching option of target keys. + - A key or key pattern to change. + - The interpretation of O(target[].before) depends on O(matching_parameter). + - For a key that matches multiple O(target[].before)s, the B(first) matching O(target[].after) will be used. type: str - default: equal - choices: - equal: Matches keys of exactly one of the O(target[].before) items. - 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 = ''' - l: + after: + description: A matching key change to. + type: str + matching_parameter: + description: Specify the matching option of target keys. + type: str + default: equal + choices: + equal: Matches keys of exactly one of the O(target[].before) items. + 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 = r""" +- 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 = ''' - _value: - description: The list of dictionaries with replaced keys. - type: list - elements: dictionary -''' +""" + +RETURN = r""" +_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, diff --git a/plugins/filter/reveal_ansible_type.py b/plugins/filter/reveal_ansible_type.py index 916aaff9306..3d7e40111c7 100644 --- a/plugins/filter/reveal_ansible_type.py +++ b/plugins/filter/reveal_ansible_type.py @@ -6,116 +6,116 @@ from __future__ import (absolute_import, division, print_function) __metaclass__ = type -DOCUMENTATION = ''' - name: reveal_ansible_type - short_description: Return input type - version_added: "9.2.0" - author: Vladimir Botka (@vbotka) - description: This filter returns input type. - options: - _input: - description: Input data. - type: raw - required: true - alias: - description: Data type aliases. - default: {} - type: dictionary -''' - -EXAMPLES = ''' +DOCUMENTATION = r""" +name: reveal_ansible_type +short_description: Return input type +version_added: "9.2.0" +author: Vladimir Botka (@vbotka) +description: This filter returns input type. +options: + _input: + description: Input data. + type: raw + required: true + alias: + description: Data type aliases. + default: {} + type: dictionary +""" + +EXAMPLES = r""" # Substitution converts str to AnsibleUnicode # ------------------------------------------- # String. AnsibleUnicode. -data: "abc" -result: '{{ data | community.general.reveal_ansible_type }}' +- data: "abc" + result: '{{ data | community.general.reveal_ansible_type }}' # result => AnsibleUnicode # String. AnsibleUnicode alias str. -alias: {"AnsibleUnicode": "str"} -data: "abc" -result: '{{ data | community.general.reveal_ansible_type(alias) }}' +- alias: {"AnsibleUnicode": "str"} + data: "abc" + result: '{{ data | community.general.reveal_ansible_type(alias) }}' # result => str # List. All items are AnsibleUnicode. -data: ["a", "b", "c"] -result: '{{ data | community.general.reveal_ansible_type }}' +- data: ["a", "b", "c"] + 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"} -result: '{{ data | community.general.reveal_ansible_type }}' +- data: {"a": "foo", "b": "bar", "c": "baz"} + 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"} -data: {1: 'a', 'b': 'b'} -result: '{{ data | community.general.reveal_ansible_type(alias) }}' +- alias: {"AnsibleUnicode": "str"} + data: {1: 'a', 'b': 'b'} + 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"} -data: {1: 'a', 2: 'b'} -result: '{{ data | community.general.reveal_ansible_type(alias) }}' +- alias: {"AnsibleUnicode": "str"} + data: {1: 'a', 2: 'b'} + result: '{{ data | community.general.reveal_ansible_type(alias) }}' # result => dict[int, str] # Dictionary. All keys are strings. Multiple types values. -alias: {"AnsibleUnicode": "str"} -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) }}' +- alias: {"AnsibleUnicode": "str"} + 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 => dict[str, bool|dict|float|int|list|str] # List. Multiple types items. -alias: {"AnsibleUnicode": "str"} -data: [1, 2, 1.1, 'abc', True, ['x', 'y', 'z'], {'x': 1, 'y': 2}] -result: '{{ data | community.general.reveal_ansible_type(alias) }}' +- alias: {"AnsibleUnicode": "str"} + data: [1, 2, 1.1, 'abc', true, ['x', 'y', 'z'], {'x': 1, 'y': 2}] + result: '{{ data | community.general.reveal_ansible_type(alias) }}' # result => list[bool|dict|float|int|list|str] -''' +""" -RETURN = ''' - _value: - description: Type of the data. - type: str -''' +RETURN = r""" +_value: + description: Type of the data. + type: str +""" from ansible_collections.community.general.plugins.plugin_utils.ansible_type import _ansible_type diff --git a/plugins/filter/to_ini.py b/plugins/filter/to_ini.py index 2bc41f6962e..f06763ac66c 100644 --- a/plugins/filter/to_ini.py +++ b/plugins/filter/to_ini.py @@ -6,34 +6,34 @@ from __future__ import absolute_import, division, print_function -DOCUMENTATION = r''' - name: to_ini - short_description: Converts a dictionary to the INI file format - version_added: 8.2.0 - author: Steffen Scheib (@sscheib) - description: - - Converts a dictionary to the INI file format. - options: - _input: - description: The dictionary that should be converted to the INI format. - type: dictionary - required: true -''' - -EXAMPLES = r''' - - name: Define a dictionary - ansible.builtin.set_fact: - my_dict: - section_name: - key_name: 'key value' - - another_section: - connection: 'ssh' - - - name: Write dictionary to INI file - ansible.builtin.copy: - dest: /tmp/test.ini - content: '{{ my_dict | community.general.to_ini }}' +DOCUMENTATION = r""" +name: to_ini +short_description: Converts a dictionary to the INI file format +version_added: 8.2.0 +author: Steffen Scheib (@sscheib) +description: + - Converts a dictionary to the INI file format. +options: + _input: + description: The dictionary that should be converted to the INI format. + type: dictionary + required: true +""" + +EXAMPLES = r""" +- name: Define a dictionary + ansible.builtin.set_fact: + my_dict: + section_name: + key_name: 'key value' + + another_section: + connection: 'ssh' + +- name: Write dictionary to INI file + ansible.builtin.copy: + dest: /tmp/test.ini + content: '{{ my_dict | community.general.to_ini }}' # /tmp/test.ini will look like this: # [section_name] @@ -41,13 +41,13 @@ # # [another_section] # connection = ssh -''' +""" -RETURN = r''' - _value: - description: A string formatted as INI file. - type: string -''' +RETURN = r""" +_value: + description: A string formatted as INI file. + type: string +""" __metaclass__ = type diff --git a/plugins/filter/unicode_normalize.py b/plugins/filter/unicode_normalize.py index dfbf20c573a..9401197eba0 100644 --- a/plugins/filter/unicode_normalize.py +++ b/plugins/filter/unicode_normalize.py @@ -7,45 +7,45 @@ from __future__ import absolute_import, division, print_function __metaclass__ = type -DOCUMENTATION = ''' - name: unicode_normalize - short_description: Normalizes unicode strings to facilitate comparison of characters with normalized forms - version_added: 3.7.0 - author: Andrew Pantuso (@Ajpantuso) - description: - - Normalizes unicode strings to facilitate comparison of characters with normalized forms. - positional: form - options: - _input: - description: A unicode string. - type: string - required: true - form: - description: - - The normal form to use. - - See U(https://docs.python.org/3/library/unicodedata.html#unicodedata.normalize) for details. - type: string - default: NFC - choices: - - NFC - - NFD - - NFKC - - NFKD -''' - -EXAMPLES = ''' +DOCUMENTATION = r""" +name: unicode_normalize +short_description: Normalizes unicode strings to facilitate comparison of characters with normalized forms +version_added: 3.7.0 +author: Andrew Pantuso (@Ajpantuso) +description: + - Normalizes unicode strings to facilitate comparison of characters with normalized forms. +positional: form +options: + _input: + description: A unicode string. + type: string + required: true + form: + description: + - The normal form to use. + - See U(https://docs.python.org/3/library/unicodedata.html#unicodedata.normalize) for details. + type: string + default: NFC + choices: + - NFC + - NFD + - NFKC + - NFKD +""" + +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 = ''' - _value: - description: The normalized unicode string of the specified normal form. - type: string -''' +RETURN = r""" +_value: + description: The normalized unicode string of the specified normal form. + type: string +""" from unicodedata import normalize diff --git a/plugins/filter/version_sort.py b/plugins/filter/version_sort.py index 09eedbf5632..f5a844c542d 100644 --- a/plugins/filter/version_sort.py +++ b/plugins/filter/version_sort.py @@ -6,34 +6,34 @@ from __future__ import (absolute_import, division, print_function) __metaclass__ = type -DOCUMENTATION = ''' - name: version_sort - short_description: Sort a list according to version order instead of pure alphabetical one - version_added: 2.2.0 - author: Eric L. (@ericzolf) - description: - - Sort a list according to version order instead of pure alphabetical one. - options: - _input: - description: A list of strings to sort. - type: list - elements: string - required: true -''' - -EXAMPLES = ''' +DOCUMENTATION = r""" +name: version_sort +short_description: Sort a list according to version order instead of pure alphabetical one +version_added: 2.2.0 +author: Eric L. (@ericzolf) +description: + - Sort a list according to version order instead of pure alphabetical one. +options: + _input: + description: A list of strings to sort. + type: list + elements: string + required: true +""" + +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 = ''' - _value: - description: The list of strings sorted by version. - type: list - elements: string -''' +""" + +RETURN = r""" +_value: + description: The list of strings sorted by version. + type: list + elements: string +""" from ansible_collections.community.general.plugins.module_utils.version import LooseVersion