a-c-m
/
community.general
mirror of https://github.com/ansible-collections/community.general.git
1
0
Fork 0
Code Issues Packages Projects Releases Wiki Activity

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

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

* remove inventory plugins from PR

* adjustments from review

* typo
pull/9547/head
Alexei Znamensky 2025-01-07 18:33:28 +13:00 committed by GitHub
parent 8cef0ee551
commit 3af793c2c1
No known key found for this signature in database
GPG Key ID: B5690EEEBB952194
22 changed files with 696 additions and 699 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

4
plugins/become/pfexec.py
View File

@ -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
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:

2
plugins/callback/default_without_diff.py
View File

@ -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
"""

3
plugins/callback/yaml.py
View File

@ -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.

53
plugins/filter/accumulate.py
View File

@ -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

43
plugins/filter/counter.py
View File

@ -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

52
plugins/filter/crc32.py
View File

@ -16,33 +16,33 @@ except ImportError:
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
'''
EXAMPLES = '''
- name: Checksum a test string
ansible.builtin.debug:
msg: "{{ 'test' | community.general.crc32 }}"
'''
RETURN = '''
_value:
description: CRC32 checksum.
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 = r"""
- name: Checksum a test string
ansible.builtin.debug:
msg: "{{ 'test' | community.general.crc32 }}"
"""
RETURN = r"""
_value:
description: CRC32 checksum.
type: string
"""
def crc32s(value):

42
plugins/filter/dict.py
View File

@ -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 @@ EXAMPLES = '''
# "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):

50
plugins/filter/dict_kv.py
View File

@ -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
'''
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 = '''
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):

102
plugins/filter/from_csv.py
View File

@ -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
'''
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 = '''
EXAMPLES = r"""
- name: Parse a CSV file's contents
ansible.builtin.debug:
msg: >-
@ -71,14 +71,14 @@ EXAMPLES = '''
# "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

66
plugins/filter/from_ini.py
View File

@ -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
'''
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
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: 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
}}
'''
- 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
'''
RETURN = r"""
_value:
description: A dictionary representing the INI file.
type: dictionary
"""
__metaclass__ = type

56
plugins/filter/groupby_as_dict.py
View File

@ -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 @@ EXAMPLES = '''
# 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

80
plugins/filter/jc.py
View File

@ -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/))
'''
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 = '''
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 = '''
_value:
description: The processed output.
type: any
'''
RETURN = r"""
_value:
description: The processed output.
type: any
"""
from ansible.errors import AnsibleError, AnsibleFilterError
import importlib

56
plugins/filter/json_query.py
View File

@ -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
'''
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 = '''
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 = '''
_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

108
plugins/filter/keep_keys.py
View File

@ -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.
'''
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 = '''
l:
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,

124
plugins/filter/lists_mergeby.py
View File

@ -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).
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
"""
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 = '''
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 = '''
_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

48
plugins/filter/random_mac.py
View File

@ -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
'''
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 = '''
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 = '''
_value:
description: The generated MAC.
type: string
'''
RETURN = r"""
_value:
description: The generated MAC.
type: string
"""
import re
from random import Random, SystemRandom

108
plugins/filter/remove_keys.py
View File

@ -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.
'''
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 = '''
l:
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,

124
plugins/filter/replace_keys.py
View File

@ -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:
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.
- 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 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).
'''
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 = '''
l:
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,

104
plugins/filter/reveal_ansible_type.py
View File

@ -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
'''
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 = '''
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

62
plugins/filter/to_ini.py
View File

@ -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
'''
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'
EXAMPLES = r"""
- name: Define a dictionary
ansible.builtin.set_fact:
my_dict:
section_name:
key_name: 'key value'
another_section:
connection: 'ssh'
another_section:
connection: 'ssh'
- name: Write dictionary to INI file
ansible.builtin.copy:
dest: /tmp/test.ini
content: '{{ my_dict | community.general.to_ini }}'
- 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 @@ EXAMPLES = r'''
#
# [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

64
plugins/filter/unicode_normalize.py
View File

@ -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
'''
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 = '''
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

44
plugins/filter/version_sort.py
View File

@ -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
'''
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 = '''
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