Release 4.4.0.

* Fully use Ansible's option handling. Deprecate not specifying sender.

* Update plugins/callback/mail.py

Co-authored-by: Andrew Klychkov <aaklychkov@mail.ru>

Co-authored-by: Andrew Klychkov <aaklychkov@mail.ru>
(cherry picked from commit e09254df91)

Co-authored-by: Felix Fontein <felix@fontein.de>

.azure-pipelines/azure-pipelines.yml

@@ -206,14 +206,14 @@ stages:
         parameters:
           testFormat: devel/{0}
           targets:
-            - name: macOS 11.1
-              test: macos/11.1
+            - name: macOS 12.0
+              test: macos/12.0
             - name: RHEL 7.9
               test: rhel/7.9
             - name: RHEL 8.5
               test: rhel/8.5
-            - name: FreeBSD 12.2
-              test: freebsd/12.2
+            - name: FreeBSD 12.3
+              test: freebsd/12.3
             - name: FreeBSD 13.0
               test: freebsd/13.0
           groups:

.github/BOTMETA.yml

@@ -118,6 +118,8 @@ files:
   $doc_fragments/xenserver.py:
     maintainers: bvitnik
     labels: xenserver
+  $filters/counter.py:
+    maintainers: keilr
   $filters/dict.py:
     maintainers: felixfontein
   $filters/dict_kv.py:
@@ -164,9 +166,9 @@ files:
   $inventories/proxmox.py:
     maintainers: $team_virt ilijamt
   $inventories/xen_orchestra.py:
-    maintainers: shinuza
+    maintainers: ddelnano shinuza
   $inventories/icinga2.py:
-    maintainers: bongoeadgc6
+    maintainers: BongoEADGC6
   $inventories/scaleway.py:
     maintainers: $team_scaleway
     labels: cloud scaleway
@@ -322,6 +324,10 @@ files:
   $modules/cloud/misc/proxmox_kvm.py:
     maintainers: helldorado
     ignore: skvidal
+  $modules/cloud/misc/proxmox_nic.py:
+    maintainers: Kogelvis
+  $modules/cloud/misc/proxmox_tasks_info:
+    maintainers: paginabianca
   $modules/cloud/misc/proxmox_template.py:
     maintainers: UnderGreen
     ignore: skvidal
@@ -534,6 +540,8 @@ files:
     maintainers: adamgoossens
   $modules/identity/keycloak/keycloak_identity_provider.py:
     maintainers: laurpaum
+  $modules/identity/keycloak/keycloak_realm_info.py:
+    maintainers: fynncfchen
   $modules/identity/keycloak/keycloak_realm.py:
     maintainers: kris2kris
   $modules/identity/keycloak/keycloak_role.py:
@@ -722,6 +730,8 @@ files:
     maintainers: mwarkentin
   $modules/packaging/language/bundler.py:
     maintainers: thoiberg
+  $modules/packaging/language/cargo.py:
+    maintainers: radek-sprta
   $modules/packaging/language/composer.py:
     maintainers: dmtrs
     ignore: resmo
@@ -903,6 +913,10 @@ files:
   $modules/remote_management/manageiq/:
     labels: manageiq
     maintainers: $team_manageiq
+  $modules/remote_management/manageiq/manageiq_alert_profiles.py:
+    maintainers: elad661
+  $modules/remote_management/manageiq/manageiq_alerts.py:
+    maintainers: elad661
   $modules/remote_management/manageiq/manageiq_group.py:
     maintainers: evertmulder
   $modules/remote_management/manageiq/manageiq_tenant.py:
@@ -1008,6 +1022,8 @@ files:
   $modules/system/gconftool2.py:
     maintainers: Akasurde kevensen
     labels: gconftool2
+  $modules/system/homectl.py:
+    maintainers: jameslivulpi
   $modules/system/interfaces_file.py:
     maintainers: obourdon hryamzik
     labels: interfaces_file
@@ -1090,6 +1106,8 @@ files:
     keywords: beadm dladm illumos ipadm nexenta omnios openindiana pfexec smartos solaris sunos zfs zpool
   $modules/system/ssh_config.py:
     maintainers: gaqzi Akasurde
+  $modules/system/sudoers.py:
+    maintainers: JonEllis
   $modules/system/svc.py:
     maintainers: bcoca
   $modules/system/syspatch.py:

CHANGELOG.rst

@@ -6,6 +6,128 @@ Community General Release Notes
 
 This changelog describes changes after version 3.0.0.
 
+v4.4.0
+======
+
+Release Summary
+---------------
+
+Regular features and bugfixes release.
+
+Minor Changes
+-------------
+
+- cobbler inventory plugin - add ``include_profiles`` option (https://github.com/ansible-collections/community.general/pull/4068).
+- gitlab_project_variable - new ``variables`` parameter (https://github.com/ansible-collections/community.general/issues/4038).
+- icinga2 inventory plugin - implemented constructed interface (https://github.com/ansible-collections/community.general/pull/4088).
+- linode inventory plugin - allow templating of ``access_token`` variable in Linode inventory plugin (https://github.com/ansible-collections/community.general/pull/4040).
+- lists_mergeby filter plugin - add parameters ``list_merge`` and ``recursive``. These are only supported when used with ansible-base 2.10 or ansible-core, but not with Ansible 2.9 (https://github.com/ansible-collections/community.general/pull/4058).
+- lxc_container - added ``wait_for_container`` parameter. If ``true`` the module will wait until the running task reports success as the status (https://github.com/ansible-collections/community.general/pull/4039).
+- mail callback plugin - add ``Message-ID`` and ``Date`` headers (https://github.com/ansible-collections/community.general/issues/4055, https://github.com/ansible-collections/community.general/pull/4056).
+- mail callback plugin - properly use Ansible's option handling to split lists (https://github.com/ansible-collections/community.general/pull/4140).
+- nmcli - adds ``routes6`` and ``route_metric6`` parameters for supporting IPv6 routes (https://github.com/ansible-collections/community.general/issues/4059).
+- opennebula - add the release action for VMs in the ``HOLD`` state (https://github.com/ansible-collections/community.general/pull/4036).
+- opentelemetry_plugin - enrich service when using the ``docker_login`` (https://github.com/ansible-collections/community.general/pull/4104).
+- proxmox modules - move ``HAS_PROXMOXER`` check into ``module_utils`` (https://github.com/ansible-collections/community.general/pull/4030).
+- scaleway inventory plugin - add profile parameter ``scw_profile`` (https://github.com/ansible-collections/community.general/pull/4049).
+- snap - add option ``options`` permitting to set options using the ``snap set`` command (https://github.com/ansible-collections/community.general/pull/3943).
+
+Deprecated Features
+-------------------
+
+- mail callback plugin - not specifying ``sender`` is deprecated and will be disallowed in community.general 6.0.0 (https://github.com/ansible-collections/community.general/pull/4140).
+
+Bugfixes
+--------
+
+- cargo - fix detection of outdated packages when ``state=latest`` (https://github.com/ansible-collections/community.general/pull/4052).
+- cargo - fix incorrectly reported changed status for packages with a name containing a hyphen (https://github.com/ansible-collections/community.general/issues/4044, https://github.com/ansible-collections/community.general/pull/4052).
+- gitlab_project_variable - add missing documentation about GitLab versions that support ``environment_scope`` and ``variable_type`` (https://github.com/ansible-collections/community.general/issues/4038).
+- gitlab_project_variable - allow to set same variable name under different environment scopes. Due this change, the return value ``project_variable`` differs from previous version in check mode. It was counting ``updated`` values, because it was accidentally overwriting environment scopes (https://github.com/ansible-collections/community.general/issues/4038).
+- gitlab_project_variable - fix idempotent change behaviour for float and integer variables (https://github.com/ansible-collections/community.general/issues/4038).
+- gitlab_runner - use correct API endpoint to create and retrieve project level runners when using ``project`` (https://github.com/ansible-collections/community.general/pull/3965).
+- listen_ports_facts - local port regex was not handling well IPv6 only binding. Fixes the regex for ``ss`` (https://github.com/ansible-collections/community.general/pull/4092).
+- mail callback plugin - fix crash on Python 3 (https://github.com/ansible-collections/community.general/issues/4025, https://github.com/ansible-collections/community.general/pull/4026).
+- opentelemetry - fix generating a trace with a task containing ``no_log: true`` (https://github.com/ansible-collections/community.general/pull/4043).
+- python_requirements_info - store ``mismatched`` return values per package as documented in the module (https://github.com/ansible-collections/community.general/pull/4078).
+- yarn - fix incorrect handling of ``yarn list`` and ``yarn global list`` output that could result in fatal error (https://github.com/ansible-collections/community.general/pull/4050).
+- yarn - fix incorrectly reported status when installing a package globally (https://github.com/ansible-collections/community.general/issues/4045, https://github.com/ansible-collections/community.general/pull/4050).
+- yarn - fix missing ``~`` expansion in yarn global install folder which resulted in incorrect task status (https://github.com/ansible-collections/community.general/issues/4045, https://github.com/ansible-collections/community.general/pull/4048).
+
+New Modules
+-----------
+
+System
+~~~~~~
+
+- homectl - Manage user accounts with systemd-homed
+
+v4.3.0
+======
+
+Release Summary
+---------------
+
+Regular feature and bugfix release.
+
+Minor Changes
+-------------
+
+- ipa_dnszone - ``dynamicupdate`` is now a boolean parameter, instead of a string parameter accepting ``"true"`` and ``"false"``. Also the module is now idempotent with respect to ``dynamicupdate`` (https://github.com/ansible-collections/community.general/pull/3374).
+- ipa_dnszone - add DNS zone synchronization support (https://github.com/ansible-collections/community.general/pull/3374).
+- ipmi_power - add ``machine`` option to ensure the power state via the remote target address (https://github.com/ansible-collections/community.general/pull/3968).
+- mattermost - add the possibility to send attachments instead of text messages (https://github.com/ansible-collections/community.general/pull/3946).
+- nmcli - add ``wireguard`` connection type (https://github.com/ansible-collections/community.general/pull/3985).
+- proxmox - add ``clone`` parameter (https://github.com/ansible-collections/community.general/pull/3930).
+- puppet - remove deprecation for ``show_diff`` parameter. Its alias ``show-diff`` is still deprecated and will be removed in community.general 7.0.0 (https://github.com/ansible-collections/community.general/pull/3980).
+- scaleway_compute - add possibility to use project identifier (new ``project`` option) instead of deprecated organization identifier (https://github.com/ansible-collections/community.general/pull/3951).
+- scaleway_volume - all volumes are systematically created on par1 (https://github.com/ansible-collections/community.general/pull/3964).
+
+Bugfixes
+--------
+
+- Various modules and plugins - use vendored version of ``distutils.version`` instead of the deprecated Python standard library ``distutils`` (https://github.com/ansible-collections/community.general/pull/3936).
+- alternatives - fix output parsing for alternatives groups (https://github.com/ansible-collections/community.general/pull/3976).
+- jail connection plugin - replace deprecated ``distutils.spawn.find_executable`` with Ansible's ``get_bin_path`` to find the executable (https://github.com/ansible-collections/community.general/pull/3934).
+- lxd connection plugin - replace deprecated ``distutils.spawn.find_executable`` with Ansible's ``get_bin_path`` to find the ``lxc`` executable (https://github.com/ansible-collections/community.general/pull/3934).
+- passwordstore lookup plugin - replace deprecated ``distutils.util.strtobool`` with Ansible's ``convert_bool.boolean`` to interpret values for the ``create``, ``returnall``, ``overwrite``, 'backup``, and ``nosymbols`` options (https://github.com/ansible-collections/community.general/pull/3934).
+- say callback plugin - replace deprecated ``distutils.spawn.find_executable`` with Ansible's ``get_bin_path`` to find the ``say`` resp. ``espeak`` executables (https://github.com/ansible-collections/community.general/pull/3934).
+- scaleway_user_data - fix double-quote added where no double-quote is needed to user data in scaleway's server (``Content-type`` -> ``Content-Type``) (https://github.com/ansible-collections/community.general/pull/3940).
+- slack - add ``charset`` to HTTP headers to avoid Slack API warning (https://github.com/ansible-collections/community.general/issues/3932).
+- zone connection plugin - replace deprecated ``distutils.spawn.find_executable`` with Ansible's ``get_bin_path`` to find the executable (https://github.com/ansible-collections/community.general/pull/3934).
+
+New Plugins
+-----------
+
+Filter
+~~~~~~
+
+- counter - Counts hashable elements in a sequence
+
+New Modules
+-----------
+
+Identity
+~~~~~~~~
+
+keycloak
+^^^^^^^^
+
+- keycloak_realm_info - Allows obtaining Keycloak realm public information via Keycloak API
+
+Packaging
+~~~~~~~~~
+
+language
+^^^^^^^^
+
+- cargo - Manage Rust packages with cargo
+
+System
+~~~~~~
+
+- sudoers - Manage sudoers files
+
 v4.2.0
 ======
 

CONTRIBUTING.md

@@ -24,7 +24,7 @@ Also, consider taking up a valuable, reviewed, but abandoned pull request which
 
 * Try committing your changes with an informative but short commit message.
 * Do not squash your commits and force-push to your branch if not needed. Reviews of your pull request are much easier with individual commits to comprehend the pull request history. All commits of your pull request branch will be squashed into one commit by GitHub upon merge.
-* Do not add merge commits to your PR. The bot will complain and you will have to rebase ([instructions for rebasing](https://docs.ansible.com/ansible/latest/dev_guide/developing_rebasing.html)) to remove them before your PR can be merged. To avoid that git automatically does merges during pulls, you can configure it to do rebases instead by running `git config pull.rebase true` inside the respository checkout.
+* Do not add merge commits to your PR. The bot will complain and you will have to rebase ([instructions for rebasing](https://docs.ansible.com/ansible/latest/dev_guide/developing_rebasing.html)) to remove them before your PR can be merged. To avoid that git automatically does merges during pulls, you can configure it to do rebases instead by running `git config pull.rebase true` inside the repository checkout.
 * Make sure your PR includes a [changelog fragment](https://docs.ansible.com/ansible/devel/community/development_process.html#changelogs-how-to). (You must not include a fragment for new modules or new plugins, except for test and filter plugins. Also you shouldn't include one for docs-only changes. If you're not sure, simply don't include one, we'll tell you whether one is needed or not :) )
 * Avoid reformatting unrelated parts of the codebase in your PR. These types of changes will likely be requested for reversion, create additional work for reviewers, and may cause approval to be delayed.
 
@@ -36,6 +36,54 @@ If you want to test a PR locally, refer to [our testing guide](https://github.co
 
 If you find any inconsistencies or places in this document which can be improved, feel free to raise an issue or pull request to fix it.
 
+## Run sanity, unit or integration tests locally
+
+You have to check out the repository into a specific path structure to be able to run `ansible-test`. The path to the git checkout must end with `.../ansible_collections/community/general`. Please see [our testing guide](https://github.com/ansible/community-docs/blob/main/test_pr_locally_guide.rst) for instructions on how to check out the repository into a correct path structure. The short version of these instructions is:
+
+```.bash
+mkdir -p ~/dev/ansible_collections/community
+git clone https://github.com/ansible-collections/community.general.git ~/dev/ansible_collections/community/general
+cd ~/dev/ansible_collections/community/general
+```
+
+Then you can run `ansible-test` (which is a part of [ansible-core](https://pypi.org/project/ansible-core/)) inside the checkout. The following example commands expect that you have installed Docker or Podman. Note that Podman has only been supported by more recent ansible-core releases. If you are using Docker, the following will work with Ansible 2.9+.
+
+The following commands show how to run sanity tests:
+
+```.bash
+# Run sanity tests for all files in the collection:
+ansible-test sanity --docker -v
+
+# Run sanity tests for the given files and directories:
+ansible-test sanity --docker -v plugins/modules/system/pids.py tests/integration/targets/pids/
+```
+
+The following commands show how to run unit tests:
+
+```.bash
+# Run all unit tests:
+ansible-test units --docker -v
+
+# Run all unit tests for one Python version (a lot faster):
+ansible-test units --docker -v --python 3.8
+
+# Run a specific unit test (for the nmcli module) for one Python version:
+ansible-test units --docker -v --python 3.8 tests/unit/plugins/modules/net_tools/test_nmcli.py
+```
+
+The following commands show how to run integration tests:
+
+```.bash
+# Run integration tests for the interfaces_files module in a Docker container using the
+# fedora35 operating system image (the supported images depend on your ansible-core version):
+ansible-test integration --docker fedora35 -v interfaces_file
+
+# Run integration tests for the flattened lookup **without any isolation**:
+ansible-test integration -v lookup_flattened
+```
+
+If you are unsure about the integration test target name for a module or plugin, you can take a look in `tests/integration/targets/`. Tests for plugins have the plugin type prepended.
+
 ## Creating new modules or plugins
 
 Creating new modules and plugins requires a bit more work than other Pull Requests.

changelogs/changelog.yaml

@@ -1238,3 +1238,164 @@ releases:
       name: ilo_redfish_info
       namespace: remote_management.redfish
     release_date: '2021-12-21'
+  4.3.0:
+    changes:
+      bugfixes:
+      - Various modules and plugins - use vendored version of ``distutils.version``
+        instead of the deprecated Python standard library ``distutils`` (https://github.com/ansible-collections/community.general/pull/3936).
+      - alternatives - fix output parsing for alternatives groups (https://github.com/ansible-collections/community.general/pull/3976).
+      - jail connection plugin - replace deprecated ``distutils.spawn.find_executable``
+        with Ansible's ``get_bin_path`` to find the executable (https://github.com/ansible-collections/community.general/pull/3934).
+      - lxd connection plugin - replace deprecated ``distutils.spawn.find_executable``
+        with Ansible's ``get_bin_path`` to find the ``lxc`` executable (https://github.com/ansible-collections/community.general/pull/3934).
+      - passwordstore lookup plugin - replace deprecated ``distutils.util.strtobool``
+        with Ansible's ``convert_bool.boolean`` to interpret values for the ``create``,
+        ``returnall``, ``overwrite``, 'backup``, and ``nosymbols`` options (https://github.com/ansible-collections/community.general/pull/3934).
+      - say callback plugin - replace deprecated ``distutils.spawn.find_executable``
+        with Ansible's ``get_bin_path`` to find the ``say`` resp. ``espeak`` executables
+        (https://github.com/ansible-collections/community.general/pull/3934).
+      - scaleway_user_data - fix double-quote added where no double-quote is needed
+        to user data in scaleway's server (``Content-type`` -> ``Content-Type``) (https://github.com/ansible-collections/community.general/pull/3940).
+      - slack - add ``charset`` to HTTP headers to avoid Slack API warning (https://github.com/ansible-collections/community.general/issues/3932).
+      - zone connection plugin - replace deprecated ``distutils.spawn.find_executable``
+        with Ansible's ``get_bin_path`` to find the executable (https://github.com/ansible-collections/community.general/pull/3934).
+      minor_changes:
+      - ipa_dnszone - ``dynamicupdate`` is now a boolean parameter, instead of a string
+        parameter accepting ``"true"`` and ``"false"``. Also the module is now idempotent
+        with respect to ``dynamicupdate`` (https://github.com/ansible-collections/community.general/pull/3374).
+      - ipa_dnszone - add DNS zone synchronization support (https://github.com/ansible-collections/community.general/pull/3374).
+      - ipmi_power - add ``machine`` option to ensure the power state via the remote
+        target address (https://github.com/ansible-collections/community.general/pull/3968).
+      - mattermost - add the possibility to send attachments instead of text messages
+        (https://github.com/ansible-collections/community.general/pull/3946).
+      - nmcli - add ``wireguard`` connection type (https://github.com/ansible-collections/community.general/pull/3985).
+      - proxmox - add ``clone`` parameter (https://github.com/ansible-collections/community.general/pull/3930).
+      - puppet - remove deprecation for ``show_diff`` parameter. Its alias ``show-diff``
+        is still deprecated and will be removed in community.general 7.0.0 (https://github.com/ansible-collections/community.general/pull/3980).
+      - scaleway_compute - add possibility to use project identifier (new ``project``
+        option) instead of deprecated organization identifier (https://github.com/ansible-collections/community.general/pull/3951).
+      - scaleway_volume - all volumes are systematically created on par1 (https://github.com/ansible-collections/community.general/pull/3964).
+      release_summary: Regular feature and bugfix release.
+    fragments:
+    - 3374-add-ipa-ptr-sync-support.yml
+    - 3921-add-counter-filter-plugin.yml
+    - 3930-proxmox-add-clone.yaml
+    - 3933-slack-charset-header.yaml
+    - 3934-distutils.yml
+    - 3936-distutils.version.yml
+    - 3940_fix_contenttype_scaleway_user_data.yml
+    - 3946-mattermost_attachments.yml
+    - 3951-scaleway_compute_add_project_id.yml
+    - 3964-scaleway_volume_add_region.yml
+    - 3968-ipmi_power-add-machine-option.yaml
+    - 3976-fix-alternatives-parsing.yml
+    - 3980-puppet-show_diff.yml
+    - 3985-nmcli-add-wireguard-connection-type.yml
+    - 4.3.0.yml
+    modules:
+    - description: Manage Rust packages with cargo
+      name: cargo
+      namespace: packaging.language
+    - description: Allows obtaining Keycloak realm public information via Keycloak
+        API
+      name: keycloak_realm_info
+      namespace: identity.keycloak
+    - description: Manage sudoers files
+      name: sudoers
+      namespace: system
+    plugins:
+      filter:
+      - description: Counts hashable elements in a sequence
+        name: counter
+        namespace: null
+    release_date: '2022-01-11'
+  4.4.0:
+    changes:
+      bugfixes:
+      - cargo - fix detection of outdated packages when ``state=latest`` (https://github.com/ansible-collections/community.general/pull/4052).
+      - cargo - fix incorrectly reported changed status for packages with a name containing
+        a hyphen (https://github.com/ansible-collections/community.general/issues/4044,
+        https://github.com/ansible-collections/community.general/pull/4052).
+      - gitlab_project_variable - add missing documentation about GitLab versions
+        that support ``environment_scope`` and ``variable_type`` (https://github.com/ansible-collections/community.general/issues/4038).
+      - 'gitlab_project_variable - allow to set same variable name under different
+        environment scopes. Due this change, the return value ``project_variable``
+        differs from previous version in check mode. It was counting ``updated`` values,
+        because it was accidentally overwriting environment scopes (https://github.com/ansible-collections/community.general/issues/4038).
+
+        '
+      - gitlab_project_variable - fix idempotent change behaviour for float and integer
+        variables (https://github.com/ansible-collections/community.general/issues/4038).
+      - gitlab_runner - use correct API endpoint to create and retrieve project level
+        runners when using ``project`` (https://github.com/ansible-collections/community.general/pull/3965).
+      - listen_ports_facts - local port regex was not handling well IPv6 only binding.
+        Fixes the regex for ``ss`` (https://github.com/ansible-collections/community.general/pull/4092).
+      - mail callback plugin - fix crash on Python 3 (https://github.com/ansible-collections/community.general/issues/4025,
+        https://github.com/ansible-collections/community.general/pull/4026).
+      - 'opentelemetry - fix generating a trace with a task containing ``no_log: true``
+        (https://github.com/ansible-collections/community.general/pull/4043).'
+      - python_requirements_info - store ``mismatched`` return values per package
+        as documented in the module (https://github.com/ansible-collections/community.general/pull/4078).
+      - yarn - fix incorrect handling of ``yarn list`` and ``yarn global list`` output
+        that could result in fatal error (https://github.com/ansible-collections/community.general/pull/4050).
+      - yarn - fix incorrectly reported status when installing a package globally
+        (https://github.com/ansible-collections/community.general/issues/4045, https://github.com/ansible-collections/community.general/pull/4050).
+      - yarn - fix missing ``~`` expansion in yarn global install folder which resulted
+        in incorrect task status (https://github.com/ansible-collections/community.general/issues/4045,
+        https://github.com/ansible-collections/community.general/pull/4048).
+      deprecated_features:
+      - mail callback plugin - not specifying ``sender`` is deprecated and will be
+        disallowed in community.general 6.0.0 (https://github.com/ansible-collections/community.general/pull/4140).
+      minor_changes:
+      - cobbler inventory plugin - add ``include_profiles`` option (https://github.com/ansible-collections/community.general/pull/4068).
+      - gitlab_project_variable - new ``variables`` parameter (https://github.com/ansible-collections/community.general/issues/4038).
+      - icinga2 inventory plugin - implemented constructed interface (https://github.com/ansible-collections/community.general/pull/4088).
+      - linode inventory plugin - allow templating of ``access_token`` variable in
+        Linode inventory plugin (https://github.com/ansible-collections/community.general/pull/4040).
+      - lists_mergeby filter plugin - add parameters ``list_merge`` and ``recursive``.
+        These are only supported when used with ansible-base 2.10 or ansible-core,
+        but not with Ansible 2.9 (https://github.com/ansible-collections/community.general/pull/4058).
+      - lxc_container - added ``wait_for_container`` parameter. If ``true`` the module
+        will wait until the running task reports success as the status (https://github.com/ansible-collections/community.general/pull/4039).
+      - mail callback plugin - add ``Message-ID`` and ``Date`` headers (https://github.com/ansible-collections/community.general/issues/4055,
+        https://github.com/ansible-collections/community.general/pull/4056).
+      - mail callback plugin - properly use Ansible's option handling to split lists
+        (https://github.com/ansible-collections/community.general/pull/4140).
+      - nmcli - adds ``routes6`` and ``route_metric6`` parameters for supporting IPv6
+        routes (https://github.com/ansible-collections/community.general/issues/4059).
+      - opennebula - add the release action for VMs in the ``HOLD`` state (https://github.com/ansible-collections/community.general/pull/4036).
+      - opentelemetry_plugin - enrich service when using the ``docker_login`` (https://github.com/ansible-collections/community.general/pull/4104).
+      - proxmox modules - move ``HAS_PROXMOXER`` check into ``module_utils`` (https://github.com/ansible-collections/community.general/pull/4030).
+      - scaleway inventory plugin - add profile parameter ``scw_profile`` (https://github.com/ansible-collections/community.general/pull/4049).
+      - snap - add option ``options`` permitting to set options using the ``snap set``
+        command (https://github.com/ansible-collections/community.general/pull/3943).
+      release_summary: Regular features and bugfixes release.
+    fragments:
+    - 3935-use-gitlab-instance-runner-to-create-runner.yml
+    - 3943-add-option-options-to-snap-module.yml
+    - 4.4.0.yml
+    - 4026-fix-mail-callback.yml
+    - 4030-proxmox-has-proxmoxer.yml
+    - 4036-onevm-add-release-action.yaml
+    - 4038-fix-and-rework-gitlb-project-variable.yml
+    - 4039-cluster-container-wait.yml
+    - 4040-linode-token-templating.yaml
+    - 4043-fix-no-log-opentelemetry.yml
+    - 4048-expand-tilde-in-yarn-global-install-folder.yaml
+    - 4049-profile-for-scaleway-inventory.yml
+    - 4050-properly-parse-json-lines-output-from-yarn.yaml
+    - 4052-fix-detection-of-installed-cargo-packages-with-hyphens.yaml
+    - 4056-add-missing-mail-headers.yml
+    - 4058-lists_mergeby-add-parameters.yml
+    - 4062-nmcli-ipv6-routes-support.yml
+    - 4068-add-include_file-option.yml
+    - 4078-python_requirements_info.yaml
+    - 4088-add-constructed-interface-for-icinga2-inventory.yml
+    - 4092-fix_local_ports_regex_listen_ports_facts.yaml
+    - 4104-opentelemetry_plugin-enrich_docker_login.yaml
+    - 4140-mail-callback-options.yml
+    modules:
+    - description: Manage user accounts with systemd-homed
+      name: homectl
+      namespace: system
+    release_date: '2022-02-01'

docs/docsite/helper/lists_mergeby/examples.rst.j2

@@ -0,0 +1,8 @@
+{% for i in examples %}
+{{ i.label }}
+
+.. code-block:: {{ i.lang }}
+
+  {{ lookup('file', source_path ~ i.file)|indent(2) }}
+
+{% endfor %}

docs/docsite/helper/lists_mergeby/examples.yml

@@ -0,0 +1,38 @@
+---
+examples:
+  - label: 'Example ``list_merge=replace`` (default):'
+    file: example-003.yml
+    lang: 'yaml+jinja'
+  - label: 'This produces:'
+    file: example-003.out
+    lang: 'yaml'
+  - label: 'Example ``list_merge=keep``:'
+    file: example-004.yml
+    lang: 'yaml+jinja'
+  - label: 'This produces:'
+    file: example-004.out
+    lang: 'yaml'
+  - label: 'Example ``list_merge=append``:'
+    file: example-005.yml
+    lang: 'yaml+jinja'
+  - label: 'This produces:'
+    file: example-005.out
+    lang: 'yaml'
+  - label: 'Example ``list_merge=prepend``:'
+    file: example-006.yml
+    lang: 'yaml+jinja'
+  - label: 'This produces:'
+    file: example-006.out
+    lang: 'yaml'
+  - label: 'Example ``list_merge=append_rp``:'
+    file: example-007.yml
+    lang: 'yaml+jinja'
+  - label: 'This produces:'
+    file: example-007.out
+    lang: 'yaml'
+  - label: 'Example ``list_merge=prepend_rp``:'
+    file: example-008.yml
+    lang: 'yaml+jinja'
+  - label: 'This produces:'
+    file: example-008.out
+    lang: 'yaml'

docs/docsite/helper/lists_mergeby/playbook.yml

@@ -0,0 +1,41 @@
+---
+# The following runs all examples:
+#
+#    ANSIBLE_STDOUT_CALLBACK=community.general.yaml ansible-playbook playbook.yml -e examples=true
+#
+# You need to copy the YAML output of example-XXX.yml into example-XXX.out.
+#
+# The following generates examples.rst out of the .out files:
+#
+#    ansible-playbook playbook.yml -e template=true
+- hosts: localhost
+  gather_facts: false
+  vars:
+    source_path: ../../rst/examples/lists_mergeby/
+  tasks:
+
+    - block:
+        - import_tasks: '{{ source_path }}example-001.yml'
+          tags: t001
+        - import_tasks: '{{ source_path }}example-002.yml'
+          tags: t002
+        - import_tasks: '{{ source_path }}example-003.yml'
+          tags: t003
+        - import_tasks: '{{ source_path }}example-004.yml'
+          tags: t004
+        - import_tasks: '{{ source_path }}example-005.yml'
+          tags: t005
+        - import_tasks: '{{ source_path }}example-006.yml'
+          tags: t006
+        - import_tasks: '{{ source_path }}example-007.yml'
+          tags: t007
+        - import_tasks: '{{ source_path }}example-008.yml'
+          tags: t008
+      when: examples|d(false)|bool
+
+    - block:
+        - include_vars: examples.yml
+        - template:
+            src: examples.rst.j2
+            dest: examples.rst
+      when: template|d(false)|bool

docs/docsite/rst/examples/lists_mergeby/example-001.out

@@ -0,0 +1,10 @@
+  list3:
+  - extra: false
+    name: bar
+  - name: baz
+    path: /baz
+  - extra: true
+    name: foo
+    path: /foo
+  - extra: true
+    name: meh

docs/docsite/rst/examples/lists_mergeby/example-001.yml

@@ -0,0 +1,20 @@
+---
+- name: Merge two lists by common attribute 'name'
+  set_fact:
+    list3: "{{ list1|
+               community.general.lists_mergeby(list2, 'name') }}"
+  vars:
+    list1:
+      - name: foo
+        extra: true
+      - name: bar
+        extra: false
+      - name: meh
+        extra: true
+    list2:
+      - name: foo
+        path: /foo
+      - name: baz
+        path: /baz
+- debug:
+    var: list3

docs/docsite/rst/examples/lists_mergeby/example-002.out

@@ -0,0 +1,10 @@
+  list3:
+  - extra: false
+    name: bar
+  - name: baz
+    path: /baz
+  - extra: true
+    name: foo
+    path: /foo
+  - extra: true
+    name: meh

docs/docsite/rst/examples/lists_mergeby/example-002.yml

@@ -0,0 +1,20 @@
+---
+- name: Merge two lists by common attribute 'name'
+  set_fact:
+    list3: "{{ [list1, list2]|
+               community.general.lists_mergeby('name') }}"
+  vars:
+    list1:
+      - name: foo
+        extra: true
+      - name: bar
+        extra: false
+      - name: meh
+        extra: true
+    list2:
+      - name: foo
+        path: /foo
+      - name: baz
+        path: /baz
+- debug:
+    var: list3

docs/docsite/rst/examples/lists_mergeby/example-003.out

@@ -0,0 +1,14 @@
+  list3:
+  - name: myname01
+    param01:
+      list:
+      - patch_value
+      x: default_value
+      y: patch_value
+      z: patch_value
+  - name: myname02
+    param01:
+    - 3
+    - 4
+    - 4
+    - key: value

docs/docsite/rst/examples/lists_mergeby/example-003.yml

@@ -0,0 +1,28 @@
+---
+- name: Merge recursive by 'name', replace lists (default)
+  set_fact:
+    list3: "{{ [list1, list2]|
+               community.general.lists_mergeby('name',
+                                               recursive=true) }}"
+  vars:
+    list1:
+      - name: myname01
+        param01:
+          x: default_value
+          y: default_value
+          list:
+            - default_value
+      - name: myname02
+        param01: [1, 1, 2, 3]
+
+    list2:
+      - name: myname01
+        param01:
+          y: patch_value
+          z: patch_value
+          list:
+            - patch_value
+      - name: myname02
+        param01: [3, 4, 4, {key: value}]
+- debug:
+    var: list3

docs/docsite/rst/examples/lists_mergeby/example-004.out

@@ -0,0 +1,14 @@
+  list3:
+  - name: myname01
+    param01:
+      list:
+      - default_value
+      x: default_value
+      y: patch_value
+      z: patch_value
+  - name: myname02
+    param01:
+    - 1
+    - 1
+    - 2
+    - 3

docs/docsite/rst/examples/lists_mergeby/example-004.yml

@@ -0,0 +1,29 @@
+---
+- name: Merge recursive by 'name', keep lists
+  set_fact:
+    list3: "{{ [list1, list2]|
+               community.general.lists_mergeby('name',
+                                               recursive=true,
+                                               list_merge='keep') }}"
+  vars:
+    list1:
+      - name: myname01
+        param01:
+          x: default_value
+          y: default_value
+          list:
+            - default_value
+      - name: myname02
+        param01: [1, 1, 2, 3]
+
+    list2:
+      - name: myname01
+        param01:
+          y: patch_value
+          z: patch_value
+          list:
+            - patch_value
+      - name: myname02
+        param01: [3, 4, 4, {key: value}]
+- debug:
+    var: list3

docs/docsite/rst/examples/lists_mergeby/example-005.out

@@ -0,0 +1,19 @@
+  list3:
+  - name: myname01
+    param01:
+      list:
+      - default_value
+      - patch_value
+      x: default_value
+      y: patch_value
+      z: patch_value
+  - name: myname02
+    param01:
+    - 1
+    - 1
+    - 2
+    - 3
+    - 3
+    - 4
+    - 4
+    - key: value

docs/docsite/rst/examples/lists_mergeby/example-005.yml

@@ -0,0 +1,29 @@
+---
+- name: Merge recursive by 'name', append lists
+  set_fact:
+    list3: "{{ [list1, list2]|
+               community.general.lists_mergeby('name',
+                                               recursive=true,
+                                               list_merge='append') }}"
+  vars:
+    list1:
+      - name: myname01
+        param01:
+          x: default_value
+          y: default_value
+          list:
+            - default_value
+      - name: myname02
+        param01: [1, 1, 2, 3]
+
+    list2:
+      - name: myname01
+        param01:
+          y: patch_value
+          z: patch_value
+          list:
+            - patch_value
+      - name: myname02
+        param01: [3, 4, 4, {key: value}]
+- debug:
+    var: list3

docs/docsite/rst/examples/lists_mergeby/example-006.out

@@ -0,0 +1,19 @@
+  list3:
+  - name: myname01
+    param01:
+      list:
+      - patch_value
+      - default_value
+      x: default_value
+      y: patch_value
+      z: patch_value
+  - name: myname02
+    param01:
+    - 3
+    - 4
+    - 4
+    - key: value
+    - 1
+    - 1
+    - 2
+    - 3

docs/docsite/rst/examples/lists_mergeby/example-006.yml

@@ -0,0 +1,29 @@
+---
+- name: Merge recursive by 'name', prepend lists
+  set_fact:
+    list3: "{{ [list1, list2]|
+               community.general.lists_mergeby('name',
+                                               recursive=true,
+                                               list_merge='prepend') }}"
+  vars:
+    list1:
+      - name: myname01
+        param01:
+          x: default_value
+          y: default_value
+          list:
+            - default_value
+      - name: myname02
+        param01: [1, 1, 2, 3]
+
+    list2:
+      - name: myname01
+        param01:
+          y: patch_value
+          z: patch_value
+          list:
+            - patch_value
+      - name: myname02
+        param01: [3, 4, 4, {key: value}]
+- debug:
+    var: list3

docs/docsite/rst/examples/lists_mergeby/example-007.out

@@ -0,0 +1,18 @@
+  list3:
+  - name: myname01
+    param01:
+      list:
+      - default_value
+      - patch_value
+      x: default_value
+      y: patch_value
+      z: patch_value
+  - name: myname02
+    param01:
+    - 1
+    - 1
+    - 2
+    - 3
+    - 4
+    - 4
+    - key: value

docs/docsite/rst/examples/lists_mergeby/example-007.yml

@@ -0,0 +1,29 @@
+---
+- name: Merge recursive by 'name', append lists 'remove present'
+  set_fact:
+    list3: "{{ [list1, list2]|
+               community.general.lists_mergeby('name',
+                                               recursive=true,
+                                               list_merge='append_rp') }}"
+  vars:
+    list1:
+      - name: myname01
+        param01:
+          x: default_value
+          y: default_value
+          list:
+            - default_value
+      - name: myname02
+        param01: [1, 1, 2, 3]
+
+    list2:
+      - name: myname01
+        param01:
+          y: patch_value
+          z: patch_value
+          list:
+            - patch_value
+      - name: myname02
+        param01: [3, 4, 4, {key: value}]
+- debug:
+    var: list3

docs/docsite/rst/examples/lists_mergeby/example-008.out

@@ -0,0 +1,18 @@
+  list3:
+  - name: myname01
+    param01:
+      list:
+      - patch_value
+      - default_value
+      x: default_value
+      y: patch_value
+      z: patch_value
+  - name: myname02
+    param01:
+    - 3
+    - 4
+    - 4
+    - key: value
+    - 1
+    - 1
+    - 2

docs/docsite/rst/examples/lists_mergeby/example-008.yml

@@ -0,0 +1,29 @@
+---
+- name: Merge recursive by 'name', prepend lists 'remove present'
+  set_fact:
+    list3: "{{ [list1, list2]|
+               community.general.lists_mergeby('name',
+                                               recursive=true,
+                                               list_merge='prepend_rp') }}"
+  vars:
+    list1:
+      - name: myname01
+        param01:
+          x: default_value
+          y: default_value
+          list:
+            - default_value
+      - name: myname02
+        param01: [1, 1, 2, 3]
+
+    list2:
+      - name: myname01
+        param01:
+          y: patch_value
+          z: patch_value
+          list:
+            - patch_value
+      - name: myname02
+        param01: [3, 4, 4, {key: value}]
+- debug:
+    var: list3

docs/docsite/rst/filter_guide.rst

@@ -1,3 +1,4 @@
+
 .. _ansible_collections.community.general.docsite.filter_guide:
 
 community.general Filter Guide
@@ -5,780 +6,14 @@ community.general Filter Guide
 
 The :ref:`community.general collection <plugins_in_community.general>` offers several useful filter plugins.
 
-.. contents:: Topics
-
-Paths
------
-
-The ``path_join`` filter has been added in ansible-base 2.10. If you want to use this filter, but also need to support Ansible 2.9, you can use ``community.general``'s ``path_join`` shim, ``community.general.path_join``. This filter redirects to ``path_join`` for ansible-base 2.10 and ansible-core 2.11 or newer, and re-implements the filter for Ansible 2.9.
-
-.. code-block:: yaml+jinja
-
-    # ansible-base 2.10 or newer:
-    path: {{ ('/etc', path, 'subdir', file) | path_join }}
-
-    # Also works with Ansible 2.9:
-    path: {{ ('/etc', path, 'subdir', file) | community.general.path_join }}
-
-.. versionadded:: 3.0.0
-
-Abstract transformations
-------------------------
-
-Dictionaries
-^^^^^^^^^^^^
-
-You can use the ``dict_kv`` filter to create a single-entry dictionary with ``value | community.general.dict_kv(key)``:
-
-.. code-block:: yaml+jinja
-
-    - name: Create a single-entry dictionary
-      debug:
-        msg: "{{ myvar | community.general.dict_kv('thatsmyvar') }}"
-      vars:
-        myvar: myvalue
-
-    - name: Create a list of dictionaries where the 'server' field is taken from a list
-      debug:
-        msg: >-
-          {{ myservers | map('community.general.dict_kv', 'server')
-                       | map('combine', common_config) }}
-      vars:
-        common_config:
-          type: host
-          database: all
-        myservers:
-        - server1
-        - server2
-
-This produces:
-
-.. code-block:: ansible-output
-
-    TASK [Create a single-entry dictionary]  **************************************************
-    ok: [localhost] => {
-        "msg": {
-            "thatsmyvar": "myvalue"
-        }
-    }
-
-    TASK [Create a list of dictionaries where the 'server' field is taken from a list]  *******
-    ok: [localhost] => {
-        "msg": [
-            {
-                "database": "all",
-                "server": "server1",
-                "type": "host"
-            },
-            {
-                "database": "all",
-                "server": "server2",
-                "type": "host"
-            }
-        ]
-    }
-
-.. versionadded:: 2.0.0
-
-If you need to convert a list of key-value pairs to a dictionary, you can use the ``dict`` function. Unfortunately, this function cannot be used with ``map``. For this, the ``community.general.dict`` filter can be used:
-
-.. code-block:: yaml+jinja
-
-    - name: Create a dictionary with the dict function
-      debug:
-        msg: "{{ dict([[1, 2], ['a', 'b']]) }}"
-
-    - name: Create a dictionary with the community.general.dict filter
-      debug:
-        msg: "{{ [[1, 2], ['a', 'b']] | community.general.dict }}"
-
-    - name: Create a list of dictionaries with map and the community.general.dict filter
-      debug:
-        msg: >-
-          {{ values | map('zip', ['k1', 'k2', 'k3'])
-                    | map('map', 'reverse')
-                    | map('community.general.dict') }}
-      vars:
-        values:
-          - - foo
-            - 23
-            - a
-          - - bar
-            - 42
-            - b
-
-This produces:
-
-.. code-block:: ansible-output
-
-    TASK [Create a dictionary with the dict function]  ****************************************
-    ok: [localhost] => {
-        "msg": {
-            "1": 2,
-            "a": "b"
-        }
-    }
-
-    TASK [Create a dictionary with the community.general.dict filter]  ************************
-    ok: [localhost] => {
-        "msg": {
-            "1": 2,
-            "a": "b"
-        }
-    }
-
-    TASK [Create a list of dictionaries with map and the community.general.dict filter]  ******
-    ok: [localhost] => {
-        "msg": [
-            {
-                "k1": "foo",
-                "k2": 23,
-                "k3": "a"
-            },
-            {
-                "k1": "bar",
-                "k2": 42,
-                "k3": "b"
-            }
-        ]
-    }
-
-.. versionadded:: 3.0.0
-
-Grouping
-^^^^^^^^
-
-If you have a list of dictionaries, the Jinja2 ``groupby`` filter allows to group the list by an attribute. This results in a list of ``(grouper, list)`` namedtuples, where ``list`` contains all dictionaries where the selected attribute equals ``grouper``. If you know that for every ``grouper``, there will be a most one entry in that list, you can use the ``community.general.groupby_as_dict`` filter to convert the original list into a dictionary which maps ``grouper`` to the corresponding dictionary.
-
-One example is ``ansible_facts.mounts``, which is a list of dictionaries where each has one ``device`` element to indicate the device which is mounted. Therefore, ``ansible_facts.mounts | community.general.groupby_as_dict('device')`` is a dictionary mapping a device to the mount information:
-
-.. code-block:: yaml+jinja
-
-    - name: Output mount facts grouped by device name
-      debug:
-        var: ansible_facts.mounts | community.general.groupby_as_dict('device')
-
-    - name: Output mount facts grouped by mount point
-      debug:
-        var: ansible_facts.mounts | community.general.groupby_as_dict('mount')
-
-This produces:
-
-.. code-block:: ansible-output
-
-    TASK [Output mount facts grouped by device name] ******************************************
-    ok: [localhost] => {
-        "ansible_facts.mounts | community.general.groupby_as_dict('device')": {
-            "/dev/sda1": {
-                "block_available": 2000,
-                "block_size": 4096,
-                "block_total": 2345,
-                "block_used": 345,
-                "device": "/dev/sda1",
-                "fstype": "ext4",
-                "inode_available": 500,
-                "inode_total": 512,
-                "inode_used": 12,
-                "mount": "/boot",
-                "options": "rw,relatime,data=ordered",
-                "size_available": 56821,
-                "size_total": 543210,
-                "uuid": "ab31cade-d9c1-484d-8482-8a4cbee5241a"
-            },
-            "/dev/sda2": {
-                "block_available": 1234,
-                "block_size": 4096,
-                "block_total": 12345,
-                "block_used": 11111,
-                "device": "/dev/sda2",
-                "fstype": "ext4",
-                "inode_available": 1111,
-                "inode_total": 1234,
-                "inode_used": 123,
-                "mount": "/",
-                "options": "rw,relatime",
-                "size_available": 42143,
-                "size_total": 543210,
-                "uuid": "abcdef01-2345-6789-0abc-def012345678"
-            }
-        }
-    }
-
-    TASK [Output mount facts grouped by mount point] ******************************************
-    ok: [localhost] => {
-        "ansible_facts.mounts | community.general.groupby_as_dict('mount')": {
-            "/": {
-                "block_available": 1234,
-                "block_size": 4096,
-                "block_total": 12345,
-                "block_used": 11111,
-                "device": "/dev/sda2",
-                "fstype": "ext4",
-                "inode_available": 1111,
-                "inode_total": 1234,
-                "inode_used": 123,
-                "mount": "/",
-                "options": "rw,relatime",
-                "size_available": 42143,
-                "size_total": 543210,
-                "uuid": "bdf50b7d-4859-40af-8665-c637ee7a7808"
-            },
-            "/boot": {
-                "block_available": 2000,
-                "block_size": 4096,
-                "block_total": 2345,
-                "block_used": 345,
-                "device": "/dev/sda1",
-                "fstype": "ext4",
-                "inode_available": 500,
-                "inode_total": 512,
-                "inode_used": 12,
-                "mount": "/boot",
-                "options": "rw,relatime,data=ordered",
-                "size_available": 56821,
-                "size_total": 543210,
-                "uuid": "ab31cade-d9c1-484d-8482-8a4cbee5241a"
-            }
-        }
-    }
-
-.. versionadded: 3.0.0
-
-Merging lists of dictionaries
-^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
-
-If you have two lists of dictionaries and want to combine them into a list of merged dictionaries, where two dictionaries are merged if they coincide in one attribute, you can use the ``lists_mergeby`` filter.
-
-.. code-block:: yaml+jinja
-
-    - name: Merge two lists by common attribute 'name'
-      debug:
-        var: list1 | community.general.lists_mergeby(list2, 'name')
-      vars:
-        list1:
-          - name: foo
-            extra: true
-          - name: bar
-            extra: false
-          - name: meh
-            extra: true
-        list2:
-          - name: foo
-            path: /foo
-          - name: baz
-            path: /bazzz
-
-This produces:
-
-.. code-block:: ansible-output
-
-    TASK [Merge two lists by common attribute 'name']  ****************************************
-    ok: [localhost] => {
-        "list1 | community.general.lists_mergeby(list2, 'name')": [
-            {
-                "extra": false,
-                "name": "bar"
-            },
-            {
-                "name": "baz",
-                "path": "/bazzz"
-            },
-            {
-                "extra": true,
-                "name": "foo",
-                "path": "/foo"
-            },
-            {
-                "extra": true,
-                "name": "meh"
-            }
-        ]
-    }
-
-.. versionadded: 2.0.0
-
-Working with times
-------------------
-
-The ``to_time_unit`` filter allows to convert times from a human-readable string to a unit. For example, ``'4h 30min 12second' | community.general.to_time_unit('hour')`` gives the number of hours that correspond to 4 hours, 30 minutes and 12 seconds.
-
-There are shorthands to directly convert to various units, like ``to_hours``, ``to_minutes``, ``to_seconds``, and so on. The following table lists all units that can be used:
-
-.. list-table:: Units
-   :widths: 25 25 25 25
-   :header-rows: 1
-
-   * - Unit name
-     - Unit value in seconds
-     - Unit strings for filter
-     - Shorthand filter
-   * - Millisecond
-     - 1/1000 second
-     - ``ms``, ``millisecond``, ``milliseconds``, ``msec``, ``msecs``, ``msecond``, ``mseconds``
-     - ``to_milliseconds``
-   * - Second
-     - 1 second
-     - ``s``, ``sec``, ``secs``, ``second``, ``seconds``
-     - ``to_seconds``
-   * - Minute
-     - 60 seconds
-     - ``m``, ``min``, ``mins``, ``minute``, ``minutes``
-     - ``to_minutes``
-   * - Hour
-     - 60*60 seconds
-     - ``h``, ``hour``, ``hours``
-     - ``to_hours``
-   * - Day
-     - 24*60*60 seconds
-     - ``d``, ``day``, ``days``
-     - ``to_days``
-   * - Week
-     - 7*24*60*60 seconds
-     - ``w``, ``week``, ``weeks``
-     - ``to_weeks``
-   * - Month
-     - 30*24*60*60 seconds
-     - ``mo``, ``month``, ``months``
-     - ``to_months``
-   * - Year
-     - 365*24*60*60 seconds
-     - ``y``, ``year``, ``years``
-     - ``to_years``
-
-Note that months and years are using a simplified representation: a month is 30 days, and a year is 365 days. If you need different definitions of months or years, you can pass them as keyword arguments. For example, if you want a year to be 365.25 days, and a month to be 30.5 days, you can write ``'11months 4' | community.general.to_years(year=365.25, month=30.5)``. These keyword arguments can be specified to ``to_time_unit`` and to all shorthand filters.
-
-.. code-block:: yaml+jinja
-
-    - name: Convert string to seconds
-      debug:
-        msg: "{{ '30h 20m 10s 123ms' | community.general.to_time_unit('seconds') }}"
-
-    - name: Convert string to hours
-      debug:
-        msg: "{{ '30h 20m 10s 123ms' | community.general.to_hours }}"
-
-    - name: Convert string to years (using 365.25 days == 1 year)
-      debug:
-        msg: "{{ '400d 15h' | community.general.to_years(year=365.25) }}"
-
-This produces:
-
-.. code-block:: ansible-output
-
-    TASK [Convert string to seconds] **********************************************************
-    ok: [localhost] => {
-        "msg": "109210.123"
-    }
-
-    TASK [Convert string to hours] ************************************************************
-    ok: [localhost] => {
-        "msg": "30.336145277778"
-    }
-
-    TASK [Convert string to years (using 365.25 days == 1 year)] ******************************
-    ok: [localhost] => {
-        "msg": "1.096851471595"
-    }
-
-.. versionadded: 0.2.0
-
-Working with versions
----------------------
-
-If you need to sort a list of version numbers, the Jinja ``sort`` filter is problematic. Since it sorts lexicographically, ``2.10`` will come before ``2.9``. To treat version numbers correctly, you can use the ``version_sort`` filter:
-
-.. code-block:: yaml+jinja
-
-    - name: Sort list by version number
-      debug:
-        var: ansible_versions | community.general.version_sort
-      vars:
-        ansible_versions:
-          - '2.8.0'
-          - '2.11.0'
-          - '2.7.0'
-          - '2.10.0'
-          - '2.9.0'
-
-This produces:
-
-.. code-block:: ansible-output
-
-    TASK [Sort list by version number] ********************************************************
-    ok: [localhost] => {
-        "ansible_versions | community.general.version_sort": [
-            "2.7.0",
-            "2.8.0",
-            "2.9.0",
-            "2.10.0",
-            "2.11.0"
-        ]
-    }
-
-.. versionadded: 2.2.0
-
-Creating identifiers
---------------------
-
-The following filters allow to create identifiers.
-
-Hashids
-^^^^^^^
-
-`Hashids <https://hashids.org/>`_ allow to convert sequences of integers to short unique string identifiers. This filter needs the `hashids Python library <https://pypi.org/project/hashids/>`_ installed on the controller.
-
-.. code-block:: yaml+jinja
-
-    - name: "Create hashid"
-      debug:
-        msg: "{{ [1234, 5, 6] | community.general.hashids_encode }}"
-
-    - name: "Decode hashid"
-      debug:
-        msg: "{{ 'jm2Cytn' | community.general.hashids_decode }}"
-
-This produces:
-
-.. code-block:: ansible-output
-
-    TASK [Create hashid] **********************************************************************
-    ok: [localhost] => {
-        "msg": "jm2Cytn"
-    }
-
-    TASK [Decode hashid] **********************************************************************
-    ok: [localhost] => {
-        "msg": [
-            1234,
-            5,
-            6
-        ]
-    }
-
-The hashids filters accept keyword arguments to allow fine-tuning the hashids generated:
-
-:salt: String to use as salt when hashing.
-:alphabet: String of 16 or more unique characters to produce a hash.
-:min_length: Minimum length of hash produced.
-
-.. versionadded: 3.0.0
-
-Random MACs
-^^^^^^^^^^^
-
-You can use the ``random_mac`` filter to complete a partial `MAC address <https://en.wikipedia.org/wiki/MAC_address>`_ to a random 6-byte MAC address.
-
-.. code-block:: yaml+jinja
-
-    - name: "Create a random MAC starting with ff:"
-      debug:
-        msg: "{{ 'FF' | community.general.random_mac }}"
-
-    - name: "Create a random MAC starting with 00:11:22:"
-      debug:
-        msg: "{{ '00:11:22' | community.general.random_mac }}"
-  
-This produces:
-
-.. code-block:: ansible-output
-
-    TASK [Create a random MAC starting with ff:] **********************************************
-    ok: [localhost] => {
-        "msg": "ff:69:d3:78:7f:b4"
-    }
-
-    TASK [Create a random MAC starting with 00:11:22:] ****************************************
-    ok: [localhost] => {
-        "msg": "00:11:22:71:5d:3b"
-    }
-
-You can also initialize the random number generator from a seed to create random-but-idempotent MAC addresses:
-
-.. code-block:: yaml+jinja
-
-    "{{ '52:54:00' | community.general.random_mac(seed=inventory_hostname) }}"
-
-Conversions
------------
-
-Parsing CSV files
-^^^^^^^^^^^^^^^^^
-
-Ansible offers the :ref:`community.general.read_csv module <ansible_collections.community.general.read_csv_module>` to read CSV files. Sometimes you need to convert strings to CSV files instead. For this, the ``from_csv`` filter exists.
-
-.. code-block:: yaml+jinja
-
-    - name: "Parse CSV from string"
-      debug:
-        msg: "{{ csv_string | community.general.from_csv }}"
-      vars:
-        csv_string: |
-          foo,bar,baz
-          1,2,3
-          you,this,then
-
-This produces:
-
-.. code-block:: ansible-output
-
-    TASK [Parse CSV from string] **************************************************************
-    ok: [localhost] => {
-        "msg": [
-            {
-                "bar": "2",
-                "baz": "3",
-                "foo": "1"
-            },
-            {
-                "bar": "this",
-                "baz": "then",
-                "foo": "you"
-            }
-        ]
-    }
-
-The ``from_csv`` filter has several keyword arguments to control its behavior:
-
-:dialect: Dialect of the CSV file. Default is ``excel``. Other possible choices are ``excel-tab`` and ``unix``. If one of ``delimiter``, ``skipinitialspace`` or ``strict`` is specified, ``dialect`` is ignored.
-:fieldnames: A set of column names to use. If not provided, the first line of the CSV is assumed to contain the column names.
-:delimiter: Sets the delimiter to use. Default depends on the dialect used.
-:skipinitialspace: Set to ``true`` to ignore space directly after the delimiter. Default depends on the dialect used (usually ``false``).
-:strict: Set to ``true`` to error out on invalid CSV input.
-
-.. versionadded: 3.0.0
-
-Converting to JSON
-^^^^^^^^^^^^^^^^^^
-
-`JC <https://pypi.org/project/jc/>`_ is a CLI tool and Python library which allows to interpret output of various CLI programs as JSON. It is also available as a filter in community.general. This filter needs the `jc Python library <https://pypi.org/project/jc/>`_ installed on the controller.
-
-.. code-block:: yaml+jinja
-
-    - name: Run 'ls' to list files in /
-      command: ls /
-      register: result
-
-    - name: Parse the ls output
-      debug:
-        msg: "{{ result.stdout | community.general.jc('ls') }}"
-
-This produces:
-
-.. code-block:: ansible-output
-
-    TASK [Run 'ls' to list files in /] ********************************************************
-    changed: [localhost]
-
-    TASK [Parse the ls output] ****************************************************************
-    ok: [localhost] => {
-        "msg": [
-            {
-                "filename": "bin"
-            },
-            {
-                "filename": "boot"
-            },
-            {
-                "filename": "dev"
-            },
-            {
-                "filename": "etc"
-            },
-            {
-                "filename": "home"
-            },
-            {
-                "filename": "lib"
-            },
-            {
-                "filename": "proc"
-            },
-            {
-                "filename": "root"
-            },
-            {
-                "filename": "run"
-            },
-            {
-                "filename": "tmp"
-            }
-        ]
-    }
-
-.. versionadded: 2.0.0
-
-.. _ansible_collections.community.general.docsite.json_query_filter:
-
-Selecting JSON data: JSON queries
----------------------------------
-
-To select a single element or a data subset from a complex data structure in JSON format (for example, Ansible facts), use the ``json_query`` filter.  The ``json_query`` filter lets you query a complex JSON structure and iterate over it using a loop structure.
-
-.. note:: You must manually install the **jmespath** dependency on the Ansible controller before using this filter. This filter is built upon **jmespath**, and you can use the same syntax. For examples, see `jmespath examples <http://jmespath.org/examples.html>`_.
-
-Consider this data structure:
-
-.. code-block:: yaml+jinja
-
-    {
-        "domain_definition": {
-            "domain": {
-                "cluster": [
-                    {
-                        "name": "cluster1"
-                    },
-                    {
-                        "name": "cluster2"
-                    }
-                ],
-                "server": [
-                    {
-                        "name": "server11",
-                        "cluster": "cluster1",
-                        "port": "8080"
-                    },
-                    {
-                        "name": "server12",
-                        "cluster": "cluster1",
-                        "port": "8090"
-                    },
-                    {
-                        "name": "server21",
-                        "cluster": "cluster2",
-                        "port": "9080"
-                    },
-                    {
-                        "name": "server22",
-                        "cluster": "cluster2",
-                        "port": "9090"
-                    }
-                ],
-                "library": [
-                    {
-                        "name": "lib1",
-                        "target": "cluster1"
-                    },
-                    {
-                        "name": "lib2",
-                        "target": "cluster2"
-                    }
-                ]
-            }
-        }
-    }
-
-To extract all clusters from this structure, you can use the following query:
-
-.. code-block:: yaml+jinja
-
-    - name: Display all cluster names
-      ansible.builtin.debug:
-        var: item
-      loop: "{{ domain_definition | community.general.json_query('domain.cluster[*].name') }}"
-
-To extract all server names:
-
-.. code-block:: yaml+jinja
-
-    - name: Display all server names
-      ansible.builtin.debug:
-        var: item
-      loop: "{{ domain_definition | community.general.json_query('domain.server[*].name') }}"
-
-To extract ports from cluster1:
-
-.. code-block:: yaml+jinja
-
-    - name: Display all ports from cluster1
-      ansible.builtin.debug:
-        var: item
-      loop: "{{ domain_definition | community.general.json_query(server_name_cluster1_query) }}"
-      vars:
-        server_name_cluster1_query: "domain.server[?cluster=='cluster1'].port"
-
-.. note:: You can use a variable to make the query more readable.
-
-To print out the ports from cluster1 in a comma separated string:
-
-.. code-block:: yaml+jinja
-
-    - name: Display all ports from cluster1 as a string
-      ansible.builtin.debug:
-        msg: "{{ domain_definition | community.general.json_query('domain.server[?cluster==`cluster1`].port') | join(', ') }}"
-
-.. note:: In the example above, quoting literals using backticks avoids escaping quotes and maintains readability.
-
-You can use YAML `single quote escaping <https://yaml.org/spec/current.html#id2534365>`_:
-
-.. code-block:: yaml+jinja
-
-    - name: Display all ports from cluster1
-      ansible.builtin.debug:
-        var: item
-      loop: "{{ domain_definition | community.general.json_query('domain.server[?cluster==''cluster1''].port') }}"
-
-.. note:: Escaping single quotes within single quotes in YAML is done by doubling the single quote.
-
-To get a hash map with all ports and names of a cluster:
-
-.. code-block:: yaml+jinja
-
-    - name: Display all server ports and names from cluster1
-      ansible.builtin.debug:
-        var: item
-      loop: "{{ domain_definition | community.general.json_query(server_name_cluster1_query) }}"
-      vars:
-        server_name_cluster1_query: "domain.server[?cluster=='cluster2'].{name: name, port: port}"
-
-To extract ports from all clusters with name starting with 'server1':
-
-.. code-block:: yaml+jinja
-
-    - name: Display all ports from cluster1
-      ansible.builtin.debug:
-        msg: "{{ domain_definition | to_json | from_json | community.general.json_query(server_name_query) }}"
-      vars:
-        server_name_query: "domain.server[?starts_with(name,'server1')].port"
-
-To extract ports from all clusters with name containing 'server1':
-
-.. code-block:: yaml+jinja
-
-    - name: Display all ports from cluster1
-      ansible.builtin.debug:
-        msg: "{{ domain_definition | to_json | from_json | community.general.json_query(server_name_query) }}"
-      vars:
-        server_name_query: "domain.server[?contains(name,'server1')].port"
-
-.. note:: while using ``starts_with`` and ``contains``, you have to use `` to_json | from_json `` filter for correct parsing of data structure.
-
-Working with Unicode
----------------------
-
-`Unicode <https://unicode.org/main.html>`_ makes it possible to produce two strings which may be visually equivalent, but are comprised of distinctly different characters/character sequences. To address this ``Unicode`` defines `normalization forms <https://unicode.org/reports/tr15/>`_ which avoid these distinctions by choosing a unique character sequence for a given visual representation.
-
-You can use the ``community.general.unicode_normalize`` filter to normalize ``Unicode`` strings within your playbooks.
-
-.. code-block:: yaml+jinja
-
-    - name: Compare Unicode representations
-      debug:
-        msg: "{{ with_combining_character | community.general.unicode_normalize == without_combining_character }}"
-      vars:
-        with_combining_character: "{{ 'Mayagu\u0308ez' }}"
-        without_combining_character: Mayagüez
-
-This produces:
-
-.. code-block:: ansible-output
-
-    TASK [Compare Unicode representations] ********************************************************
-    ok: [localhost] => {
-        "msg": true
-    }
-
-The ``community.general.unicode_normalize`` filter accepts a keyword argument to select the ``Unicode`` form used to normalize the input string.
-
-:form: One of ``'NFC'`` (default), ``'NFD'``, ``'NFKC'``, or ``'NFKD'``. See the `Unicode reference <https://unicode.org/reports/tr15/>`_ for more information.
-
-.. versionadded:: 3.7.0
+.. toctree::
+   :maxdepth: 2
+
+   filter_guide_paths
+   filter_guide_abstract_informations
+   filter_guide_working_with_times
+   filter_guide_working_with_versions
+   filter_guide_creating_identifiers
+   filter_guide_conversions
+   filter_guide_selecting_json_data
+   filter_guide_working_with_unicode

docs/docsite/rst/filter_guide_abstract_informations.rst

@@ -0,0 +1,10 @@
+Abstract transformations
+------------------------
+
+.. toctree::
+   :maxdepth: 1
+
+   filter_guide_abstract_informations_dictionaries
+   filter_guide_abstract_informations_grouping
+   filter_guide_abstract_informations_merging_lists_of_dictionaries
+   filter_guide_abstract_informations_counting_elements_in_sequence

docs/docsite/rst/filter_guide_abstract_informations_counting_elements_in_sequence.rst

@@ -0,0 +1,77 @@
+Counting elements in a sequence
+^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
+
+The ``community.general.counter`` filter plugin allows you to count (hashable) elements in a sequence. Elements are returned as dictionary keys and their counts are stored as dictionary values.
+
+.. code-block:: yaml+jinja
+
+    - name: Count character occurrences in a string
+      debug:
+        msg: "{{ 'abccbaabca' | community.general.counter }}"
+
+    - name: Count items in a list
+      debug:
+        msg: "{{ ['car', 'car', 'bike', 'plane', 'bike'] | community.general.counter }}"
+
+This produces:
+
+.. code-block:: ansible-output
+
+    TASK [Count character occurrences in a string] ********************************************
+    ok: [localhost] => {
+        "msg": {
+            "a": 4,
+            "b": 3,
+            "c": 3
+        }
+    }
+
+    TASK [Count items in a list] **************************************************************
+    ok: [localhost] => {
+        "msg": {
+            "bike": 2,
+            "car": 2,
+            "plane": 1
+        }
+    }
+
+This plugin is useful for selecting resources based on current allocation:
+
+.. code-block:: yaml+jinja
+
+    - name: Get ID of SCSI controller(s) with less than 4 disks attached and choose the one with the least disks
+      debug:
+        msg: >-
+          {{
+             ( disks | dict2items | map(attribute='value.adapter') | list
+               | community.general.counter | dict2items
+               | rejectattr('value', '>=', 4) | sort(attribute='value') | first
+             ).key
+          }}
+      vars:
+        disks:
+          sda:
+            adapter: scsi_1
+          sdb:
+            adapter: scsi_1
+          sdc:
+            adapter: scsi_1
+          sdd:
+            adapter: scsi_1
+          sde:
+            adapter: scsi_2
+          sdf:
+            adapter: scsi_3
+          sdg:
+            adapter: scsi_3
+
+This produces:
+
+.. code-block:: ansible-output
+
+    TASK [Get ID of SCSI controller(s) with less than 4 disks attached and choose the one with the least disks]
+    ok: [localhost] => {
+        "msg": "scsi_2"
+    }
+
+.. versionadded:: 4.3.0

docs/docsite/rst/filter_guide_abstract_informations_dictionaries.rst

@@ -0,0 +1,119 @@
+Dictionaries
+^^^^^^^^^^^^
+
+You can use the ``dict_kv`` filter to create a single-entry dictionary with ``value | community.general.dict_kv(key)``:
+
+.. code-block:: yaml+jinja
+
+    - name: Create a single-entry dictionary
+      debug:
+        msg: "{{ myvar | community.general.dict_kv('thatsmyvar') }}"
+      vars:
+        myvar: myvalue
+
+    - name: Create a list of dictionaries where the 'server' field is taken from a list
+      debug:
+        msg: >-
+          {{ myservers | map('community.general.dict_kv', 'server')
+                       | map('combine', common_config) }}
+      vars:
+        common_config:
+          type: host
+          database: all
+        myservers:
+        - server1
+        - server2
+
+This produces:
+
+.. code-block:: ansible-output
+
+    TASK [Create a single-entry dictionary]  **************************************************
+    ok: [localhost] => {
+        "msg": {
+            "thatsmyvar": "myvalue"
+        }
+    }
+
+    TASK [Create a list of dictionaries where the 'server' field is taken from a list]  *******
+    ok: [localhost] => {
+        "msg": [
+            {
+                "database": "all",
+                "server": "server1",
+                "type": "host"
+            },
+            {
+                "database": "all",
+                "server": "server2",
+                "type": "host"
+            }
+        ]
+    }
+
+.. versionadded:: 2.0.0
+
+If you need to convert a list of key-value pairs to a dictionary, you can use the ``dict`` function. Unfortunately, this function cannot be used with ``map``. For this, the ``community.general.dict`` filter can be used:
+
+.. code-block:: yaml+jinja
+
+    - name: Create a dictionary with the dict function
+      debug:
+        msg: "{{ dict([[1, 2], ['a', 'b']]) }}"
+
+    - name: Create a dictionary with the community.general.dict filter
+      debug:
+        msg: "{{ [[1, 2], ['a', 'b']] | community.general.dict }}"
+
+    - name: Create a list of dictionaries with map and the community.general.dict filter
+      debug:
+        msg: >-
+          {{ values | map('zip', ['k1', 'k2', 'k3'])
+                    | map('map', 'reverse')
+                    | map('community.general.dict') }}
+      vars:
+        values:
+          - - foo
+            - 23
+            - a
+          - - bar
+            - 42
+            - b
+
+This produces:
+
+.. code-block:: ansible-output
+
+    TASK [Create a dictionary with the dict function]  ****************************************
+    ok: [localhost] => {
+        "msg": {
+            "1": 2,
+            "a": "b"
+        }
+    }
+
+    TASK [Create a dictionary with the community.general.dict filter]  ************************
+    ok: [localhost] => {
+        "msg": {
+            "1": 2,
+            "a": "b"
+        }
+    }
+
+    TASK [Create a list of dictionaries with map and the community.general.dict filter]  ******
+    ok: [localhost] => {
+        "msg": [
+            {
+                "k1": "foo",
+                "k2": 23,
+                "k3": "a"
+            },
+            {
+                "k1": "bar",
+                "k2": 42,
+                "k3": "b"
+            }
+        ]
+    }
+
+.. versionadded:: 3.0.0

docs/docsite/rst/filter_guide_abstract_informations_grouping.rst

@@ -0,0 +1,98 @@
+Grouping
+^^^^^^^^
+
+If you have a list of dictionaries, the Jinja2 ``groupby`` filter allows to group the list by an attribute. This results in a list of ``(grouper, list)`` namedtuples, where ``list`` contains all dictionaries where the selected attribute equals ``grouper``. If you know that for every ``grouper``, there will be a most one entry in that list, you can use the ``community.general.groupby_as_dict`` filter to convert the original list into a dictionary which maps ``grouper`` to the corresponding dictionary.
+
+One example is ``ansible_facts.mounts``, which is a list of dictionaries where each has one ``device`` element to indicate the device which is mounted. Therefore, ``ansible_facts.mounts | community.general.groupby_as_dict('device')`` is a dictionary mapping a device to the mount information:
+
+.. code-block:: yaml+jinja
+
+    - name: Output mount facts grouped by device name
+      debug:
+        var: ansible_facts.mounts | community.general.groupby_as_dict('device')
+
+    - name: Output mount facts grouped by mount point
+      debug:
+        var: ansible_facts.mounts | community.general.groupby_as_dict('mount')
+
+This produces:
+
+.. code-block:: ansible-output
+
+    TASK [Output mount facts grouped by device name] ******************************************
+    ok: [localhost] => {
+        "ansible_facts.mounts | community.general.groupby_as_dict('device')": {
+            "/dev/sda1": {
+                "block_available": 2000,
+                "block_size": 4096,
+                "block_total": 2345,
+                "block_used": 345,
+                "device": "/dev/sda1",
+                "fstype": "ext4",
+                "inode_available": 500,
+                "inode_total": 512,
+                "inode_used": 12,
+                "mount": "/boot",
+                "options": "rw,relatime,data=ordered",
+                "size_available": 56821,
+                "size_total": 543210,
+                "uuid": "ab31cade-d9c1-484d-8482-8a4cbee5241a"
+            },
+            "/dev/sda2": {
+                "block_available": 1234,
+                "block_size": 4096,
+                "block_total": 12345,
+                "block_used": 11111,
+                "device": "/dev/sda2",
+                "fstype": "ext4",
+                "inode_available": 1111,
+                "inode_total": 1234,
+                "inode_used": 123,
+                "mount": "/",
+                "options": "rw,relatime",
+                "size_available": 42143,
+                "size_total": 543210,
+                "uuid": "abcdef01-2345-6789-0abc-def012345678"
+            }
+        }
+    }
+
+    TASK [Output mount facts grouped by mount point] ******************************************
+    ok: [localhost] => {
+        "ansible_facts.mounts | community.general.groupby_as_dict('mount')": {
+            "/": {
+                "block_available": 1234,
+                "block_size": 4096,
+                "block_total": 12345,
+                "block_used": 11111,
+                "device": "/dev/sda2",
+                "fstype": "ext4",
+                "inode_available": 1111,
+                "inode_total": 1234,
+                "inode_used": 123,
+                "mount": "/",
+                "options": "rw,relatime",
+                "size_available": 42143,
+                "size_total": 543210,
+                "uuid": "bdf50b7d-4859-40af-8665-c637ee7a7808"
+            },
+            "/boot": {
+                "block_available": 2000,
+                "block_size": 4096,
+                "block_total": 2345,
+                "block_used": 345,
+                "device": "/dev/sda1",
+                "fstype": "ext4",
+                "inode_available": 500,
+                "inode_total": 512,
+                "inode_used": 12,
+                "mount": "/boot",
+                "options": "rw,relatime,data=ordered",
+                "size_available": 56821,
+                "size_total": 543210,
+                "uuid": "ab31cade-d9c1-484d-8482-8a4cbee5241a"
+            }
+        }
+    }
+
+.. versionadded: 3.0.0

docs/docsite/rst/filter_guide_abstract_informations_merging_lists_of_dictionaries.rst

@@ -0,0 +1,433 @@
+Merging lists of dictionaries
+^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
+
+If you have two or more lists of dictionaries and want to combine them into a list of merged dictionaries, where the dictionaries are merged by an attribute, you can use the ``lists_mergeby`` filter.
+
+.. note:: The output of the examples in this section use the YAML callback plugin. Quoting: "Ansible output that can be quite a bit easier to read than the default JSON formatting." See :ref:`the documentation for the community.general.yaml callback plugin <ansible_collections.community.general.yaml_callback>`.
+
+In the example below the lists are merged by the attribute ``name``:
+
+.. code-block:: yaml+jinja
+
+  ---
+  - name: Merge two lists by common attribute 'name'
+    set_fact:
+      list3: "{{ list1|
+                 community.general.lists_mergeby(list2, 'name') }}"
+    vars:
+      list1:
+        - name: foo
+          extra: true
+        - name: bar
+          extra: false
+        - name: meh
+          extra: true
+      list2:
+        - name: foo
+          path: /foo
+        - name: baz
+          path: /baz
+  - debug:
+      var: list3
+
+This produces:
+
+.. code-block:: yaml
+
+  list3:
+  - extra: false
+    name: bar
+  - name: baz
+    path: /baz
+  - extra: true
+    name: foo
+    path: /foo
+  - extra: true
+    name: meh
+
+.. versionadded:: 2.0.0
+
+It is possible to use a list of lists as an input of the filter:
+
+.. code-block:: yaml+jinja
+
+  ---
+  - name: Merge two lists by common attribute 'name'
+    set_fact:
+      list3: "{{ [list1, list2]|
+                 community.general.lists_mergeby('name') }}"
+    vars:
+      list1:
+        - name: foo
+          extra: true
+        - name: bar
+          extra: false
+        - name: meh
+          extra: true
+      list2:
+        - name: foo
+          path: /foo
+        - name: baz
+          path: /baz
+  - debug:
+      var: list3
+
+This produces the same result as in the previous example:
+
+.. code-block:: yaml
+
+  list3:
+  - extra: false
+    name: bar
+  - name: baz
+    path: /baz
+  - extra: true
+    name: foo
+    path: /foo
+  - extra: true
+    name: meh
+
+The filter also accepts two optional parameters: ``recursive`` and ``list_merge``. These parameters are only supported when used with ansible-base 2.10 or ansible-core, but not with Ansible 2.9. This is available since community.general 4.4.0.
+
+**recursive**
+    Is a boolean, default to ``False``. Should the ``community.general.lists_mergeby`` recursively merge nested hashes. Note: It does not depend on the value of the ``hash_behaviour`` setting in ``ansible.cfg``.
+
+**list_merge**
+    Is a string, its possible values are ``replace`` (default), ``keep``, ``append``, ``prepend``, ``append_rp`` or ``prepend_rp``. It modifies the behaviour of ``community.general.lists_mergeby`` when the hashes to merge contain arrays/lists.
+
+The examples below set ``recursive=true`` and display the differences among all six options of ``list_merge``. Functionality of the parameters is exactly the same as in the filter ``combine``. See :ref:`Combining hashes/dictionaries <combine_filter>` to learn details about these options.
+
+Example ``list_merge=replace`` (default):
+
+.. code-block:: yaml+jinja
+
+  ---
+  - name: Merge recursive by 'name', replace lists (default)
+    set_fact:
+      list3: "{{ [list1, list2]|
+                 community.general.lists_mergeby('name',
+                                                 recursive=true) }}"
+    vars:
+      list1:
+        - name: myname01
+          param01:
+            x: default_value
+            y: default_value
+            list:
+              - default_value
+        - name: myname02
+          param01: [1, 1, 2, 3]
+
+      list2:
+        - name: myname01
+          param01:
+            y: patch_value
+            z: patch_value
+            list:
+              - patch_value
+        - name: myname02
+          param01: [3, 4, 4, {key: value}]
+  - debug:
+      var: list3
+
+This produces:
+
+.. code-block:: yaml
+
+    list3:
+    - name: myname01
+      param01:
+        list:
+        - patch_value
+        x: default_value
+        y: patch_value
+        z: patch_value
+    - name: myname02
+      param01:
+      - 3
+      - 4
+      - 4
+      - key: value
+
+Example ``list_merge=keep``:
+
+.. code-block:: yaml+jinja
+
+  ---
+  - name: Merge recursive by 'name', keep lists
+    set_fact:
+      list3: "{{ [list1, list2]|
+                 community.general.lists_mergeby('name',
+                                                 recursive=true,
+                                                 list_merge='keep') }}"
+    vars:
+      list1:
+        - name: myname01
+          param01:
+            x: default_value
+            y: default_value
+            list:
+              - default_value
+        - name: myname02
+          param01: [1, 1, 2, 3]
+
+      list2:
+        - name: myname01
+          param01:
+            y: patch_value
+            z: patch_value
+            list:
+              - patch_value
+        - name: myname02
+          param01: [3, 4, 4, {key: value}]
+  - debug:
+      var: list3
+
+This produces:
+
+.. code-block:: yaml
+
+    list3:
+    - name: myname01
+      param01:
+        list:
+        - default_value
+        x: default_value
+        y: patch_value
+        z: patch_value
+    - name: myname02
+      param01:
+      - 1
+      - 1
+      - 2
+      - 3
+
+Example ``list_merge=append``:
+
+.. code-block:: yaml+jinja
+
+  ---
+  - name: Merge recursive by 'name', append lists
+    set_fact:
+      list3: "{{ [list1, list2]|
+                 community.general.lists_mergeby('name',
+                                                 recursive=true,
+                                                 list_merge='append') }}"
+    vars:
+      list1:
+        - name: myname01
+          param01:
+            x: default_value
+            y: default_value
+            list:
+              - default_value
+        - name: myname02
+          param01: [1, 1, 2, 3]
+
+      list2:
+        - name: myname01
+          param01:
+            y: patch_value
+            z: patch_value
+            list:
+              - patch_value
+        - name: myname02
+          param01: [3, 4, 4, {key: value}]
+  - debug:
+      var: list3
+
+This produces:
+
+.. code-block:: yaml
+
+    list3:
+    - name: myname01
+      param01:
+        list:
+        - default_value
+        - patch_value
+        x: default_value
+        y: patch_value
+        z: patch_value
+    - name: myname02
+      param01:
+      - 1
+      - 1
+      - 2
+      - 3
+      - 3
+      - 4
+      - 4
+      - key: value
+
+Example ``list_merge=prepend``:
+
+.. code-block:: yaml+jinja
+
+  ---
+  - name: Merge recursive by 'name', prepend lists
+    set_fact:
+      list3: "{{ [list1, list2]|
+                 community.general.lists_mergeby('name',
+                                                 recursive=true,
+                                                 list_merge='prepend') }}"
+    vars:
+      list1:
+        - name: myname01
+          param01:
+            x: default_value
+            y: default_value
+            list:
+              - default_value
+        - name: myname02
+          param01: [1, 1, 2, 3]
+
+      list2:
+        - name: myname01
+          param01:
+            y: patch_value
+            z: patch_value
+            list:
+              - patch_value
+        - name: myname02
+          param01: [3, 4, 4, {key: value}]
+  - debug:
+      var: list3
+
+This produces:
+
+.. code-block:: yaml
+
+    list3:
+    - name: myname01
+      param01:
+        list:
+        - patch_value
+        - default_value
+        x: default_value
+        y: patch_value
+        z: patch_value
+    - name: myname02
+      param01:
+      - 3
+      - 4
+      - 4
+      - key: value
+      - 1
+      - 1
+      - 2
+      - 3
+
+Example ``list_merge=append_rp``:
+
+.. code-block:: yaml+jinja
+
+  ---
+  - name: Merge recursive by 'name', append lists 'remove present'
+    set_fact:
+      list3: "{{ [list1, list2]|
+                 community.general.lists_mergeby('name',
+                                                 recursive=true,
+                                                 list_merge='append_rp') }}"
+    vars:
+      list1:
+        - name: myname01
+          param01:
+            x: default_value
+            y: default_value
+            list:
+              - default_value
+        - name: myname02
+          param01: [1, 1, 2, 3]
+
+      list2:
+        - name: myname01
+          param01:
+            y: patch_value
+            z: patch_value
+            list:
+              - patch_value
+        - name: myname02
+          param01: [3, 4, 4, {key: value}]
+  - debug:
+      var: list3
+
+This produces:
+
+.. code-block:: yaml
+
+    list3:
+    - name: myname01
+      param01:
+        list:
+        - default_value
+        - patch_value
+        x: default_value
+        y: patch_value
+        z: patch_value
+    - name: myname02
+      param01:
+      - 1
+      - 1
+      - 2
+      - 3
+      - 4
+      - 4
+      - key: value
+
+Example ``list_merge=prepend_rp``:
+
+.. code-block:: yaml+jinja
+
+  ---
+  - name: Merge recursive by 'name', prepend lists 'remove present'
+    set_fact:
+      list3: "{{ [list1, list2]|
+                 community.general.lists_mergeby('name',
+                                                 recursive=true,
+                                                 list_merge='prepend_rp') }}"
+    vars:
+      list1:
+        - name: myname01
+          param01:
+            x: default_value
+            y: default_value
+            list:
+              - default_value
+        - name: myname02
+          param01: [1, 1, 2, 3]
+
+      list2:
+        - name: myname01
+          param01:
+            y: patch_value
+            z: patch_value
+            list:
+              - patch_value
+        - name: myname02
+          param01: [3, 4, 4, {key: value}]
+  - debug:
+      var: list3
+
+This produces:
+
+.. code-block:: yaml
+
+    list3:
+    - name: myname01
+      param01:
+        list:
+        - patch_value
+        - default_value
+        x: default_value
+        y: patch_value
+        z: patch_value
+    - name: myname02
+      param01:
+      - 3
+      - 4
+      - 4
+      - key: value
+      - 1
+      - 1
+      - 2

docs/docsite/rst/filter_guide_conversions.rst

@@ -0,0 +1,108 @@
+Conversions
+-----------
+
+Parsing CSV files
+^^^^^^^^^^^^^^^^^
+
+Ansible offers the :ref:`community.general.read_csv module <ansible_collections.community.general.read_csv_module>` to read CSV files. Sometimes you need to convert strings to CSV files instead. For this, the ``from_csv`` filter exists.
+
+.. code-block:: yaml+jinja
+
+    - name: "Parse CSV from string"
+      debug:
+        msg: "{{ csv_string | community.general.from_csv }}"
+      vars:
+        csv_string: |
+          foo,bar,baz
+          1,2,3
+          you,this,then
+
+This produces:
+
+.. code-block:: ansible-output
+
+    TASK [Parse CSV from string] **************************************************************
+    ok: [localhost] => {
+        "msg": [
+            {
+                "bar": "2",
+                "baz": "3",
+                "foo": "1"
+            },
+            {
+                "bar": "this",
+                "baz": "then",
+                "foo": "you"
+            }
+        ]
+    }
+
+The ``from_csv`` filter has several keyword arguments to control its behavior:
+
+:dialect: Dialect of the CSV file. Default is ``excel``. Other possible choices are ``excel-tab`` and ``unix``. If one of ``delimiter``, ``skipinitialspace`` or ``strict`` is specified, ``dialect`` is ignored.
+:fieldnames: A set of column names to use. If not provided, the first line of the CSV is assumed to contain the column names.
+:delimiter: Sets the delimiter to use. Default depends on the dialect used.
+:skipinitialspace: Set to ``true`` to ignore space directly after the delimiter. Default depends on the dialect used (usually ``false``).
+:strict: Set to ``true`` to error out on invalid CSV input.
+
+.. versionadded: 3.0.0
+
+Converting to JSON
+^^^^^^^^^^^^^^^^^^
+
+`JC <https://pypi.org/project/jc/>`_ is a CLI tool and Python library which allows to interpret output of various CLI programs as JSON. It is also available as a filter in community.general. This filter needs the `jc Python library <https://pypi.org/project/jc/>`_ installed on the controller.
+
+.. code-block:: yaml+jinja
+
+    - name: Run 'ls' to list files in /
+      command: ls /
+      register: result
+
+    - name: Parse the ls output
+      debug:
+        msg: "{{ result.stdout | community.general.jc('ls') }}"
+
+This produces:
+
+.. code-block:: ansible-output
+
+    TASK [Run 'ls' to list files in /] ********************************************************
+    changed: [localhost]
+
+    TASK [Parse the ls output] ****************************************************************
+    ok: [localhost] => {
+        "msg": [
+            {
+                "filename": "bin"
+            },
+            {
+                "filename": "boot"
+            },
+            {
+                "filename": "dev"
+            },
+            {
+                "filename": "etc"
+            },
+            {
+                "filename": "home"
+            },
+            {
+                "filename": "lib"
+            },
+            {
+                "filename": "proc"
+            },
+            {
+                "filename": "root"
+            },
+            {
+                "filename": "run"
+            },
+            {
+                "filename": "tmp"
+            }
+        ]
+    }
+
+.. versionadded: 2.0.0

docs/docsite/rst/filter_guide_creating_identifiers.rst

@@ -0,0 +1,80 @@
+Creating identifiers
+--------------------
+
+The following filters allow to create identifiers.
+
+Hashids
+^^^^^^^
+
+`Hashids <https://hashids.org/>`_ allow to convert sequences of integers to short unique string identifiers. This filter needs the `hashids Python library <https://pypi.org/project/hashids/>`_ installed on the controller.
+
+.. code-block:: yaml+jinja
+
+    - name: "Create hashid"
+      debug:
+        msg: "{{ [1234, 5, 6] | community.general.hashids_encode }}"
+
+    - name: "Decode hashid"
+      debug:
+        msg: "{{ 'jm2Cytn' | community.general.hashids_decode }}"
+
+This produces:
+
+.. code-block:: ansible-output
+
+    TASK [Create hashid] **********************************************************************
+    ok: [localhost] => {
+        "msg": "jm2Cytn"
+    }
+
+    TASK [Decode hashid] **********************************************************************
+    ok: [localhost] => {
+        "msg": [
+            1234,
+            5,
+            6
+        ]
+    }
+
+The hashids filters accept keyword arguments to allow fine-tuning the hashids generated:
+
+:salt: String to use as salt when hashing.
+:alphabet: String of 16 or more unique characters to produce a hash.
+:min_length: Minimum length of hash produced.
+
+.. versionadded: 3.0.0
+
+Random MACs
+^^^^^^^^^^^
+
+You can use the ``random_mac`` filter to complete a partial `MAC address <https://en.wikipedia.org/wiki/MAC_address>`_ to a random 6-byte MAC address.
+
+.. code-block:: yaml+jinja
+
+    - name: "Create a random MAC starting with ff:"
+      debug:
+        msg: "{{ 'FF' | community.general.random_mac }}"
+
+    - name: "Create a random MAC starting with 00:11:22:"
+      debug:
+        msg: "{{ '00:11:22' | community.general.random_mac }}"
+
+This produces:
+
+.. code-block:: ansible-output
+
+    TASK [Create a random MAC starting with ff:] **********************************************
+    ok: [localhost] => {
+        "msg": "ff:69:d3:78:7f:b4"
+    }
+
+    TASK [Create a random MAC starting with 00:11:22:] ****************************************
+    ok: [localhost] => {
+        "msg": "00:11:22:71:5d:3b"
+    }
+
+You can also initialize the random number generator from a seed to create random-but-idempotent MAC addresses:
+
+.. code-block:: yaml+jinja
+
+    "{{ '52:54:00' | community.general.random_mac(seed=inventory_hostname) }}"

docs/docsite/rst/filter_guide_paths.rst

@@ -0,0 +1,14 @@
+Paths
+-----
+
+The ``path_join`` filter has been added in ansible-base 2.10. If you want to use this filter, but also need to support Ansible 2.9, you can use ``community.general``'s ``path_join`` shim, ``community.general.path_join``. This filter redirects to ``path_join`` for ansible-base 2.10 and ansible-core 2.11 or newer, and re-implements the filter for Ansible 2.9.
+
+.. code-block:: yaml+jinja
+
+    # ansible-base 2.10 or newer:
+    path: {{ ('/etc', path, 'subdir', file) | path_join }}
+
+    # Also works with Ansible 2.9:
+    path: {{ ('/etc', path, 'subdir', file) | community.general.path_join }}
+
+.. versionadded:: 3.0.0

docs/docsite/rst/filter_guide_selecting_json_data.rst

@@ -0,0 +1,144 @@
+.. _ansible_collections.community.general.docsite.json_query_filter:
+
+Selecting JSON data: JSON queries
+---------------------------------
+
+To select a single element or a data subset from a complex data structure in JSON format (for example, Ansible facts), use the ``json_query`` filter.  The ``json_query`` filter lets you query a complex JSON structure and iterate over it using a loop structure.
+
+.. note:: You must manually install the **jmespath** dependency on the Ansible controller before using this filter. This filter is built upon **jmespath**, and you can use the same syntax. For examples, see `jmespath examples <http://jmespath.org/examples.html>`_.
+
+Consider this data structure:
+
+.. code-block:: yaml+jinja
+
+    {
+        "domain_definition": {
+            "domain": {
+                "cluster": [
+                    {
+                        "name": "cluster1"
+                    },
+                    {
+                        "name": "cluster2"
+                    }
+                ],
+                "server": [
+                    {
+                        "name": "server11",
+                        "cluster": "cluster1",
+                        "port": "8080"
+                    },
+                    {
+                        "name": "server12",
+                        "cluster": "cluster1",
+                        "port": "8090"
+                    },
+                    {
+                        "name": "server21",
+                        "cluster": "cluster2",
+                        "port": "9080"
+                    },
+                    {
+                        "name": "server22",
+                        "cluster": "cluster2",
+                        "port": "9090"
+                    }
+                ],
+                "library": [
+                    {
+                        "name": "lib1",
+                        "target": "cluster1"
+                    },
+                    {
+                        "name": "lib2",
+                        "target": "cluster2"
+                    }
+                ]
+            }
+        }
+    }
+
+To extract all clusters from this structure, you can use the following query:
+
+.. code-block:: yaml+jinja
+
+    - name: Display all cluster names
+      ansible.builtin.debug:
+        var: item
+      loop: "{{ domain_definition | community.general.json_query('domain.cluster[*].name') }}"
+
+To extract all server names:
+
+.. code-block:: yaml+jinja
+
+    - name: Display all server names
+      ansible.builtin.debug:
+        var: item
+      loop: "{{ domain_definition | community.general.json_query('domain.server[*].name') }}"
+
+To extract ports from cluster1:
+
+.. code-block:: yaml+jinja
+
+    - name: Display all ports from cluster1
+      ansible.builtin.debug:
+        var: item
+      loop: "{{ domain_definition | community.general.json_query(server_name_cluster1_query) }}"
+      vars:
+        server_name_cluster1_query: "domain.server[?cluster=='cluster1'].port"
+
+.. note:: You can use a variable to make the query more readable.
+
+To print out the ports from cluster1 in a comma separated string:
+
+.. code-block:: yaml+jinja
+
+    - name: Display all ports from cluster1 as a string
+      ansible.builtin.debug:
+        msg: "{{ domain_definition | community.general.json_query('domain.server[?cluster==`cluster1`].port') | join(', ') }}"
+
+.. note:: In the example above, quoting literals using backticks avoids escaping quotes and maintains readability.
+
+You can use YAML `single quote escaping <https://yaml.org/spec/current.html#id2534365>`_:
+
+.. code-block:: yaml+jinja
+
+    - name: Display all ports from cluster1
+      ansible.builtin.debug:
+        var: item
+      loop: "{{ domain_definition | community.general.json_query('domain.server[?cluster==''cluster1''].port') }}"
+
+.. note:: Escaping single quotes within single quotes in YAML is done by doubling the single quote.
+
+To get a hash map with all ports and names of a cluster:
+
+.. code-block:: yaml+jinja
+
+    - name: Display all server ports and names from cluster1
+      ansible.builtin.debug:
+        var: item
+      loop: "{{ domain_definition | community.general.json_query(server_name_cluster1_query) }}"
+      vars:
+        server_name_cluster1_query: "domain.server[?cluster=='cluster2'].{name: name, port: port}"
+
+To extract ports from all clusters with name starting with 'server1':
+
+.. code-block:: yaml+jinja
+
+    - name: Display all ports from cluster1
+      ansible.builtin.debug:
+        msg: "{{ domain_definition | to_json | from_json | community.general.json_query(server_name_query) }}"
+      vars:
+        server_name_query: "domain.server[?starts_with(name,'server1')].port"
+
+To extract ports from all clusters with name containing 'server1':
+
+.. code-block:: yaml+jinja
+
+    - name: Display all ports from cluster1
+      ansible.builtin.debug:
+        msg: "{{ domain_definition | to_json | from_json | community.general.json_query(server_name_query) }}"
+      vars:
+        server_name_query: "domain.server[?contains(name,'server1')].port"
+
+.. note:: while using ``starts_with`` and ``contains``, you have to use `` to_json | from_json `` filter for correct parsing of data structure.

docs/docsite/rst/filter_guide_working_with_times.rst

@@ -0,0 +1,84 @@
+Working with times
+------------------
+
+The ``to_time_unit`` filter allows to convert times from a human-readable string to a unit. For example, ``'4h 30min 12second' | community.general.to_time_unit('hour')`` gives the number of hours that correspond to 4 hours, 30 minutes and 12 seconds.
+
+There are shorthands to directly convert to various units, like ``to_hours``, ``to_minutes``, ``to_seconds``, and so on. The following table lists all units that can be used:
+
+.. list-table:: Units
+   :widths: 25 25 25 25
+   :header-rows: 1
+
+   * - Unit name
+     - Unit value in seconds
+     - Unit strings for filter
+     - Shorthand filter
+   * - Millisecond
+     - 1/1000 second
+     - ``ms``, ``millisecond``, ``milliseconds``, ``msec``, ``msecs``, ``msecond``, ``mseconds``
+     - ``to_milliseconds``
+   * - Second
+     - 1 second
+     - ``s``, ``sec``, ``secs``, ``second``, ``seconds``
+     - ``to_seconds``
+   * - Minute
+     - 60 seconds
+     - ``m``, ``min``, ``mins``, ``minute``, ``minutes``
+     - ``to_minutes``
+   * - Hour
+     - 60*60 seconds
+     - ``h``, ``hour``, ``hours``
+     - ``to_hours``
+   * - Day
+     - 24*60*60 seconds
+     - ``d``, ``day``, ``days``
+     - ``to_days``
+   * - Week
+     - 7*24*60*60 seconds
+     - ``w``, ``week``, ``weeks``
+     - ``to_weeks``
+   * - Month
+     - 30*24*60*60 seconds
+     - ``mo``, ``month``, ``months``
+     - ``to_months``
+   * - Year
+     - 365*24*60*60 seconds
+     - ``y``, ``year``, ``years``
+     - ``to_years``
+
+Note that months and years are using a simplified representation: a month is 30 days, and a year is 365 days. If you need different definitions of months or years, you can pass them as keyword arguments. For example, if you want a year to be 365.25 days, and a month to be 30.5 days, you can write ``'11months 4' | community.general.to_years(year=365.25, month=30.5)``. These keyword arguments can be specified to ``to_time_unit`` and to all shorthand filters.
+
+.. code-block:: yaml+jinja
+
+    - name: Convert string to seconds
+      debug:
+        msg: "{{ '30h 20m 10s 123ms' | community.general.to_time_unit('seconds') }}"
+
+    - name: Convert string to hours
+      debug:
+        msg: "{{ '30h 20m 10s 123ms' | community.general.to_hours }}"
+
+    - name: Convert string to years (using 365.25 days == 1 year)
+      debug:
+        msg: "{{ '400d 15h' | community.general.to_years(year=365.25) }}"
+
+This produces:
+
+.. code-block:: ansible-output
+
+    TASK [Convert string to seconds] **********************************************************
+    ok: [localhost] => {
+        "msg": "109210.123"
+    }
+
+    TASK [Convert string to hours] ************************************************************
+    ok: [localhost] => {
+        "msg": "30.336145277778"
+    }
+
+    TASK [Convert string to years (using 365.25 days == 1 year)] ******************************
+    ok: [localhost] => {
+        "msg": "1.096851471595"
+    }
+
+.. versionadded: 0.2.0

docs/docsite/rst/filter_guide_working_with_unicode.rst

@@ -0,0 +1,30 @@
+Working with Unicode
+---------------------
+
+`Unicode <https://unicode.org/main.html>`_ makes it possible to produce two strings which may be visually equivalent, but are comprised of distinctly different characters/character sequences. To address this ``Unicode`` defines `normalization forms <https://unicode.org/reports/tr15/>`_ which avoid these distinctions by choosing a unique character sequence for a given visual representation.
+
+You can use the ``community.general.unicode_normalize`` filter to normalize ``Unicode`` strings within your playbooks.
+
+.. code-block:: yaml+jinja
+
+    - name: Compare Unicode representations
+      debug:
+        msg: "{{ with_combining_character | community.general.unicode_normalize == without_combining_character }}"
+      vars:
+        with_combining_character: "{{ 'Mayagu\u0308ez' }}"
+        without_combining_character: Mayagüez
+
+This produces:
+
+.. code-block:: ansible-output
+
+    TASK [Compare Unicode representations] ********************************************************
+    ok: [localhost] => {
+        "msg": true
+    }
+
+The ``community.general.unicode_normalize`` filter accepts a keyword argument to select the ``Unicode`` form used to normalize the input string.
+
+:form: One of ``'NFC'`` (default), ``'NFD'``, ``'NFKC'``, or ``'NFKD'``. See the `Unicode reference <https://unicode.org/reports/tr15/>`_ for more information.
+
+.. versionadded:: 3.7.0

docs/docsite/rst/filter_guide_working_with_versions.rst

@@ -0,0 +1,34 @@
+Working with versions
+---------------------
+
+If you need to sort a list of version numbers, the Jinja ``sort`` filter is problematic. Since it sorts lexicographically, ``2.10`` will come before ``2.9``. To treat version numbers correctly, you can use the ``version_sort`` filter:
+
+.. code-block:: yaml+jinja
+
+    - name: Sort list by version number
+      debug:
+        var: ansible_versions | community.general.version_sort
+      vars:
+        ansible_versions:
+          - '2.8.0'
+          - '2.11.0'
+          - '2.7.0'
+          - '2.10.0'
+          - '2.9.0'
+
+This produces:
+
+.. code-block:: ansible-output
+
+    TASK [Sort list by version number] ********************************************************
+    ok: [localhost] => {
+        "ansible_versions | community.general.version_sort": [
+            "2.7.0",
+            "2.8.0",
+            "2.9.0",
+            "2.10.0",
+            "2.11.0"
+        ]
+    }
+
+.. versionadded: 2.2.0

galaxy.yml

@@ -1,6 +1,6 @@
 namespace: community
 name: general
-version: 4.2.0
+version: 4.4.0
 readme: README.md
 authors:
   - Ansible (https://github.com/ansible)

plugins/callback/mail.py

@@ -11,14 +11,16 @@ name: mail
 type: notification
 short_description: Sends failure events via email
 description:
-- This callback will report failures via email
+- This callback will report failures via email.
 author:
 - Dag Wieers (@dagwieers)
 requirements:
 - whitelisting in configuration
 options:
   mta:
-    description: Mail Transfer Agent, server that accepts SMTP
+    description:
+        - Mail Transfer Agent, server that accepts SMTP.
+    type: str
     env:
         - name: SMTPHOST
     ini:
@@ -26,39 +28,53 @@ options:
           key: smtphost
     default: localhost
   mtaport:
-    description: Mail Transfer Agent Port, port at which server SMTP
+    description:
+        - Mail Transfer Agent Port.
+        - Port at which server SMTP.
+    type: int
     ini:
         - section: callback_mail
           key: smtpport
     default: 25
   to:
-    description: Mail recipient
+    description:
+        - Mail recipient.
+    type: list
+    elements: str
     ini:
         - section: callback_mail
           key: to
-    default: root
+    default: [root]
   sender:
-    description: Mail sender
+    description:
+        - Mail sender.
+        - Note that this will be required from community.general 6.0.0 on.
+    type: str
     ini:
         - section: callback_mail
           key: sender
   cc:
-    description: CC'd recipient
+    description:
+        - CC'd recipients.
+    type: list
+    elements: str
     ini:
         - section: callback_mail
           key: cc
   bcc:
-    description: BCC'd recipient
+    description:
+        - BCC'd recipients.
+    type: list
+    elements: str
     ini:
         - section: callback_mail
           key: bcc
-notes:
-- "TODO: expand configuration options now that plugins can leverage Ansible's configuration"
 '''
 
 import json
 import os
 import re
+import email.utils
 import smtplib
 
 from ansible.module_utils.six import string_types
@@ -88,9 +104,13 @@ class CallbackModule(CallbackBase):
         super(CallbackModule, self).set_options(task_keys=task_keys, var_options=var_options, direct=direct)
 
         self.sender = self.get_option('sender')
+        if self.sender is None:
+            self._display.deprecated(
+                'The sender for the mail callback has not been specified. This will be an error in the future',
+                version='6.0.0', collection_name='community.general')
         self.to = self.get_option('to')
         self.smtphost = self.get_option('mta')
-        self.smtpport = int(self.get_option('mtaport'))
+        self.smtpport = self.get_option('mtaport')
         self.cc = self.get_option('cc')
         self.bcc = self.get_option('bcc')
 
@@ -100,28 +120,27 @@ class CallbackModule(CallbackBase):
 
         smtp = smtplib.SMTP(self.smtphost, port=self.smtpport)
 
-        b_sender = to_bytes(self.sender)
-        b_to = to_bytes(self.to)
-        b_cc = to_bytes(self.cc)
-        b_bcc = to_bytes(self.bcc)
-        b_subject = to_bytes(subject)
-        b_body = to_bytes(body)
-
-        b_content = b'From: %s\n' % b_sender
-        b_content += b'To: %s\n' % b_to
+        content = 'Date: %s\n' % email.utils.formatdate()
+        content += 'From: %s\n' % self.sender
+        if self.to:
+            content += 'To: %s\n' % ','.join(self.to)
         if self.cc:
-            b_content += b'Cc: %s\n' % b_cc
-        b_content += b'Subject: %s\n\n' % b_subject
-        b_content += b_body
+            content += 'Cc: %s\n' % ','.join(self.cc)
+        content += 'Message-ID: %s\n' % email.utils.make_msgid()
+        content += 'Subject: %s\n\n' % subject.strip()
+        content += body
 
-        b_addresses = b_to.split(b',')
+        addresses = self.to
         if self.cc:
-            b_addresses += b_cc.split(b',')
+            addresses += self.cc
         if self.bcc:
-            b_addresses += b_bcc.split(b',')
+            addresses += self.bcc
 
-        for b_address in b_addresses:
-            smtp.sendmail(b_sender, b_address, b_content)
+        if not addresses:
+            self._display.warning('No receiver has been specified for the mail callback plugin.')
+
+        for address in addresses:
+            smtp.sendmail(self.sender, address, to_bytes(content))
 
         smtp.quit()
 

plugins/callback/opentelemetry.py

@@ -319,9 +319,9 @@ class OpenTelemetrySource(object):
     @staticmethod
     def url_from_args(args):
         # the order matters
-        url_args = ("url", "api_url", "baseurl", "repo", "server_url", "chart_repo_url")
+        url_args = ("url", "api_url", "baseurl", "repo", "server_url", "chart_repo_url", "registry_url")
         for arg in url_args:
-            if args.get(arg):
+            if args is not None and args.get(arg):
                 return args.get(arg)
         return ""
 

plugins/callback/say.py

@@ -21,11 +21,11 @@ DOCUMENTATION = '''
       - In 2.8, this callback has been renamed from C(osx_say) into M(community.general.say).
 '''
 
-import distutils.spawn
 import platform
 import subprocess
 import os
 
+from ansible.module_utils.common.process import get_bin_path
 from ansible.plugins.callback import CallbackBase
 
 
@@ -47,21 +47,24 @@ class CallbackModule(CallbackBase):
         self.HAPPY_VOICE = None
         self.LASER_VOICE = None
 
-        self.synthesizer = distutils.spawn.find_executable('say')
-        if not self.synthesizer:
-            self.synthesizer = distutils.spawn.find_executable('espeak')
-            if self.synthesizer:
+        try:
+            self.synthesizer = get_bin_path('say')
+            if platform.system() != 'Darwin':
+                # 'say' binary available, it might be GNUstep tool which doesn't support 'voice' parameter
+                self._display.warning("'say' executable found but system is '%s': ignoring voice parameter" % platform.system())
+            else:
+                self.FAILED_VOICE = 'Zarvox'
+                self.REGULAR_VOICE = 'Trinoids'
+                self.HAPPY_VOICE = 'Cellos'
+                self.LASER_VOICE = 'Princess'
+        except ValueError:
+            try:
+                self.synthesizer = get_bin_path('espeak')
                 self.FAILED_VOICE = 'klatt'
                 self.HAPPY_VOICE = 'f5'
                 self.LASER_VOICE = 'whisper'
-        elif platform.system() != 'Darwin':
-            # 'say' binary available, it might be GNUstep tool which doesn't support 'voice' parameter
-            self._display.warning("'say' executable found but system is '%s': ignoring voice parameter" % platform.system())
-        else:
-            self.FAILED_VOICE = 'Zarvox'
-            self.REGULAR_VOICE = 'Trinoids'
-            self.HAPPY_VOICE = 'Cellos'
-            self.LASER_VOICE = 'Princess'
+            except ValueError:
+                self.synthesizer = None
 
         # plugin disable itself if say is not present
         # ansible will not call any callback if disabled is set to True

plugins/connection/jail.py

@@ -31,7 +31,6 @@ DOCUMENTATION = '''
             - name: ansible_jail_user
 '''
 
-import distutils.spawn
 import os
 import os.path
 import subprocess
@@ -39,6 +38,7 @@ import traceback
 
 from ansible.errors import AnsibleError
 from ansible.module_utils.six.moves import shlex_quote
+from ansible.module_utils.common.process import get_bin_path
 from ansible.module_utils.common.text.converters import to_bytes, to_native, to_text
 from ansible.plugins.connection import ConnectionBase, BUFSIZE
 from ansible.utils.display import Display
@@ -75,10 +75,10 @@ class Connection(ConnectionBase):
 
     @staticmethod
     def _search_executable(executable):
-        cmd = distutils.spawn.find_executable(executable)
-        if not cmd:
+        try:
+            return get_bin_path(executable)
+        except ValueError:
             raise AnsibleError("%s command not found in PATH" % executable)
-        return cmd
 
     def list_jails(self):
         p = subprocess.Popen([self.jls_cmd, '-q', 'name'],

plugins/connection/lxd.py

@@ -43,10 +43,10 @@ DOCUMENTATION = '''
 '''
 
 import os
-from distutils.spawn import find_executable
 from subprocess import Popen, PIPE
 
 from ansible.errors import AnsibleError, AnsibleConnectionFailure, AnsibleFileNotFound
+from ansible.module_utils.common.process import get_bin_path
 from ansible.module_utils.common.text.converters import to_bytes, to_text
 from ansible.plugins.connection import ConnectionBase
 
@@ -62,9 +62,9 @@ class Connection(ConnectionBase):
         super(Connection, self).__init__(play_context, new_stdin, *args, **kwargs)
 
         self._host = self._play_context.remote_addr
-        self._lxc_cmd = find_executable("lxc")
-
-        if not self._lxc_cmd:
+        try:
+            self._lxc_cmd = get_bin_path("lxc")
+        except ValueError:
             raise AnsibleError("lxc command not found in PATH")
 
         if self._play_context.remote_user is not None and self._play_context.remote_user != 'root':

plugins/connection/zone.py

@@ -26,7 +26,6 @@ DOCUMENTATION = '''
             - name: ansible_zone_host
 '''
 
-import distutils.spawn
 import os
 import os.path
 import subprocess
@@ -34,6 +33,7 @@ import traceback
 
 from ansible.errors import AnsibleError
 from ansible.module_utils.six.moves import shlex_quote
+from ansible.module_utils.common.process import get_bin_path
 from ansible.module_utils.common.text.converters import to_bytes
 from ansible.plugins.connection import ConnectionBase, BUFSIZE
 from ansible.utils.display import Display
@@ -64,10 +64,10 @@ class Connection(ConnectionBase):
 
     @staticmethod
     def _search_executable(executable):
-        cmd = distutils.spawn.find_executable(executable)
-        if not cmd:
+        try:
+            return get_bin_path(executable)
+        except ValueError:
             raise AnsibleError("%s command not found in PATH" % executable)
-        return cmd
 
     def list_zones(self):
         process = subprocess.Popen([self.zoneadm_cmd, 'list', '-ip'],

plugins/filter/counter.py

@@ -0,0 +1,36 @@
+# -*- coding: utf-8 -*-
+# Copyright (c) 2021, Remy Keil <remy.keil@gmail.com>
+# GNU General Public License v3.0+ (see COPYING or https://www.gnu.org/licenses/gpl-3.0.txt)
+
+from __future__ import (absolute_import, division, print_function)
+__metaclass__ = type
+
+from ansible.errors import AnsibleFilterError
+from ansible.module_utils.common._collections_compat import Sequence
+from collections import Counter
+
+
+def counter(sequence):
+    ''' Count elements in a sequence. Returns dict with count result. '''
+    if not isinstance(sequence, Sequence):
+        raise AnsibleFilterError('Argument for community.general.counter must be a sequence (string or list). %s is %s' %
+                                 (sequence, type(sequence)))
+
+    try:
+        result = dict(Counter(sequence))
+    except TypeError as e:
+        raise AnsibleFilterError(
+            "community.general.counter needs a sequence with hashable elements (int, float or str) - %s" % (e)
+        )
+    return result
+
+
+class FilterModule(object):
+    ''' Ansible counter jinja2 filters '''
+
+    def filters(self):
+        filters = {
+            'counter': counter,
+        }
+
+        return filters

plugins/filter/list.py

@@ -1,43 +1,113 @@
 # -*- coding: utf-8 -*-
-# Copyright (c) 2020, Vladimir Botka <vbotka@gmail.com>
+# Copyright (c) 2020-2022, Vladimir Botka <vbotka@gmail.com>
 # GNU General Public License v3.0+ (see COPYING or https://www.gnu.org/licenses/gpl-3.0.txt)
 
 from __future__ import (absolute_import, division, print_function)
 __metaclass__ = type
 
-from ansible.errors import AnsibleError, AnsibleFilterError
+from ansible.errors import AnsibleFilterError
 from ansible.module_utils.six import string_types
 from ansible.module_utils.common._collections_compat import Mapping, Sequence
+from ansible.utils.vars import merge_hash
+from ansible.release import __version__ as ansible_version
+from ansible_collections.community.general.plugins.module_utils.version import LooseVersion
+
 from collections import defaultdict
 from operator import itemgetter
 
 
-def lists_mergeby(l1, l2, index):
-    ''' merge lists by attribute index. Example:
-        - debug: msg="{{ l1|community.general.lists_mergeby(l2, 'index')|list }}" '''
+def merge_hash_wrapper(x, y, recursive=False, list_merge='replace'):
+    ''' Wrapper of the function merge_hash from ansible.utils.vars. Only 2 paramaters are allowed
+        for Ansible 2.9 and lower.'''
 
-    if not isinstance(l1, Sequence):
-        raise AnsibleFilterError('First argument for community.general.lists_mergeby must be list. %s is %s' %
-                                 (l1, type(l1)))
+    if LooseVersion(ansible_version) < LooseVersion('2.10'):
+        if list_merge != 'replace' or recursive:
+            msg = ("Non default options of list_merge(default=replace) or recursive(default=False) "
+                   "are not allowed in Ansible version 2.9 or lower. Ansible version is %s, "
+                   "recursive=%s, and list_merge=%s.")
+            raise AnsibleFilterError(msg % (ansible_version, recursive, list_merge))
+        else:
+            return merge_hash(x, y)
+    else:
+        return merge_hash(x, y, recursive, list_merge)
 
-    if not isinstance(l2, Sequence):
-        raise AnsibleFilterError('Second argument for community.general.lists_mergeby must be list. %s is %s' %
-                                 (l2, type(l2)))
 
-    if not isinstance(index, string_types):
-        raise AnsibleFilterError('Third argument for community.general.lists_mergeby must be string. %s is %s' %
-                                 (index, type(index)))
+def list_mergeby(x, y, index, recursive=False, list_merge='replace'):
+    ''' Merge 2 lists by attribute 'index'. The function merge_hash from ansible.utils.vars is used.
+        This function is used by the function lists_mergeby.
+    '''
 
     d = defaultdict(dict)
-    for l in (l1, l2):
+    for l in (x, y):
         for elem in l:
             if not isinstance(elem, Mapping):
-                raise AnsibleFilterError('Elements of list arguments for lists_mergeby must be dictionaries. Found {0!r}.'.format(elem))
+                msg = "Elements of list arguments for lists_mergeby must be dictionaries. %s is %s"
+                raise AnsibleFilterError(msg % (elem, type(elem)))
             if index in elem.keys():
-                d[elem[index]].update(elem)
+                d[elem[index]].update(merge_hash_wrapper(d[elem[index]], elem, recursive, list_merge))
     return sorted(d.values(), key=itemgetter(index))
 
 
+def lists_mergeby(*terms, **kwargs):
+    ''' Merge 2 or more lists by attribute 'index'. Optional parameters 'recursive' and 'list_merge'
+        control the merging of the lists in values. The function merge_hash from ansible.utils.vars
+        is used. To learn details on how to use the parameters 'recursive' and 'list_merge' see
+        Ansible User's Guide chapter "Using filters to manipulate data" section "Combining
+        hashes/dictionaries".
+
+        Example:
+        - debug:
+            msg: "{{ list1|
+                     community.general.lists_mergeby(list2,
+                                                     'index',
+                                                     recursive=True,
+                                                     list_merge='append')|
+                     list }}"
+    '''
+
+    recursive = kwargs.pop('recursive', False)
+    list_merge = kwargs.pop('list_merge', 'replace')
+    if kwargs:
+        raise AnsibleFilterError("'recursive' and 'list_merge' are the only valid keyword arguments.")
+    if len(terms) < 2:
+        raise AnsibleFilterError("At least one list and index are needed.")
+
+    # allow the user to do `[list1, list2, ...] | lists_mergeby('index')`
+    flat_list = []
+    for sublist in terms[:-1]:
+        if not isinstance(sublist, Sequence):
+            msg = ("All arguments before the argument index for community.general.lists_mergeby "
+                   "must be lists. %s is %s")
+            raise AnsibleFilterError(msg % (sublist, type(sublist)))
+        if len(sublist) > 0:
+            if all(isinstance(l, Sequence) for l in sublist):
+                for item in sublist:
+                    flat_list.append(item)
+            else:
+                flat_list.append(sublist)
+    lists = flat_list
+
+    if not lists:
+        return []
+
+    if len(lists) == 1:
+        return lists[0]
+
+    index = terms[-1]
+
+    if not isinstance(index, string_types):
+        msg = ("First argument after the lists for community.general.lists_mergeby must be string. "
+               "%s is %s")
+        raise AnsibleFilterError(msg % (index, type(index)))
+
+    high_to_low_prio_list_iterator = reversed(lists)
+    result = next(high_to_low_prio_list_iterator)
+    for list in high_to_low_prio_list_iterator:
+        result = list_mergeby(list, result, index, recursive, list_merge)
+
+    return result
+
+
 class FilterModule(object):
     ''' Ansible list filters '''
 

plugins/filter/version_sort.py

@@ -5,7 +5,7 @@
 from __future__ import (absolute_import, division, print_function)
 __metaclass__ = type
 
-from distutils.version import LooseVersion
+from ansible_collections.community.general.plugins.module_utils.version import LooseVersion
 
 
 def version_sort(value, reverse=False):

plugins/inventory/cobbler.py

@@ -40,10 +40,21 @@ DOCUMENTATION = '''
         type: boolean
         default: no
       exclude_profiles:
-        description: Profiles to exclude from inventory
+        description:
+          - Profiles to exclude from inventory.
+          - Ignored if I(include_profiles) is specified.
         type: list
         default: []
         elements: str
+      include_profiles:
+        description:
+          - Profiles to include from inventory.
+          - If specified, all other profiles will be excluded.
+          - I(exclude_profiles) is ignored if I(include_profiles) is specified.
+        type: list
+        default: []
+        elements: str
+        version_added: 4.4.0
       group_by:
         description: Keys to group hosts by
         type: list
@@ -68,12 +79,10 @@ user: ansible-tester
 password: secure
 '''
 
-from distutils.version import LooseVersion
 import socket
 
 from ansible.errors import AnsibleError
-from ansible.module_utils.common.text.converters import to_bytes, to_native, to_text
-from ansible.module_utils.common._collections_compat import MutableMapping
+from ansible.module_utils.common.text.converters import to_text
 from ansible.module_utils.six import iteritems
 from ansible.plugins.inventory import BaseInventoryPlugin, Cacheable, to_safe_group_name
 
@@ -95,18 +104,9 @@ class InventoryModule(BaseInventoryPlugin, Cacheable):
     NAME = 'community.general.cobbler'
 
     def __init__(self):
-
         super(InventoryModule, self).__init__()
-
-        # from config
-        self.cobbler_url = None
-        self.exclude_profiles = []  # A list of profiles to exclude
-
-        self.connection = None
-        self.token = None
-
         self.cache_key = None
-        self.use_cache = None
+        self.connection = None
 
     def verify_file(self, path):
         valid = False
@@ -178,6 +178,12 @@ class InventoryModule(BaseInventoryPlugin, Cacheable):
             self.inventory.add_child(group_name, child)
         return group_name
 
+    def _exclude_profile(self, profile):
+        if self.include_profiles:
+            return profile not in self.include_profiles
+        else:
+            return profile in self.exclude_profiles
+
     def parse(self, inventory, loader, path, cache=True):
 
         super(InventoryModule, self).parse(inventory, loader, path)
@@ -191,15 +197,16 @@ class InventoryModule(BaseInventoryPlugin, Cacheable):
         self.use_cache = cache and self.get_option('cache')
 
         self.exclude_profiles = self.get_option('exclude_profiles')
+        self.include_profiles = self.get_option('include_profiles')
         self.group_by = self.get_option('group_by')
 
         for profile in self._get_profiles():
             if profile['parent']:
                 self.display.vvvv('Processing profile %s with parent %s\n' % (profile['name'], profile['parent']))
-                if profile['parent'] not in self.exclude_profiles:
+                if not self._exclude_profile(profile['parent']):
                     parent_group_name = self._add_safe_group_name(profile['parent'])
                     self.display.vvvv('Added profile parent group %s\n' % parent_group_name)
-                    if profile['name'] not in self.exclude_profiles:
+                    if not self._exclude_profile(profile['name']):
                         group_name = self._add_safe_group_name(profile['name'])
                         self.display.vvvv('Added profile group %s\n' % group_name)
                         self.inventory.add_child(parent_group_name, group_name)
@@ -211,7 +218,7 @@ class InventoryModule(BaseInventoryPlugin, Cacheable):
                 while i < len(profile_elements) - 1:
                     profile_group = '-'.join(profile_elements[0:i + 1])
                     profile_group_child = '-'.join(profile_elements[0:i + 2])
-                    if profile_group in self.exclude_profiles:
+                    if self._exclude_profile(profile_group):
                         self.display.vvvv('Excluding profile %s\n' % profile_group)
                         break
                     group_name = self._add_safe_group_name(profile_group)
@@ -232,7 +239,7 @@ class InventoryModule(BaseInventoryPlugin, Cacheable):
             hostname = host['hostname']  # None
             interfaces = host['interfaces']
 
-            if host['profile'] in self.exclude_profiles:
+            if self._exclude_profile(host['profile']):
                 self.display.vvvv('Excluding host %s in profile %s\n' % (host['name'], host['profile']))
                 continue
 

plugins/inventory/icinga2.py

@@ -16,7 +16,17 @@ DOCUMENTATION = '''
         - Get inventory hosts from the Icinga2 API.
         - "Uses a configuration file as an inventory source, it must end in
           C(.icinga2.yml) or C(.icinga2.yaml)."
+    extends_documentation_fragment:
+        - constructed
     options:
+      strict:
+        version_added: 4.4.0
+      compose:
+        version_added: 4.4.0
+      groups:
+        version_added: 4.4.0
+      keyed_groups:
+        version_added: 4.4.0
       plugin:
         description: Name of the plugin.
         required: true
@@ -63,6 +73,20 @@ password: secure
 host_filter: \"linux-servers\" in host.groups
 validate_certs: false
 inventory_attr: name
+groups:
+  # simple name matching
+  webservers: inventory_hostname.startswith('web')
+
+  # using icinga2 template
+  databaseservers: "'db-template' in (icinga2_attributes.templates|list)"
+
+compose:
+  # set all icinga2 attributes to a host variable 'icinga2_attrs'
+  icinga2_attrs: icinga2_attributes
+
+  # set 'ansible_user' and 'ansible_port' from icinga2 host vars
+  ansible_user: icinga2_attributes.vars.ansible_user
+  ansible_port: icinga2_attributes.vars.ansible_port | default(22)
 '''
 
 import json
@@ -180,7 +204,7 @@ class InventoryModule(BaseInventoryPlugin, Constructable):
         """Query for all hosts """
         self.display.vvv("Querying Icinga2 for inventory")
         query_args = {
-            "attrs": ["address", "display_name", "state_type", "state", "groups"],
+            "attrs": ["address", "address6", "name", "display_name", "state_type", "state", "templates", "groups", "vars", "zone"],
         }
         if self.host_filter is not None:
             query_args['host_filter'] = self.host_filter
@@ -190,6 +214,12 @@ class InventoryModule(BaseInventoryPlugin, Constructable):
         ansible_inv = self._convert_inv(results_json)
         return ansible_inv
 
+    def _apply_constructable(self, name, variables):
+        strict = self.get_option('strict')
+        self._add_host_to_composed_groups(self.get_option('groups'), variables, name, strict=strict)
+        self._add_host_to_keyed_groups(self.get_option('keyed_groups'), variables, name, strict=strict)
+        self._set_composite_vars(self.get_option('compose'), variables, name, strict=strict)
+
     def _populate(self):
         groups = self._to_json(self.get_inventory_from_icinga())
         return groups
@@ -232,6 +262,10 @@ class InventoryModule(BaseInventoryPlugin, Constructable):
                                         host_attrs['state'])
             self.inventory.set_variable(host_name, 'state_type',
                                         host_attrs['state_type'])
+            # Adds all attributes to a variable 'icinga2_attributes'
+            construct_vars = dict(self.inventory.get_host(host_name).get_vars())
+            construct_vars['icinga2_attributes'] = host_attrs
+            self._apply_constructable(host_name, construct_vars)
         return groups_dict
 
     def parse(self, inventory, loader, path, cache=True):

plugins/inventory/linode.py

@@ -66,6 +66,12 @@ EXAMPLES = r'''
 # Minimal example. `LINODE_ACCESS_TOKEN` is exposed in environment.
 plugin: community.general.linode
 
+# You can use Jinja to template the access token.
+plugin: community.general.linode
+access_token: "{{ lookup('ini', 'token', section='your_username', file='~/.config/linode-cli') }}"
+# For older Ansible versions, you need to write this as:
+# access_token: "{{ lookup('ini', 'token section=your_username file=~/.config/linode-cli') }}"
+
 # Example with regions, types, groups and access token
 plugin: community.general.linode
 access_token: foobar
@@ -105,6 +111,7 @@ import os
 from ansible.errors import AnsibleError, AnsibleParserError
 from ansible.module_utils.six import string_types
 from ansible.plugins.inventory import BaseInventoryPlugin, Constructable
+from ansible.template import Templar
 
 
 try:
@@ -119,10 +126,14 @@ class InventoryModule(BaseInventoryPlugin, Constructable):
 
     NAME = 'community.general.linode'
 
-    def _build_client(self):
+    def _build_client(self, loader):
         """Build the Linode client."""
 
+        t = Templar(loader=loader)
+
         access_token = self.get_option('access_token')
+        if t.is_template(access_token):
+            access_token = t.template(variable=access_token, disable_lookups=False)
 
         if access_token is None:
             try:
@@ -287,7 +298,7 @@ class InventoryModule(BaseInventoryPlugin, Constructable):
             raise AnsibleError('the Linode dynamic inventory plugin requires linode_api4.')
 
         config_data = self._read_config_data(path)
-        self._build_client()
+        self._build_client(loader)
 
         self._get_instances_inventory()
 

plugins/inventory/proxmox.py

@@ -119,12 +119,13 @@ compose:
 import re
 
 from ansible.module_utils.common._collections_compat import MutableMapping
-from distutils.version import LooseVersion
 
 from ansible.errors import AnsibleError
 from ansible.plugins.inventory import BaseInventoryPlugin, Constructable, Cacheable
 from ansible.module_utils.six.moves.urllib.parse import urlencode
 
+from ansible_collections.community.general.plugins.module_utils.version import LooseVersion
+
 # 3rd party imports
 try:
     import requests

plugins/inventory/scaleway.py

@@ -31,6 +31,12 @@ DOCUMENTATION = r'''
         tags:
             description: Filter results on a specific tag.
             type: list
+        scw_profile:
+            description:
+            - The config profile to use in config file.
+            - By default uses the one specified as C(active_profile) in the config file, or falls back to C(default) if that is not defined.
+            type: string
+            version_added: 4.4.0
         oauth_token:
             description:
             - Scaleway OAuth token.
@@ -303,7 +309,13 @@ class InventoryModule(BaseInventoryPlugin, Constructable):
         if not oauth_token and os.path.exists(scw_config_path):
             with open(scw_config_path) as fh:
                 scw_config = yaml.safe_load(fh)
-                active_profile = scw_config.get('active_profile', 'default')
+                ansible_profile = self.get_option('scw_profile')
+
+                if ansible_profile:
+                    active_profile = ansible_profile
+                else:
+                    active_profile = scw_config.get('active_profile', 'default')
+
                 if active_profile == 'default':
                     oauth_token = scw_config.get('secret_key')
                 else:

plugins/inventory/xen_orchestra.py

@@ -62,28 +62,27 @@ DOCUMENTATION = '''
 
 EXAMPLES = '''
 # file must be named xen_orchestra.yaml or xen_orchestra.yml
-simple_config_file:
-    plugin: community.general.xen_orchestra
-    api_host: 192.168.1.255
-    user: xo
-    password: xo_pwd
-    validate_certs: true
-    use_ssl: true
-    groups:
-        kube_nodes: "'kube_node' in tags"
-    compose:
-        ansible_port: 2222
+plugin: community.general.xen_orchestra
+api_host: 192.168.1.255
+user: xo
+password: xo_pwd
+validate_certs: true
+use_ssl: true
+groups:
+    kube_nodes: "'kube_node' in tags"
+compose:
+    ansible_port: 2222
 
 '''
 
 import json
 import ssl
 
-from distutils.version import LooseVersion
-
 from ansible.errors import AnsibleError
 from ansible.plugins.inventory import BaseInventoryPlugin, Constructable, Cacheable
 
+from ansible_collections.community.general.plugins.module_utils.version import LooseVersion
+
 # 3rd party imports
 try:
     HAS_WEBSOCKET = True

plugins/lookup/flattened.py

@@ -23,7 +23,7 @@ DOCUMENTATION = '''
 EXAMPLES = """
 - name: "'unnest' all elements into single list"
   ansible.builtin.debug:
-    msg: "all in one list {{lookup('community.general.flattened', [1,2,3,[5,6]], [a,b,c], [[5,6,1,3], [34,a,b,c]])}}"
+    msg: "all in one list {{lookup('community.general.flattened', [1,2,3,[5,6]], ['a','b','c'], [[5,6,1,3], [34,'a','b','c']])}}"
 """
 
 RETURN = """

plugins/lookup/passwordstore.py

@@ -141,9 +141,9 @@ import time
 import yaml
 
 
-from distutils import util
 from ansible.errors import AnsibleError, AnsibleAssertionError
 from ansible.module_utils.common.text.converters import to_bytes, to_native, to_text
+from ansible.module_utils.parsing.convert_bool import boolean
 from ansible.utils.display import Display
 from ansible.utils.encrypt import random_password
 from ansible.plugins.lookup import LookupBase
@@ -211,7 +211,7 @@ class LookupModule(LookupBase):
             try:
                 for key in ['create', 'returnall', 'overwrite', 'backup', 'nosymbols']:
                     if not isinstance(self.paramvals[key], bool):
-                        self.paramvals[key] = util.strtobool(self.paramvals[key])
+                        self.paramvals[key] = boolean(self.paramvals[key])
             except (ValueError, AssertionError) as e:
                 raise AnsibleError(e)
             if self.paramvals['missing'] not in ['error', 'warn', 'create', 'empty']:

plugins/module_utils/_version.py

@@ -0,0 +1,343 @@
+# Vendored copy of distutils/version.py from CPython 3.9.5
+#
+# Implements multiple version numbering conventions for the
+# Python Module Distribution Utilities.
+#
+# PSF License (see licenses/PSF-license.txt or https://opensource.org/licenses/Python-2.0)
+#
+
+"""Provides classes to represent module version numbers (one class for
+each style of version numbering).  There are currently two such classes
+implemented: StrictVersion and LooseVersion.
+
+Every version number class implements the following interface:
+  * the 'parse' method takes a string and parses it to some internal
+    representation; if the string is an invalid version number,
+    'parse' raises a ValueError exception
+  * the class constructor takes an optional string argument which,
+    if supplied, is passed to 'parse'
+  * __str__ reconstructs the string that was passed to 'parse' (or
+    an equivalent string -- ie. one that will generate an equivalent
+    version number instance)
+  * __repr__ generates Python code to recreate the version number instance
+  * _cmp compares the current instance with either another instance
+    of the same class or a string (which will be parsed to an instance
+    of the same class, thus must follow the same rules)
+"""
+
+from __future__ import (absolute_import, division, print_function)
+__metaclass__ = type
+
+import re
+
+try:
+    RE_FLAGS = re.VERBOSE | re.ASCII
+except AttributeError:
+    RE_FLAGS = re.VERBOSE
+
+
+class Version:
+    """Abstract base class for version numbering classes.  Just provides
+    constructor (__init__) and reproducer (__repr__), because those
+    seem to be the same for all version numbering classes; and route
+    rich comparisons to _cmp.
+    """
+
+    def __init__(self, vstring=None):
+        if vstring:
+            self.parse(vstring)
+
+    def __repr__(self):
+        return "%s ('%s')" % (self.__class__.__name__, str(self))
+
+    def __eq__(self, other):
+        c = self._cmp(other)
+        if c is NotImplemented:
+            return c
+        return c == 0
+
+    def __lt__(self, other):
+        c = self._cmp(other)
+        if c is NotImplemented:
+            return c
+        return c < 0
+
+    def __le__(self, other):
+        c = self._cmp(other)
+        if c is NotImplemented:
+            return c
+        return c <= 0
+
+    def __gt__(self, other):
+        c = self._cmp(other)
+        if c is NotImplemented:
+            return c
+        return c > 0
+
+    def __ge__(self, other):
+        c = self._cmp(other)
+        if c is NotImplemented:
+            return c
+        return c >= 0
+
+
+# Interface for version-number classes -- must be implemented
+# by the following classes (the concrete ones -- Version should
+# be treated as an abstract class).
+#    __init__ (string) - create and take same action as 'parse'
+#                        (string parameter is optional)
+#    parse (string)    - convert a string representation to whatever
+#                        internal representation is appropriate for
+#                        this style of version numbering
+#    __str__ (self)    - convert back to a string; should be very similar
+#                        (if not identical to) the string supplied to parse
+#    __repr__ (self)   - generate Python code to recreate
+#                        the instance
+#    _cmp (self, other) - compare two version numbers ('other' may
+#                        be an unparsed version string, or another
+#                        instance of your version class)
+
+
+class StrictVersion(Version):
+    """Version numbering for anal retentives and software idealists.
+    Implements the standard interface for version number classes as
+    described above.  A version number consists of two or three
+    dot-separated numeric components, with an optional "pre-release" tag
+    on the end.  The pre-release tag consists of the letter 'a' or 'b'
+    followed by a number.  If the numeric components of two version
+    numbers are equal, then one with a pre-release tag will always
+    be deemed earlier (lesser) than one without.
+
+    The following are valid version numbers (shown in the order that
+    would be obtained by sorting according to the supplied cmp function):
+
+        0.4       0.4.0  (these two are equivalent)
+        0.4.1
+        0.5a1
+        0.5b3
+        0.5
+        0.9.6
+        1.0
+        1.0.4a3
+        1.0.4b1
+        1.0.4
+
+    The following are examples of invalid version numbers:
+
+        1
+        2.7.2.2
+        1.3.a4
+        1.3pl1
+        1.3c4
+
+    The rationale for this version numbering system will be explained
+    in the distutils documentation.
+    """
+
+    version_re = re.compile(r'^(\d+) \. (\d+) (\. (\d+))? ([ab](\d+))?$',
+                            RE_FLAGS)
+
+    def parse(self, vstring):
+        match = self.version_re.match(vstring)
+        if not match:
+            raise ValueError("invalid version number '%s'" % vstring)
+
+        (major, minor, patch, prerelease, prerelease_num) = \
+            match.group(1, 2, 4, 5, 6)
+
+        if patch:
+            self.version = tuple(map(int, [major, minor, patch]))
+        else:
+            self.version = tuple(map(int, [major, minor])) + (0,)
+
+        if prerelease:
+            self.prerelease = (prerelease[0], int(prerelease_num))
+        else:
+            self.prerelease = None
+
+    def __str__(self):
+        if self.version[2] == 0:
+            vstring = '.'.join(map(str, self.version[0:2]))
+        else:
+            vstring = '.'.join(map(str, self.version))
+
+        if self.prerelease:
+            vstring = vstring + self.prerelease[0] + str(self.prerelease[1])
+
+        return vstring
+
+    def _cmp(self, other):
+        if isinstance(other, str):
+            other = StrictVersion(other)
+        elif not isinstance(other, StrictVersion):
+            return NotImplemented
+
+        if self.version != other.version:
+            # numeric versions don't match
+            # prerelease stuff doesn't matter
+            if self.version < other.version:
+                return -1
+            else:
+                return 1
+
+        # have to compare prerelease
+        # case 1: neither has prerelease; they're equal
+        # case 2: self has prerelease, other doesn't; other is greater
+        # case 3: self doesn't have prerelease, other does: self is greater
+        # case 4: both have prerelease: must compare them!
+
+        if (not self.prerelease and not other.prerelease):
+            return 0
+        elif (self.prerelease and not other.prerelease):
+            return -1
+        elif (not self.prerelease and other.prerelease):
+            return 1
+        elif (self.prerelease and other.prerelease):
+            if self.prerelease == other.prerelease:
+                return 0
+            elif self.prerelease < other.prerelease:
+                return -1
+            else:
+                return 1
+        else:
+            raise AssertionError("never get here")
+
+# end class StrictVersion
+
+# The rules according to Greg Stein:
+# 1) a version number has 1 or more numbers separated by a period or by
+#    sequences of letters. If only periods, then these are compared
+#    left-to-right to determine an ordering.
+# 2) sequences of letters are part of the tuple for comparison and are
+#    compared lexicographically
+# 3) recognize the numeric components may have leading zeroes
+#
+# The LooseVersion class below implements these rules: a version number
+# string is split up into a tuple of integer and string components, and
+# comparison is a simple tuple comparison.  This means that version
+# numbers behave in a predictable and obvious way, but a way that might
+# not necessarily be how people *want* version numbers to behave.  There
+# wouldn't be a problem if people could stick to purely numeric version
+# numbers: just split on period and compare the numbers as tuples.
+# However, people insist on putting letters into their version numbers;
+# the most common purpose seems to be:
+#   - indicating a "pre-release" version
+#     ('alpha', 'beta', 'a', 'b', 'pre', 'p')
+#   - indicating a post-release patch ('p', 'pl', 'patch')
+# but of course this can't cover all version number schemes, and there's
+# no way to know what a programmer means without asking him.
+#
+# The problem is what to do with letters (and other non-numeric
+# characters) in a version number.  The current implementation does the
+# obvious and predictable thing: keep them as strings and compare
+# lexically within a tuple comparison.  This has the desired effect if
+# an appended letter sequence implies something "post-release":
+# eg. "0.99" < "0.99pl14" < "1.0", and "5.001" < "5.001m" < "5.002".
+#
+# However, if letters in a version number imply a pre-release version,
+# the "obvious" thing isn't correct.  Eg. you would expect that
+# "1.5.1" < "1.5.2a2" < "1.5.2", but under the tuple/lexical comparison
+# implemented here, this just isn't so.
+#
+# Two possible solutions come to mind.  The first is to tie the
+# comparison algorithm to a particular set of semantic rules, as has
+# been done in the StrictVersion class above.  This works great as long
+# as everyone can go along with bondage and discipline.  Hopefully a
+# (large) subset of Python module programmers will agree that the
+# particular flavour of bondage and discipline provided by StrictVersion
+# provides enough benefit to be worth using, and will submit their
+# version numbering scheme to its domination.  The free-thinking
+# anarchists in the lot will never give in, though, and something needs
+# to be done to accommodate them.
+#
+# Perhaps a "moderately strict" version class could be implemented that
+# lets almost anything slide (syntactically), and makes some heuristic
+# assumptions about non-digits in version number strings.  This could
+# sink into special-case-hell, though; if I was as talented and
+# idiosyncratic as Larry Wall, I'd go ahead and implement a class that
+# somehow knows that "1.2.1" < "1.2.2a2" < "1.2.2" < "1.2.2pl3", and is
+# just as happy dealing with things like "2g6" and "1.13++".  I don't
+# think I'm smart enough to do it right though.
+#
+# In any case, I've coded the test suite for this module (see
+# ../test/test_version.py) specifically to fail on things like comparing
+# "1.2a2" and "1.2".  That's not because the *code* is doing anything
+# wrong, it's because the simple, obvious design doesn't match my
+# complicated, hairy expectations for real-world version numbers.  It
+# would be a snap to fix the test suite to say, "Yep, LooseVersion does
+# the Right Thing" (ie. the code matches the conception).  But I'd rather
+# have a conception that matches common notions about version numbers.
+
+
+class LooseVersion(Version):
+    """Version numbering for anarchists and software realists.
+    Implements the standard interface for version number classes as
+    described above.  A version number consists of a series of numbers,
+    separated by either periods or strings of letters.  When comparing
+    version numbers, the numeric components will be compared
+    numerically, and the alphabetic components lexically.  The following
+    are all valid version numbers, in no particular order:
+
+        1.5.1
+        1.5.2b2
+        161
+        3.10a
+        8.02
+        3.4j
+        1996.07.12
+        3.2.pl0
+        3.1.1.6
+        2g6
+        11g
+        0.960923
+        2.2beta29
+        1.13++
+        5.5.kw
+        2.0b1pl0
+
+    In fact, there is no such thing as an invalid version number under
+    this scheme; the rules for comparison are simple and predictable,
+    but may not always give the results you want (for some definition
+    of "want").
+    """
+
+    component_re = re.compile(r'(\d+ | [a-z]+ | \.)', re.VERBOSE)
+
+    def __init__(self, vstring=None):
+        if vstring:
+            self.parse(vstring)
+
+    def parse(self, vstring):
+        # I've given up on thinking I can reconstruct the version string
+        # from the parsed tuple -- so I just store the string here for
+        # use by __str__
+        self.vstring = vstring
+        components = [x for x in self.component_re.split(vstring) if x and x != '.']
+        for i, obj in enumerate(components):
+            try:
+                components[i] = int(obj)
+            except ValueError:
+                pass
+
+        self.version = components
+
+    def __str__(self):
+        return self.vstring
+
+    def __repr__(self):
+        return "LooseVersion ('%s')" % str(self)
+
+    def _cmp(self, other):
+        if isinstance(other, str):
+            other = LooseVersion(other)
+        elif not isinstance(other, LooseVersion):
+            return NotImplemented
+
+        if self.version == other.version:
+            return 0
+        if self.version < other.version:
+            return -1
+        if self.version > other.version:
+            return 1
+
+# end class LooseVersion

plugins/module_utils/gitlab.py

@@ -7,11 +7,11 @@
 from __future__ import (absolute_import, division, print_function)
 __metaclass__ = type
 
-from distutils.version import StrictVersion
-
 from ansible.module_utils.basic import missing_required_lib
 from ansible.module_utils.common.text.converters import to_native
 
+from ansible_collections.community.general.plugins.module_utils.version import LooseVersion
+
 try:
     from urllib import quote_plus  # Python 2.X
     from urlparse import urljoin
@@ -79,7 +79,7 @@ def gitlab_authentication(module):
         # python-gitlab library remove support for username/password authentication since 1.13.0
         # Changelog : https://github.com/python-gitlab/python-gitlab/releases/tag/v1.13.0
         # This condition allow to still support older version of the python-gitlab library
-        if StrictVersion(gitlab.__version__) < StrictVersion("1.13.0"):
+        if LooseVersion(gitlab.__version__) < LooseVersion("1.13.0"):
             gitlab_instance = gitlab.Gitlab(url=gitlab_url, ssl_verify=validate_certs, email=gitlab_user, password=gitlab_password,
                                             private_token=gitlab_token, api_version=4)
         else:

plugins/module_utils/identity/keycloak/keycloak.py

@@ -38,6 +38,7 @@ from ansible.module_utils.six.moves.urllib.parse import urlencode, quote
 from ansible.module_utils.six.moves.urllib.error import HTTPError
 from ansible.module_utils.common.text.converters import to_native, to_text
 
+URL_REALM_INFO = "{url}/realms/{realm}"
 URL_REALMS = "{url}/admin/realms"
 URL_REALM = "{url}/admin/realms/{realm}"
 
@@ -230,6 +231,31 @@ class KeycloakAPI(object):
         self.validate_certs = self.module.params.get('validate_certs')
         self.restheaders = connection_header
 
+    def get_realm_info_by_id(self, realm='master'):
+        """ Obtain realm public info by id
+
+        :param realm: realm id
+        :return: dict of real, representation or None if none matching exist
+        """
+        realm_info_url = URL_REALM_INFO.format(url=self.baseurl, realm=realm)
+
+        try:
+            return json.loads(to_native(open_url(realm_info_url, method='GET', headers=self.restheaders,
+                                                 validate_certs=self.validate_certs).read()))
+
+        except HTTPError as e:
+            if e.code == 404:
+                return None
+            else:
+                self.module.fail_json(msg='Could not obtain realm %s: %s' % (realm, str(e)),
+                                      exception=traceback.format_exc())
+        except ValueError as e:
+            self.module.fail_json(msg='API returned incorrect JSON when trying to obtain realm %s: %s' % (realm, str(e)),
+                                  exception=traceback.format_exc())
+        except Exception as e:
+            self.module.fail_json(msg='Could not obtain realm %s: %s' % (realm, str(e)),
+                                  exception=traceback.format_exc())
+
     def get_realm_by_id(self, realm='master'):
         """ Obtain realm representation by id
 

plugins/module_utils/influxdb.py

@@ -9,7 +9,8 @@ __metaclass__ = type
 import traceback
 
 from ansible.module_utils.basic import missing_required_lib
-from distutils.version import LooseVersion
+
+from ansible_collections.community.general.plugins.module_utils.version import LooseVersion
 
 REQUESTS_IMP_ERR = None
 try:

plugins/module_utils/lxd.py

@@ -75,11 +75,14 @@ class LXDClient(object):
         else:
             raise LXDClientException('URL scheme must be unix: or https:')
 
-    def do(self, method, url, body_json=None, ok_error_codes=None, timeout=None):
+    def do(self, method, url, body_json=None, ok_error_codes=None, timeout=None, wait_for_container=None):
         resp_json = self._send_request(method, url, body_json=body_json, ok_error_codes=ok_error_codes, timeout=timeout)
         if resp_json['type'] == 'async':
             url = '{0}/wait'.format(resp_json['operation'])
             resp_json = self._send_request('GET', url)
+            if wait_for_container:
+                while resp_json['metadata']['status'] == 'Running':
+                    resp_json = self._send_request('GET', url)
             if resp_json['metadata']['status'] != 'Success':
                 self._raise_err_from_json(resp_json)
         return resp_json

plugins/module_utils/proxmox.py

@@ -68,6 +68,9 @@ def ansible_to_proxmox_bool(value):
 class ProxmoxAnsible(object):
     """Base class for Proxmox modules"""
     def __init__(self, module):
+        if not HAS_PROXMOXER:
+            module.fail_json(msg=missing_required_lib('proxmoxer'), exception=PROXMOXER_IMP_ERR)
+
         self.module = module
         self.proxmox_api = self._connect()
         # Test token validity

plugins/module_utils/version.py

@@ -0,0 +1,17 @@
+# -*- coding: utf-8 -*-
+
+# Copyright: (c) 2021, Felix Fontein <felix@fontein.de>
+# GNU General Public License v3.0+ (see COPYING or https://www.gnu.org/licenses/gpl-3.0.txt)
+
+"""Provide version object to compare version numbers."""
+
+from __future__ import absolute_import, division, print_function
+__metaclass__ = type
+
+
+# Once we drop support for Ansible 2.9, ansible-base 2.10, and ansible-core 2.11, we can
+# remove the _version.py file, and replace the following import by
+#
+#     from ansible.module_utils.compat.version import LooseVersion
+
+from ._version import LooseVersion

plugins/modules/cargo.py

@@ -0,0 +1 @@
+packaging/language/cargo.py

plugins/modules/cloud/centurylink/clc_aa_policy.py

@@ -120,7 +120,7 @@ __version__ = '${version}'
 import os
 import traceback
 
-from distutils.version import LooseVersion
+from ansible_collections.community.general.plugins.module_utils.version import LooseVersion
 
 REQUESTS_IMP_ERR = None
 try:

plugins/modules/cloud/centurylink/clc_alert_policy.py

@@ -161,7 +161,8 @@ __version__ = '${version}'
 import json
 import os
 import traceback
-from distutils.version import LooseVersion
+
+from ansible_collections.community.general.plugins.module_utils.version import LooseVersion
 
 REQUESTS_IMP_ERR = None
 try:

plugins/modules/cloud/centurylink/clc_blueprint_package.py

@@ -89,7 +89,8 @@ __version__ = '${version}'
 
 import os
 import traceback
-from distutils.version import LooseVersion
+
+from ansible_collections.community.general.plugins.module_utils.version import LooseVersion
 
 REQUESTS_IMP_ERR = None
 try:
@@ -132,8 +133,7 @@ class ClcBlueprintPackage:
             self.module.fail_json(msg=missing_required_lib('clc-sdk'), exception=CLC_IMP_ERR)
         if not REQUESTS_FOUND:
             self.module.fail_json(msg=missing_required_lib('requests'), exception=REQUESTS_IMP_ERR)
-        if requests.__version__ and LooseVersion(
-                requests.__version__) < LooseVersion('2.5.0'):
+        if requests.__version__ and LooseVersion(requests.__version__) < LooseVersion('2.5.0'):
             self.module.fail_json(
                 msg='requests library  version should be >= 2.5.0')
 

plugins/modules/cloud/centurylink/clc_firewall_policy.py

@@ -162,7 +162,8 @@ import os
 import traceback
 from ansible.module_utils.six.moves.urllib.parse import urlparse
 from time import sleep
-from distutils.version import LooseVersion
+
+from ansible_collections.community.general.plugins.module_utils.version import LooseVersion
 
 REQUESTS_IMP_ERR = None
 try:
@@ -203,8 +204,7 @@ class ClcFirewallPolicy:
             self.module.fail_json(msg=missing_required_lib('clc-sdk'), exception=CLC_IMP_ERR)
         if not REQUESTS_FOUND:
             self.module.fail_json(msg=missing_required_lib('requests'), exception=REQUESTS_IMP_ERR)
-        if requests.__version__ and LooseVersion(
-                requests.__version__) < LooseVersion('2.5.0'):
+        if requests.__version__ and LooseVersion(requests.__version__) < LooseVersion('2.5.0'):
             self.module.fail_json(
                 msg='requests library  version should be >= 2.5.0')
 

plugins/modules/cloud/centurylink/clc_group.py

@@ -207,7 +207,8 @@ __version__ = '${version}'
 
 import os
 import traceback
-from distutils.version import LooseVersion
+
+from ansible_collections.community.general.plugins.module_utils.version import LooseVersion
 
 REQUESTS_IMP_ERR = None
 try:

plugins/modules/cloud/centurylink/clc_loadbalancer.py

@@ -210,7 +210,8 @@ import json
 import os
 import traceback
 from time import sleep
-from distutils.version import LooseVersion
+
+from ansible_collections.community.general.plugins.module_utils.version import LooseVersion
 
 REQUESTS_IMP_ERR = None
 try:
@@ -255,8 +256,7 @@ class ClcLoadBalancer:
             self.module.fail_json(msg=missing_required_lib('clc-sdk'), exception=CLC_IMP_ERR)
         if not REQUESTS_FOUND:
             self.module.fail_json(msg=missing_required_lib('requests'), exception=REQUESTS_IMP_ERR)
-        if requests.__version__ and LooseVersion(
-                requests.__version__) < LooseVersion('2.5.0'):
+        if requests.__version__ and LooseVersion(requests.__version__) < LooseVersion('2.5.0'):
             self.module.fail_json(
                 msg='requests library  version should be >= 2.5.0')
 

plugins/modules/cloud/centurylink/clc_modify_server.py

@@ -311,7 +311,8 @@ __version__ = '${version}'
 import json
 import os
 import traceback
-from distutils.version import LooseVersion
+
+from ansible_collections.community.general.plugins.module_utils.version import LooseVersion
 
 REQUESTS_IMP_ERR = None
 try:
@@ -355,8 +356,7 @@ class ClcModifyServer:
             self.module.fail_json(msg=missing_required_lib('clc-sdk'), exception=CLC_IMP_ERR)
         if not REQUESTS_FOUND:
             self.module.fail_json(msg=missing_required_lib('requests'), exception=REQUESTS_IMP_ERR)
-        if requests.__version__ and LooseVersion(
-                requests.__version__) < LooseVersion('2.5.0'):
+        if requests.__version__ and LooseVersion(requests.__version__) < LooseVersion('2.5.0'):
             self.module.fail_json(
                 msg='requests library  version should be >= 2.5.0')
 

plugins/modules/cloud/centurylink/clc_publicip.py

@@ -117,7 +117,8 @@ __version__ = '${version}'
 
 import os
 import traceback
-from distutils.version import LooseVersion
+
+from ansible_collections.community.general.plugins.module_utils.version import LooseVersion
 
 REQUESTS_IMP_ERR = None
 try:

plugins/modules/cloud/centurylink/clc_server.py

@@ -433,7 +433,8 @@ import json
 import os
 import time
 import traceback
-from distutils.version import LooseVersion
+
+from ansible_collections.community.general.plugins.module_utils.version import LooseVersion
 
 REQUESTS_IMP_ERR = None
 try:
@@ -478,8 +479,7 @@ class ClcServer:
             self.module.fail_json(msg=missing_required_lib('clc-sdk'), exception=CLC_IMP_ERR)
         if not REQUESTS_FOUND:
             self.module.fail_json(msg=missing_required_lib('requests'), exception=REQUESTS_IMP_ERR)
-        if requests.__version__ and LooseVersion(
-                requests.__version__) < LooseVersion('2.5.0'):
+        if requests.__version__ and LooseVersion(requests.__version__) < LooseVersion('2.5.0'):
             self.module.fail_json(
                 msg='requests library  version should be >= 2.5.0')
 

plugins/modules/cloud/centurylink/clc_server_snapshot.py

@@ -101,7 +101,8 @@ __version__ = '${version}'
 
 import os
 import traceback
-from distutils.version import LooseVersion
+
+from ansible_collections.community.general.plugins.module_utils.version import LooseVersion
 
 REQUESTS_IMP_ERR = None
 try:
@@ -145,8 +146,7 @@ class ClcSnapshot:
             self.module.fail_json(msg=missing_required_lib('clc-sdk'), exception=CLC_IMP_ERR)
         if not REQUESTS_FOUND:
             self.module.fail_json(msg=missing_required_lib('requests'), exception=REQUESTS_IMP_ERR)
-        if requests.__version__ and LooseVersion(
-                requests.__version__) < LooseVersion('2.5.0'):
+        if requests.__version__ and LooseVersion(requests.__version__) < LooseVersion('2.5.0'):
             self.module.fail_json(
                 msg='requests library  version should be >= 2.5.0')
 

plugins/modules/cloud/lxd/lxd_container.py

@@ -124,6 +124,13 @@ options:
         required: false
         default: false
         type: bool
+    wait_for_container:
+        description:
+            - If set to C(true), the tasks will wait till the task reports a
+              success status when performing container operations.
+        default: false
+        type: bool
+        version_added: 4.4.0
     force_stop:
         description:
           - If this is true, the C(lxd_container) forces to stop the instance
@@ -414,6 +421,7 @@ class LXDContainerManagement(object):
         self.force_stop = self.module.params['force_stop']
         self.addresses = None
         self.target = self.module.params['target']
+        self.wait_for_container = self.module.params['wait_for_container']
 
         self.type = self.module.params['type']
 
@@ -487,9 +495,9 @@ class LXDContainerManagement(object):
         config = self.config.copy()
         config['name'] = self.name
         if self.target:
-            self.client.do('POST', '{0}?{1}'.format(self.api_endpoint, urlencode(dict(target=self.target))), config)
+            self.client.do('POST', '{0}?{1}'.format(self.api_endpoint, urlencode(dict(target=self.target))), config, wait_for_container=self.wait_for_container)
         else:
-            self.client.do('POST', self.api_endpoint, config)
+            self.client.do('POST', self.api_endpoint, config, wait_for_container=self.wait_for_container)
         self.actions.append('create')
 
     def _start_instance(self):
@@ -745,6 +753,10 @@ def main():
                 default='container',
                 choices=['container', 'virtual-machine'],
             ),
+            wait_for_container=dict(
+                type='bool',
+                default=False
+            ),
             wait_for_ipv4_addresses=dict(
                 type='bool',
                 default=False

plugins/modules/cloud/misc/proxmox.py

@@ -167,6 +167,25 @@ options:
       - compatibility
       - no_defaults
     version_added: "1.3.0"
+  clone:
+    description:
+      - ID of the container to be cloned.
+      - I(description), I(hostname), and I(pool) will be copied from the cloned container if not specified.
+      - The type of clone created is defined by the I(clone_type) parameter.
+      - This operator is only supported for Proxmox clusters that use LXC containerization (PVE version >= 4).
+    type: int
+    version_added: 4.3.0
+  clone_type:
+    description:
+      - Type of the clone created.
+      - C(full) creates a full clone, and I(storage) must be specified.
+      - C(linked) creates a linked clone, and the cloned container must be a template container.
+      - C(opportunistic) creates a linked clone if the cloned container is a template container, and a full clone if not.
+        I(storage) may be specified, if not it will fall back to the default.
+    type: str
+    choices: ['full', 'linked', 'opportunistic']
+    default: opportunistic
+    version_added: 4.3.0
 author: Sergei Antipov (@UnderGreen)
 extends_documentation_fragment:
   - community.general.proxmox.documentation
@@ -292,6 +311,28 @@ EXAMPLES = r'''
      - nesting=1
      - mount=cifs,nfs
 
+- name: >
+    Create a linked clone of the template container with id 100. The newly created container with be a
+    linked clone, because no storage parameter is defined
+  community.general.proxmox:
+    vmid: 201
+    node: uk-mc02
+    api_user: root@pam
+    api_password: 1q2w3e
+    api_host: node1
+    clone: 100
+    hostname: clone.example.org
+
+- name: Create a full clone of the container with id 100
+  community.general.proxmox:
+    vmid: 201
+    node: uk-mc02
+    api_user: root@pam
+    api_password: 1q2w3e
+    api_host: node1
+    clone: 100
+    hostname: clone.example.org
+    storage: local
 
 - name: Start container
   community.general.proxmox:
@@ -348,7 +389,8 @@ EXAMPLES = r'''
 
 import time
 import traceback
-from distutils.version import LooseVersion
+
+from ansible_collections.community.general.plugins.module_utils.version import LooseVersion
 
 try:
     from proxmoxer import ProxmoxAPI
@@ -388,6 +430,13 @@ def content_check(proxmox, node, ostemplate, template_store):
     return [True for cnt in proxmox.nodes(node).storage(template_store).content.get() if cnt['volid'] == ostemplate]
 
 
+def is_template_container(proxmox, node, vmid):
+    """Check if the specified container is a template."""
+    proxmox_node = proxmox.nodes(node)
+    config = getattr(proxmox_node, VZ_TYPE)(vmid).config.get()
+    return config['template']
+
+
 def node_check(proxmox, node):
     return [True for nd in proxmox.nodes.get() if nd['node'] == node]
 
@@ -397,8 +446,10 @@ def proxmox_version(proxmox):
     return LooseVersion(apireturn['version'])
 
 
-def create_instance(module, proxmox, vmid, node, disk, storage, cpus, memory, swap, timeout, **kwargs):
+def create_instance(module, proxmox, vmid, node, disk, storage, cpus, memory, swap, timeout, clone, **kwargs):
     proxmox_node = proxmox.nodes(node)
+
+    # Remove all empty kwarg entries
     kwargs = dict((k, v) for k, v in kwargs.items() if v is not None)
 
     if VZ_TYPE == 'lxc':
@@ -418,7 +469,49 @@ def create_instance(module, proxmox, vmid, node, disk, storage, cpus, memory, sw
         kwargs['cpus'] = cpus
         kwargs['disk'] = disk
 
-    taskid = getattr(proxmox_node, VZ_TYPE).create(vmid=vmid, storage=storage, memory=memory, swap=swap, **kwargs)
+    if clone is not None:
+        if VZ_TYPE != 'lxc':
+            module.fail_json(changed=False, msg="Clone operator is only supported for LXC enabled proxmox clusters.")
+
+        clone_is_template = is_template_container(proxmox, node, clone)
+
+        # By default, create a full copy only when the cloned container is not a template.
+        create_full_copy = not clone_is_template
+
+        # Only accept parameters that are compatible with the clone endpoint.
+        valid_clone_parameters = ['hostname', 'pool', 'description']
+        if module.params['storage'] is not None and clone_is_template:
+            # Cloning a template, so create a full copy instead of a linked copy
+            create_full_copy = True
+        elif module.params['storage'] is None and not clone_is_template:
+            # Not cloning a template, but also no defined storage. This isn't possible.
+            module.fail_json(changed=False, msg="Cloned container is not a template, storage needs to be specified.")
+
+        if module.params['clone_type'] == 'linked':
+            if not clone_is_template:
+                module.fail_json(changed=False, msg="'linked' clone type is specified, but cloned container is not a template container.")
+            # Don't need to do more, by default create_full_copy is set to false already
+        elif module.params['clone_type'] == 'opportunistic':
+            if not clone_is_template:
+                # Cloned container is not a template, so we need our 'storage' parameter
+                valid_clone_parameters.append('storage')
+        elif module.params['clone_type'] == 'full':
+            create_full_copy = True
+            valid_clone_parameters.append('storage')
+
+        clone_parameters = {}
+
+        if create_full_copy:
+            clone_parameters['full'] = '1'
+        else:
+            clone_parameters['full'] = '0'
+        for param in valid_clone_parameters:
+            if module.params[param] is not None:
+                clone_parameters[param] = module.params[param]
+
+        taskid = getattr(proxmox_node, VZ_TYPE)(clone).clone.post(newid=vmid, **clone_parameters)
+    else:
+        taskid = getattr(proxmox_node, VZ_TYPE).create(vmid=vmid, storage=storage, memory=memory, swap=swap, **kwargs)
 
     while timeout:
         if (proxmox_node.tasks(taskid).status.get()['status'] == 'stopped' and
@@ -519,10 +612,19 @@ def main():
             description=dict(type='str'),
             hookscript=dict(type='str'),
             proxmox_default_behavior=dict(type='str', default='no_defaults', choices=['compatibility', 'no_defaults']),
+            clone=dict(type='int'),
+            clone_type=dict(default='opportunistic', choices=['full', 'linked', 'opportunistic']),
         ),
-        required_if=[('state', 'present', ['node', 'hostname', 'ostemplate'])],
-        required_together=[('api_token_id', 'api_token_secret')],
+        required_if=[
+            ('state', 'present', ['node', 'hostname']),
+            ('state', 'present', ('clone', 'ostemplate'), True),  # Require one of clone and ostemplate. Together with mutually_exclusive this ensures that we
+                                                                  # either clone a container or create a new one from a template file.
+        ],
+        required_together=[
+            ('api_token_id', 'api_token_secret')
+        ],
         required_one_of=[('api_password', 'api_token_id')],
+        mutually_exclusive=[('clone', 'ostemplate')],  # Creating a new container is done either by cloning an existing one, or based on a template.
     )
 
     if not HAS_PROXMOXER:
@@ -546,6 +648,7 @@ def main():
     if module.params['ostemplate'] is not None:
         template_store = module.params['ostemplate'].split(":")[0]
     timeout = module.params['timeout']
+    clone = module.params['clone']
 
     if module.params['proxmox_default_behavior'] == 'compatibility':
         old_default_values = dict(
@@ -587,7 +690,8 @@ def main():
     elif not vmid:
         module.exit_json(changed=False, msg="Vmid could not be fetched for the following action: %s" % state)
 
-    if state == 'present':
+    # Create a new container
+    if state == 'present' and clone is None:
         try:
             if get_instance(proxmox, vmid) and not module.params['force']:
                 module.exit_json(changed=False, msg="VM with vmid = %s is already exists" % vmid)
@@ -599,8 +703,11 @@ def main():
             elif not content_check(proxmox, node, module.params['ostemplate'], template_store):
                 module.fail_json(msg="ostemplate '%s' not exists on node %s and storage %s"
                                  % (module.params['ostemplate'], node, template_store))
+        except Exception as e:
+            module.fail_json(msg="Pre-creation checks of {VZ_TYPE} VM {vmid} failed with exception: {e}".format(VZ_TYPE=VZ_TYPE, vmid=vmid, e=e))
 
-            create_instance(module, proxmox, vmid, node, disk, storage, cpus, memory, swap, timeout,
+        try:
+            create_instance(module, proxmox, vmid, node, disk, storage, cpus, memory, swap, timeout, clone,
                             cores=module.params['cores'],
                             pool=module.params['pool'],
                             password=module.params['password'],
@@ -620,9 +727,29 @@ def main():
                             description=module.params['description'],
                             hookscript=module.params['hookscript'])
 
-            module.exit_json(changed=True, msg="deployed VM %s from template %s" % (vmid, module.params['ostemplate']))
+            module.exit_json(changed=True, msg="Deployed VM %s from template %s" % (vmid, module.params['ostemplate']))
         except Exception as e:
-            module.fail_json(msg="creation of %s VM %s failed with exception: %s" % (VZ_TYPE, vmid, e))
+            module.fail_json(msg="Creation of %s VM %s failed with exception: %s" % (VZ_TYPE, vmid, e))
+
+    # Clone a container
+    elif state == 'present' and clone is not None:
+        try:
+            if get_instance(proxmox, vmid) and not module.params['force']:
+                module.exit_json(changed=False, msg="VM with vmid = %s is already exists" % vmid)
+            # If no vmid was passed, there cannot be another VM named 'hostname'
+            if not module.params['vmid'] and get_vmid(proxmox, hostname) and not module.params['force']:
+                module.exit_json(changed=False, msg="VM with hostname %s already exists and has ID number %s" % (hostname, get_vmid(proxmox, hostname)[0]))
+            if not get_instance(proxmox, clone):
+                module.exit_json(changed=False, msg="Container to be cloned does not exist")
+        except Exception as e:
+            module.fail_json(msg="Pre-clone checks of {VZ_TYPE} VM {vmid} failed with exception: {e}".format(VZ_TYPE=VZ_TYPE, vmid=vmid, e=e))
+
+        try:
+            create_instance(module, proxmox, vmid, node, disk, storage, cpus, memory, swap, timeout, clone)
+
+            module.exit_json(changed=True, msg="Cloned VM %s from %s" % (vmid, clone))
+        except Exception as e:
+            module.fail_json(msg="Cloning %s VM %s failed with exception: %s" % (VZ_TYPE, vmid, e))
 
     elif state == 'started':
         try:

plugins/modules/cloud/misc/proxmox_domain_info.py

@@ -76,7 +76,7 @@ proxmox_domains:
 
 from ansible.module_utils.basic import AnsibleModule, missing_required_lib
 from ansible_collections.community.general.plugins.module_utils.proxmox import (
-    proxmox_auth_argument_spec, ProxmoxAnsible, HAS_PROXMOXER, PROXMOXER_IMP_ERR)
+    proxmox_auth_argument_spec, ProxmoxAnsible)
 
 
 class ProxmoxDomainInfoAnsible(ProxmoxAnsible):
@@ -114,9 +114,6 @@ def main():
         changed=False
     )
 
-    if not HAS_PROXMOXER:
-        module.fail_json(msg=missing_required_lib('proxmoxer'), exception=PROXMOXER_IMP_ERR)
-
     proxmox = ProxmoxDomainInfoAnsible(module)
     domain = module.params['domain']
 

plugins/modules/cloud/misc/proxmox_group_info.py

@@ -73,7 +73,7 @@ proxmox_groups:
 
 from ansible.module_utils.basic import AnsibleModule, missing_required_lib
 from ansible_collections.community.general.plugins.module_utils.proxmox import (
-    proxmox_auth_argument_spec, ProxmoxAnsible, HAS_PROXMOXER, PROXMOXER_IMP_ERR)
+    proxmox_auth_argument_spec, ProxmoxAnsible)
 
 
 class ProxmoxGroupInfoAnsible(ProxmoxAnsible):
@@ -124,9 +124,6 @@ def main():
         changed=False
     )
 
-    if not HAS_PROXMOXER:
-        module.fail_json(msg=missing_required_lib('proxmoxer'), exception=PROXMOXER_IMP_ERR)
-
     proxmox = ProxmoxGroupInfoAnsible(module)
     group = module.params['group']
 

plugins/modules/cloud/misc/proxmox_kvm.py

@@ -725,9 +725,10 @@ msg:
 import re
 import time
 import traceback
-from distutils.version import LooseVersion
 from ansible.module_utils.six.moves.urllib.parse import quote
 
+from ansible_collections.community.general.plugins.module_utils.version import LooseVersion
+
 try:
     from proxmoxer import ProxmoxAPI
     HAS_PROXMOXER = True

plugins/modules/cloud/misc/proxmox_snap.py

@@ -197,7 +197,7 @@ def main():
     )
 
     if not HAS_PROXMOXER:
-        module.fail_json(msg=missing_required_lib('python-proxmoxer'),
+        module.fail_json(msg=missing_required_lib('proxmoxer'),
                          exception=PROXMOXER_IMP_ERR)
 
     state = module.params['state']

plugins/modules/cloud/misc/proxmox_storage_info.py

@@ -111,7 +111,7 @@ proxmox_storages:
 
 from ansible.module_utils.basic import AnsibleModule, missing_required_lib
 from ansible_collections.community.general.plugins.module_utils.proxmox import (
-    proxmox_auth_argument_spec, ProxmoxAnsible, HAS_PROXMOXER, PROXMOXER_IMP_ERR, proxmox_to_ansible_bool)
+    proxmox_auth_argument_spec, ProxmoxAnsible, proxmox_to_ansible_bool)
 
 
 class ProxmoxStorageInfoAnsible(ProxmoxAnsible):
@@ -170,9 +170,6 @@ def main():
         changed=False
     )
 
-    if not HAS_PROXMOXER:
-        module.fail_json(msg=missing_required_lib('proxmoxer'), exception=PROXMOXER_IMP_ERR)
-
     proxmox = ProxmoxStorageInfoAnsible(module)
     storage = module.params['storage']
     storagetype = module.params['type']

plugins/modules/cloud/misc/proxmox_tasks_info.py

@@ -116,7 +116,7 @@ msg:
 
 from ansible.module_utils.basic import AnsibleModule, missing_required_lib
 from ansible_collections.community.general.plugins.module_utils.proxmox import (
-    proxmox_auth_argument_spec, ProxmoxAnsible, HAS_PROXMOXER, PROXMOXER_IMP_ERR)
+    proxmox_auth_argument_spec, ProxmoxAnsible)
 
 
 class ProxmoxTaskInfoAnsible(ProxmoxAnsible):
@@ -163,9 +163,6 @@ def main():
         supports_check_mode=True)
     result = dict(changed=False)
 
-    if not HAS_PROXMOXER:
-        module.fail_json(msg=missing_required_lib(
-            'proxmoxer'), exception=PROXMOXER_IMP_ERR)
     proxmox = ProxmoxTaskInfoAnsible(module)
     upid = module.params['task']
     node = module.params['node']

plugins/modules/cloud/misc/proxmox_user_info.py

@@ -156,7 +156,7 @@ proxmox_users:
 
 from ansible.module_utils.basic import AnsibleModule, missing_required_lib
 from ansible_collections.community.general.plugins.module_utils.proxmox import (
-    proxmox_auth_argument_spec, ProxmoxAnsible, proxmox_to_ansible_bool, HAS_PROXMOXER, PROXMOXER_IMP_ERR)
+    proxmox_auth_argument_spec, ProxmoxAnsible, proxmox_to_ansible_bool)
 
 
 class ProxmoxUserInfoAnsible(ProxmoxAnsible):
@@ -232,9 +232,6 @@ def main():
         changed=False
     )
 
-    if not HAS_PROXMOXER:
-        module.fail_json(msg=missing_required_lib('proxmoxer'), exception=PROXMOXER_IMP_ERR)
-
     proxmox = ProxmoxUserInfoAnsible(module)
     domain = module.params['domain']
     user = module.params['user']

plugins/modules/cloud/misc/terraform.py

@@ -230,11 +230,12 @@ command:
 import os
 import json
 import tempfile
-from distutils.version import LooseVersion
 from ansible.module_utils.six.moves import shlex_quote
 
 from ansible.module_utils.basic import AnsibleModule
 
+from ansible_collections.community.general.plugins.module_utils.version import LooseVersion
+
 module = None
 
 

plugins/modules/cloud/opennebula/one_vm.py

@@ -1260,6 +1260,11 @@ def resume_vm(module, client, vm):
     vm = client.vm.info(vm.ID)
     changed = False
 
+    state = vm.STATE
+    if state in [VM_STATES.index('HOLD')]:
+        changed = release_vm(module, client, vm)
+        return changed
+
     lcm_state = vm.LCM_STATE
     if lcm_state == LCM_STATES.index('SHUTDOWN_POWEROFF'):
         module.fail_json(msg="Cannot perform action 'resume' because this action is not available " +
@@ -1282,6 +1287,23 @@ def resume_vms(module, client, vms):
     return changed
 
 
+def release_vm(module, client, vm):
+    vm = client.vm.info(vm.ID)
+    changed = False
+
+    state = vm.STATE
+    if state != VM_STATES.index('HOLD'):
+        module.fail_json(msg="Cannot perform action 'release' because this action is not available " +
+                         "because VM is not in state 'HOLD'.")
+    else:
+        changed = True
+
+    if changed and not module.check_mode:
+        client.vm.action('release', vm.ID)
+
+    return changed
+
+
 def check_name_attribute(module, attributes):
     if attributes.get("NAME"):
         import re

plugins/modules/cloud/rackspace/rax_cbs.py

@@ -97,7 +97,7 @@ EXAMPLES = '''
       register: my_volume
 '''
 
-from distutils.version import LooseVersion
+from ansible_collections.community.general.plugins.module_utils.version import LooseVersion
 
 try:
     import pyrax

plugins/modules/cloud/scaleway/scaleway_compute.py

@@ -54,8 +54,15 @@ options:
   organization:
     type: str
     description:
-      - Organization identifier
-    required: true
+      - Organization identifier.
+      - Exactly one of I(project) and I(organization) must be specified.
+
+  project:
+    type: str
+    description:
+      - Project identifier.
+      - Exactly one of I(project) and I(organization) must be specified.
+    version_added: 4.3.0
 
   state:
     type: str
@@ -132,7 +139,7 @@ EXAMPLES = '''
     name: foobar
     state: present
     image: 89ee4018-f8c3-4dc4-a6b5-bca14f985ebe
-    organization: 951df375-e094-4d26-97c1-ba548eeb9c42
+    project: 951df375-e094-4d26-97c1-ba548eeb9c42
     region: ams1
     commercial_type: VC1S
     tags:
@@ -144,7 +151,7 @@ EXAMPLES = '''
     name: foobar
     state: present
     image: 89ee4018-f8c3-4dc4-a6b5-bca14f985ebe
-    organization: 951df375-e094-4d26-97c1-ba548eeb9c42
+    project: 951df375-e094-4d26-97c1-ba548eeb9c42
     region: ams1
     commercial_type: VC1S
     security_group: 4a31b633-118e-4900-bd52-facf1085fc8d
@@ -157,7 +164,7 @@ EXAMPLES = '''
     name: foobar
     state: absent
     image: 89ee4018-f8c3-4dc4-a6b5-bca14f985ebe
-    organization: 951df375-e094-4d26-97c1-ba548eeb9c42
+    project: 951df375-e094-4d26-97c1-ba548eeb9c42
     region: ams1
     commercial_type: VC1S
 '''
@@ -269,10 +276,15 @@ def create_server(compute_api, server):
             "commercial_type": server["commercial_type"],
             "image": server["image"],
             "dynamic_ip_required": server["dynamic_ip_required"],
-            "name": server["name"],
-            "organization": server["organization"]
+            "name": server["name"]
             }
 
+    if server["project"]:
+        data["project"] = server["project"]
+
+    if server["organization"]:
+        data["organization"] = server["organization"]
+
     if server["security_group"]:
         data["security_group"] = server["security_group"]
 
@@ -628,6 +640,7 @@ def core(module):
         "enable_ipv6": module.params["enable_ipv6"],
         "tags": module.params["tags"],
         "organization": module.params["organization"],
+        "project": module.params["project"],
         "security_group": module.params["security_group"]
     }
     module.params['api_url'] = SCALEWAY_LOCATION[region]["api_endpoint"]
@@ -655,7 +668,8 @@ def main():
         public_ip=dict(default="absent"),
         state=dict(choices=list(state_strategy.keys()), default='present'),
         tags=dict(type="list", elements="str", default=[]),
-        organization=dict(required=True),
+        organization=dict(),
+        project=dict(),
         wait=dict(type="bool", default=False),
         wait_timeout=dict(type="int", default=300),
         wait_sleep_time=dict(type="int", default=3),
@@ -664,6 +678,12 @@ def main():
     module = AnsibleModule(
         argument_spec=argument_spec,
         supports_check_mode=True,
+        mutually_exclusive=[
+            ('organization', 'project'),
+        ],
+        required_one_of=[
+            ('organization', 'project'),
+        ],
     )
 
     core(module)

plugins/modules/cloud/scaleway/scaleway_user_data.py

@@ -75,7 +75,7 @@ def patch_user_data(compute_api, server_id, key, value):
     compute_api.module.debug("Starting patching user_data attributes")
 
     path = "servers/%s/user_data/%s" % (server_id, key)
-    response = compute_api.patch(path=path, data=value, headers={"Content-type": "text/plain"})
+    response = compute_api.patch(path=path, data=value, headers={"Content-Type": "text/plain"})
     if not response.ok:
         msg = 'Error during user_data patching: %s %s' % (response.status_code, response.body)
         compute_api.module.fail_json(msg=msg)

plugins/modules/cloud/scaleway/scaleway_volume.py

@@ -51,6 +51,11 @@ options:
     description:
      - Name used to identify the volume.
     required: true
+  project:
+    type: str
+    description:
+     - Scaleway project ID to which volume belongs.
+    version_added: 4.3.0
   organization:
     type: str
     description:
@@ -71,7 +76,7 @@ EXAMPLES = '''
     name: my-volume
     state: present
     region: par1
-    organization: "{{ scw_org }}"
+    project: "{{ scw_org }}"
     "size": 10000000000
     volume_type: l_ssd
   register: server_creation_check_task
@@ -93,7 +98,7 @@ data:
         "export_uri": null,
         "id": "c675f420-cfeb-48ff-ba2a-9d2a4dbe3fcd",
         "name": "volume-0-3",
-        "organization": "000a115d-2852-4b0a-9ce8-47f1134ba95a",
+        "project": "000a115d-2852-4b0a-9ce8-47f1134ba95a",
          "server": null,
          "size": 10000000000,
          "volume_type": "l_ssd"
@@ -106,31 +111,37 @@ from ansible.module_utils.basic import AnsibleModule
 
 
 def core(module):
+    region = module.params["region"]
     state = module.params['state']
     name = module.params['name']
     organization = module.params['organization']
+    project = module.params['project']
     size = module.params['size']
     volume_type = module.params['volume_type']
+    module.params['api_url'] = SCALEWAY_LOCATION[region]["api_endpoint"]
 
     account_api = Scaleway(module)
     response = account_api.get('volumes')
     status_code = response.status_code
     volumes_json = response.json
 
+    if project is None:
+        project = organization
+
     if not response.ok:
         module.fail_json(msg='Error getting volume [{0}: {1}]'.format(
             status_code, response.json['message']))
 
     volumeByName = None
     for volume in volumes_json['volumes']:
-        if volume['organization'] == organization and volume['name'] == name:
+        if volume['project'] == project and volume['name'] == name:
             volumeByName = volume
 
     if state in ('present',):
         if volumeByName is not None:
             module.exit_json(changed=False)
 
-        payload = {'name': name, 'organization': organization, 'size': size, 'volume_type': volume_type}
+        payload = {'name': name, 'project': project, 'size': size, 'volume_type': volume_type}
 
         response = account_api.post('/volumes', payload)
 
@@ -161,6 +172,7 @@ def main():
         state=dict(default='present', choices=['absent', 'present']),
         name=dict(required=True),
         size=dict(type='int'),
+        project=dict(),
         organization=dict(),
         volume_type=dict(),
         region=dict(required=True, choices=list(SCALEWAY_LOCATION.keys())),
@@ -168,6 +180,12 @@ def main():
     module = AnsibleModule(
         argument_spec=argument_spec,
         supports_check_mode=True,
+        mutually_exclusive=[
+            ('organization', 'project'),
+        ],
+        required_one_of=[
+            ('organization', 'project'),
+        ],
     )
 
     core(module)

plugins/modules/database/misc/kibana_plugin.py

@@ -117,9 +117,10 @@ state:
 '''
 
 import os
-from distutils.version import LooseVersion
 from ansible.module_utils.basic import AnsibleModule
 
+from ansible_collections.community.general.plugins.module_utils.version import LooseVersion
+
 
 PACKAGE_STATE_MAP = dict(
     present="--install",

plugins/modules/files/xml.py

@@ -356,9 +356,10 @@ import os
 import re
 import traceback
 
-from distutils.version import LooseVersion
 from io import BytesIO
 
+from ansible_collections.community.general.plugins.module_utils.version import LooseVersion
+
 LXML_IMP_ERR = None
 try:
     from lxml import etree, objectify

plugins/modules/homectl.py

@@ -0,0 +1 @@
+./system/homectl.py

plugins/modules/identity/ipa/ipa_dnszone.py

@@ -27,11 +27,14 @@ options:
     choices: ["absent", "present"]
     type: str
   dynamicupdate:
-    description: Apply dynamic update to zone
-    required: false
-    default: "false"
-    choices: ["false", "true"]
-    type: str
+    description: Apply dynamic update to zone.
+    default: false
+    type: bool
+  allowsyncptr:
+    description: Allow synchronization of forward and reverse records in the zone.
+    default: false
+    type: bool
+    version_added: 4.3.0
 extends_documentation_fragment:
 - community.general.ipa.documentation
 
@@ -60,6 +63,14 @@ EXAMPLES = r'''
     ipa_user: admin
     ipa_pass: topsecret
     state: absent
+
+- name: Ensure dns zone is present and is allowing sync
+  community.general.ipa_dnszone:
+    ipa_host: spider.example.com
+    ipa_pass: Passw0rd!
+    state: present
+    zone_name: example.com
+    allowsyncptr: true
 '''
 
 RETURN = r'''
@@ -79,25 +90,37 @@ class DNSZoneIPAClient(IPAClient):
         super(DNSZoneIPAClient, self).__init__(module, host, port, protocol)
 
     def dnszone_find(self, zone_name, details=None):
-        itens = {'idnsname': zone_name}
+        items = {'all': 'true',
+                 'idnsname': zone_name, }
         if details is not None:
-            itens.update(details)
+            items.update(details)
 
         return self._post_json(
             method='dnszone_find',
             name=zone_name,
-            item=itens
+            item=items
         )
 
     def dnszone_add(self, zone_name=None, details=None):
-        itens = {}
+        items = {}
         if details is not None:
-            itens.update(details)
+            items.update(details)
 
         return self._post_json(
             method='dnszone_add',
             name=zone_name,
-            item=itens
+            item=items
+        )
+
+    def dnszone_mod(self, zone_name=None, details=None):
+        items = {}
+        if details is not None:
+            items.update(details)
+
+        return self._post_json(
+            method='dnszone_mod',
+            name=zone_name,
+            item=items
         )
 
     def dnszone_del(self, zone_name=None, record_name=None, details=None):
@@ -109,18 +132,29 @@ def ensure(module, client):
     zone_name = module.params['zone_name']
     state = module.params['state']
     dynamicupdate = module.params['dynamicupdate']
-
-    ipa_dnszone = client.dnszone_find(zone_name)
+    allowsyncptr = module.params['allowsyncptr']
 
     changed = False
+
+    # does zone exist
+    ipa_dnszone = client.dnszone_find(zone_name)
+
     if state == 'present':
         if not ipa_dnszone:
+
             changed = True
             if not module.check_mode:
-                client.dnszone_add(zone_name=zone_name, details={'idnsallowdynupdate': dynamicupdate})
+                client.dnszone_add(zone_name=zone_name, details={'idnsallowdynupdate': dynamicupdate, 'idnsallowsyncptr': allowsyncptr})
+        elif ipa_dnszone['idnsallowdynupdate'][0] != str(dynamicupdate).upper() or ipa_dnszone['idnsallowsyncptr'][0] != str(allowsyncptr).upper():
+            changed = True
+            if not module.check_mode:
+                client.dnszone_mod(zone_name=zone_name, details={'idnsallowdynupdate': dynamicupdate, 'idnsallowsyncptr': allowsyncptr})
         else:
             changed = False
+
+    # state is absent
     else:
+        # check for generic zone existence
         if ipa_dnszone:
             changed = True
             if not module.check_mode:
@@ -133,7 +167,8 @@ def main():
     argument_spec = ipa_argument_spec()
     argument_spec.update(zone_name=dict(type='str', required=True),
                          state=dict(type='str', default='present', choices=['present', 'absent']),
-                         dynamicupdate=dict(type='str', required=False, default='false', choices=['true', 'false']),
+                         dynamicupdate=dict(type='bool', required=False, default=False),
+                         allowsyncptr=dict(type='bool', required=False, default=False),
                          )
 
     module = AnsibleModule(argument_spec=argument_spec,

plugins/modules/identity/ipa/ipa_subca.py

@@ -74,11 +74,12 @@ subca:
   type: dict
 '''
 
-from distutils.version import LooseVersion
 from ansible.module_utils.basic import AnsibleModule
 from ansible_collections.community.general.plugins.module_utils.ipa import IPAClient, ipa_argument_spec
 from ansible.module_utils.common.text.converters import to_native
 
+from ansible_collections.community.general.plugins.module_utils.version import LooseVersion
+
 
 class SubCAIPAClient(IPAClient):
     def __init__(self, module, host, port, protocol):

plugins/modules/identity/keycloak/keycloak_realm_info.py

@@ -0,0 +1,132 @@
+#!/usr/bin/python
+# -*- coding: utf-8 -*-
+
+# GNU General Public License v3.0+ (see COPYING or https://www.gnu.org/licenses/gpl-3.0.txt)
+
+from __future__ import absolute_import, division, print_function
+__metaclass__ = type
+
+DOCUMENTATION = '''
+---
+module: keycloak_realm_info
+
+short_description: Allows obtaining Keycloak realm public information via Keycloak API
+
+version_added: 4.3.0
+
+description:
+    - This module allows you to get Keycloak realm public information via the Keycloak REST API.
+
+    - The names of module options are snake_cased versions of the camelCase ones found in the
+      Keycloak API and its documentation at U(https://www.keycloak.org/docs-api/8.0/rest-api/index.html).
+
+    - Attributes are multi-valued in the Keycloak API. All attributes are lists of individual values and will
+      be returned that way by this module. You may pass single values for attributes when calling the module,
+      and this will be translated into a list suitable for the API.
+
+options:
+    auth_keycloak_url:
+        description:
+            - URL to the Keycloak instance.
+        type: str
+        required: true
+        aliases:
+          - url
+    validate_certs:
+        description:
+            - Verify TLS certificates (do not disable this in production).
+        type: bool
+        default: yes
+
+    realm:
+        type: str
+        description:
+            - They Keycloak realm ID.
+        default: 'master'
+
+author:
+    - Fynn Chen (@fynncfchen)
+'''
+
+EXAMPLES = '''
+- name: Get a Keycloak public key
+  community.general.keycloak_realm_info:
+    realm: MyCustomRealm
+    auth_keycloak_url: https://auth.example.com/auth
+  delegate_to: localhost
+'''
+
+RETURN = '''
+msg:
+    description: Message as to what action was taken.
+    returned: always
+    type: str
+
+realm_info:
+    description:
+        - Representation of the realm public infomation.
+    returned: always
+    type: dict
+    contains:
+        realm:
+            description: Realm ID.
+            type: str
+            returned: always
+            sample: MyRealm
+        public_key:
+            description: Public key of the realm.
+            type: str
+            returned: always
+            sample: MIIBIjANBgkqhkiG9w0BAQEFAAO...
+        token-service:
+            description: Token endpoint URL.
+            type: str
+            returned: always
+            sample: https://auth.example.com/auth/realms/MyRealm/protocol/openid-connect
+        account-service:
+            description: Account console URL.
+            type: str
+            returned: always
+            sample: https://auth.example.com/auth/realms/MyRealm/account
+        tokens-not-before:
+            description: The token not before.
+            type: int
+            returned: always
+            sample: 0
+'''
+
+from ansible_collections.community.general.plugins.module_utils.identity.keycloak.keycloak import KeycloakAPI
+from ansible.module_utils.basic import AnsibleModule
+
+
+def main():
+    """
+    Module execution
+
+    :return:
+    """
+    argument_spec = dict(
+        auth_keycloak_url=dict(type='str', aliases=['url'], required=True, no_log=False),
+        validate_certs=dict(type='bool', default=True),
+
+        realm=dict(default='master'),
+    )
+
+    module = AnsibleModule(argument_spec=argument_spec,
+                           supports_check_mode=True)
+
+    result = dict(changed=False, msg='', realm_info='')
+
+    kc = KeycloakAPI(module, {})
+
+    realm = module.params.get('realm')
+
+    realm_info = kc.get_realm_info_by_id(realm=realm)
+
+    result['realm_info'] = realm_info
+    result['msg'] = 'Get realm public info successful for ID {realm}'.format(realm=realm)
+    module.exit_json(**result)
+
+
+if __name__ == '__main__':
+    main()

plugins/modules/keycloak_realm_info.py

@@ -0,0 +1 @@
+./identity/keycloak/keycloak_realm_info.py

plugins/modules/monitoring/circonus_annotation.py

@@ -143,7 +143,8 @@ annotation:
 import json
 import time
 import traceback
-from distutils.version import LooseVersion
+
+from ansible_collections.community.general.plugins.module_utils.version import LooseVersion
 
 REQUESTS_IMP_ERR = None
 try:

plugins/modules/net_tools/dnsimple.py

@@ -148,9 +148,10 @@ EXAMPLES = '''
 RETURN = r"""# """
 
 import traceback
-from distutils.version import LooseVersion
 import re
 
+from ansible_collections.community.general.plugins.module_utils.version import LooseVersion
+
 
 class DNSimpleV1():
     """class which uses dnsimple-python < 2"""

plugins/modules/net_tools/nmcli.py

@@ -55,8 +55,10 @@ options:
             - Type C(generic) is added in Ansible 2.5.
             - Type C(infiniband) is added in community.general 2.0.0.
             - Type C(gsm) is added in community.general 3.7.0.
+            - Type C(wireguard) is added in community.general 4.3.0
         type: str
-        choices: [ bond, bond-slave, bridge, bridge-slave, dummy, ethernet, generic, gre, infiniband, ipip, sit, team, team-slave, vlan, vxlan, wifi, gsm ]
+        choices: [ bond, bond-slave, bridge, bridge-slave, dummy, ethernet, generic, gre, infiniband, ipip, sit, team, team-slave, vlan, vxlan, wifi, gsm,
+            wireguard ]
     mode:
         description:
             - This is the type of device or network connection that you wish to create for a bond or bridge.
@@ -159,6 +161,18 @@ options:
         type: bool
         default: false
         version_added: 3.2.0
+    routes6:
+        description:
+            - The list of IPv6 routes.
+            - Use the format C(fd12:3456:789a:1::/64 2001:dead:beef::1).
+        type: list
+        elements: str
+        version_added: 4.4.0
+    route_metric6:
+        description:
+            - Set metric level of IPv6 routes configured on interface.
+        type: int
+        version_added: 4.4.0
     dns6:
         description:
             - A list of up to 3 dns servers.
@@ -754,6 +768,62 @@ options:
                     - The username used to authenticate with the network, if required.
                     - Many providers do not require a username, or accept any username.
                     - But if a username is required, it is specified here.
+    wireguard:
+        description:
+            - The configuration of the Wireguard connection.
+            - Note the list of suboption attributes may vary depending on which version of NetworkManager/nmcli is installed on the host.
+            - 'An up-to-date list of supported attributes can be found here:
+              U(https://networkmanager.dev/docs/api/latest/settings-wireguard.html).'
+            - 'For instance to configure a listen port:
+              C({listen-port: 12345}).'
+        type: dict
+        version_added: 4.3.0
+        suboptions:
+            fwmark:
+                description:
+                    - The 32-bit fwmark for outgoing packets.
+                    - The use of fwmark is optional and is by default off. Setting it to 0 disables it.
+                    - Note that I(wireguard.ip4-auto-default-route) or I(wireguard.ip6-auto-default-route) enabled, implies to automatically choose a fwmark.
+                type: int
+            ip4-auto-default-route:
+                description:
+                    - Whether to enable special handling of the IPv4 default route.
+                    - If enabled, the IPv4 default route from I(wireguard.peer-routes) will be placed to a dedicated routing-table and two policy
+                        routing rules will be added.
+                    - The fwmark number is also used as routing-table for the default-route, and if fwmark is zero, an unused fwmark/table is chosen
+                        automatically. This corresponds to what wg-quick does with Table=auto and what WireGuard calls "Improved Rule-based Routing"
+                type: bool
+            ip6-auto-default-route:
+                description:
+                    - Like I(wireguard.ip4-auto-default-route), but for the IPv6 default route.
+                type: bool
+            listen-port:
+                description: The WireGuard connection listen-port. If not specified, the port will be chosen randomly when the
+                    interface comes up.
+                type: int
+            mtu:
+                description:
+                    - If non-zero, only transmit packets of the specified size or smaller, breaking larger packets up into multiple fragments.
+                    - If zero a default MTU is used. Note that contrary to wg-quick's MTU setting, this does not take into account the current routes
+                        at the time of activation.
+                type: int
+            peer-routes:
+                description:
+                    - Whether to automatically add routes for the AllowedIPs ranges of the peers.
+                    - If C(true) (the default), NetworkManager will automatically add routes in the routing tables according to C(ipv4.route-table) and
+                        C(ipv6.route-table). Usually you want this automatism enabled.
+                    - If C(false), no such routes are added automatically. In this case, the user may want to configure static routes in C(ipv4.routes)
+                        and C(ipv6.routes), respectively.
+                    - Note that if the peer's AllowedIPs is C(0.0.0.0/0) or C(::/0) and the profile's C(ipv4.never-default) or C(ipv6.never-default)
+                        setting is enabled, the peer route for this peer won't be added automatically.
+                type: bool
+            private-key:
+                description: The 256 bit private-key in base64 encoding.
+                type: str
+            private-key-flags:
+                description: C(NMSettingSecretFlags) indicating how to handle the I(wireguard.private-key) property.
+                type: int
+                choices: [ 0, 1, 2 ]
 '''
 
 EXAMPLES = r'''
@@ -1126,6 +1196,17 @@ EXAMPLES = r'''
     autoconnect: true
     state: present
 
+- name: Create a wireguard connection
+  community.general.nmcli:
+    type: wireguard
+    conn_name: my-wg-provider
+    ifname: mywg0
+    wireguard:
+        listen-port: 51820
+        private-key: my-private-key
+    autoconnect: true
+    state: present
+
 '''
 
 RETURN = r"""#
@@ -1190,6 +1271,8 @@ class Nmcli(object):
         self.ip6 = module.params['ip6']
         self.gw6 = module.params['gw6']
         self.gw6_ignore_auto = module.params['gw6_ignore_auto']
+        self.routes6 = module.params['routes6']
+        self.route_metric6 = module.params['route_metric6']
         self.dns6 = module.params['dns6']
         self.dns6_search = module.params['dns6_search']
         self.dns6_ignore_auto = module.params['dns6_ignore_auto']
@@ -1236,10 +1319,11 @@ class Nmcli(object):
         self.wifi = module.params['wifi']
         self.wifi_sec = module.params['wifi_sec']
         self.gsm = module.params['gsm']
+        self.wireguard = module.params['wireguard']
 
         if self.method4:
             self.ipv4_method = self.method4
-        elif self.type == 'dummy' and not self.ip4:
+        elif self.type in ('dummy', 'wireguard') and not self.ip4:
             self.ipv4_method = 'disabled'
         elif self.ip4:
             self.ipv4_method = 'manual'
@@ -1248,7 +1332,7 @@ class Nmcli(object):
 
         if self.method6:
             self.ipv6_method = self.method6
-        elif self.type == 'dummy' and not self.ip6:
+        elif self.type in ('dummy', 'wireguard') and not self.ip6:
             self.ipv6_method = 'disabled'
         elif self.ip6:
             self.ipv6_method = 'manual'
@@ -1299,6 +1383,8 @@ class Nmcli(object):
                 'ipv6.ignore-auto-dns': self.dns6_ignore_auto,
                 'ipv6.gateway': self.gw6,
                 'ipv6.ignore-auto-routes': self.gw6_ignore_auto,
+                'ipv6.routes': self.routes6,
+                'ipv6.route-metric': self.route_metric6,
                 'ipv6.method': self.ipv6_method,
                 'ipv6.ip6-privacy': self.ip_privacy6,
                 'ipv6.addr-gen-mode': self.addr_gen_mode6
@@ -1404,6 +1490,12 @@ class Nmcli(object):
                     options.update({
                         'gsm.%s' % name: value,
                     })
+        elif self.type == 'wireguard':
+            if self.wireguard:
+                for name, value in self.wireguard.items():
+                    options.update({
+                        'wireguard.%s' % name: value,
+                    })
         # Convert settings values based on the situation.
         for setting, value in options.items():
             setting_type = self.settings_type(setting)
@@ -1445,6 +1537,7 @@ class Nmcli(object):
             'vlan',
             'wifi',
             'gsm',
+            'wireguard',
         )
 
     @property
@@ -1551,6 +1644,7 @@ class Nmcli(object):
                          'ipv4.routing-rules',
                          'ipv6.dns',
                          'ipv6.dns-search',
+                         'ipv6.routes',
                          '802-11-wireless-security.group',
                          '802-11-wireless-security.leap-password-flags',
                          '802-11-wireless-security.pairwise',
@@ -1676,7 +1770,7 @@ class Nmcli(object):
                             alias_key = alias_pair[0]
                             alias_value = alias_pair[1]
                             conn_info[alias_key] = alias_value
-                elif key == 'ipv4.routes':
+                elif key in ('ipv4.routes', 'ipv6.routes'):
                     conn_info[key] = [s.strip() for s in raw_value.split(';')]
                 elif key_type == list:
                     conn_info[key] = [s.strip() for s in raw_value.split(',')]
@@ -1755,8 +1849,8 @@ class Nmcli(object):
 
             if key in conn_info:
                 current_value = conn_info[key]
-                if key == 'ipv4.routes' and current_value is not None:
-                    # ipv4.routes do not have same options and show_connection() format
+                if key in ('ipv4.routes', 'ipv6.routes') and current_value is not None:
+                    # ipv4.routes and ipv6.routes do not have same options and show_connection() format
                     # options: ['10.11.0.0/24 10.10.0.2', '10.12.0.0/24 10.10.0.2 200']
                     # show_connection(): ['{ ip = 10.11.0.0/24, nh = 10.10.0.2 }', '{ ip = 10.12.0.0/24, nh = 10.10.0.2, mt = 200 }']
                     # Need to convert in order to compare both
@@ -1834,6 +1928,7 @@ def main():
                           'vxlan',
                           'wifi',
                           'gsm',
+                          'wireguard',
                       ]),
             ip4=dict(type='list', elements='str'),
             gw4=dict(type='str'),
@@ -1854,6 +1949,8 @@ def main():
             dns6=dict(type='list', elements='str'),
             dns6_search=dict(type='list', elements='str'),
             dns6_ignore_auto=dict(type='bool', default=False),
+            routes6=dict(type='list', elements='str'),
+            route_metric6=dict(type='int'),
             method6=dict(type='str', choices=['ignore', 'auto', 'dhcp', 'link-local', 'manual', 'shared', 'disabled']),
             ip_privacy6=dict(type='str', choices=['disabled', 'prefer-public-addr', 'prefer-temp-addr', 'unknown']),
             addr_gen_mode6=dict(type='str', choices=['eui64', 'stable-privacy']),
@@ -1907,6 +2004,7 @@ def main():
             wifi=dict(type='dict'),
             wifi_sec=dict(type='dict', no_log=True),
             gsm=dict(type='dict'),
+            wireguard=dict(type='dict'),
         ),
         mutually_exclusive=[['never_default4', 'gw4']],
         required_if=[("type", "wifi", [("ssid")])],

plugins/modules/notification/mattermost.py

@@ -38,7 +38,15 @@ options:
     type: str
     description:
       - Text to send. Note that the module does not handle escaping characters.
-    required: true
+      - Required when I(attachments) is not set.
+  attachments:
+    type: list
+    elements: dict
+    description:
+      - Define a list of attachments.
+      - For more information, see U(https://developers.mattermost.com/integrate/admin-guide/admin-message-attachments/).
+      - Required when I(text) is not set.
+    version_added: 4.3.0
   channel:
     type: str
     description:
@@ -76,6 +84,22 @@ EXAMPLES = """
     channel: notifications
     username: 'Ansible on {{ inventory_hostname }}'
     icon_url: http://www.example.com/some-image-file.png
+
+- name: Send attachments message via Mattermost
+  community.general.mattermost:
+    url: http://mattermost.example.com
+    api_key: my_api_key
+    attachments:
+      - text: Display my system load on host A and B
+        color: '#ff00dd'
+        title: System load
+        fields:
+          - title: System A
+            value: "load average: 0,74, 0,66, 0,63"
+            short: True
+          - title: System B
+            value: 'load average: 5,16, 4,64, 2,43'
+            short: True
 """
 
 RETURN = '''
@@ -99,12 +123,16 @@ def main():
         argument_spec=dict(
             url=dict(type='str', required=True),
             api_key=dict(type='str', required=True, no_log=True),
-            text=dict(type='str', required=True),
+            text=dict(type='str'),
             channel=dict(type='str', default=None),
             username=dict(type='str', default='Ansible'),
             icon_url=dict(type='str', default='https://www.ansible.com/favicon.ico'),
             validate_certs=dict(default=True, type='bool'),
-        )
+            attachments=dict(type='list', elements='dict'),
+        ),
+        required_one_of=[
+            ('text', 'attachments'),
+        ],
     )
     # init return dict
     result = dict(changed=False, msg="OK")
@@ -115,7 +143,7 @@ def main():
 
     # define payload
     payload = {}
-    for param in ['text', 'channel', 'username', 'icon_url']:
+    for param in ['text', 'channel', 'username', 'icon_url', 'attachments']:
         if module.params[param] is not None:
             payload[param] = module.params[param]
 

plugins/modules/notification/mqtt.py

@@ -124,7 +124,8 @@ import os
 import ssl
 import traceback
 import platform
-from distutils.version import LooseVersion
+
+from ansible_collections.community.general.plugins.module_utils.version import LooseVersion
 
 HAS_PAHOMQTT = True
 PAHOMQTT_IMP_ERR = None
@@ -207,7 +208,7 @@ def main():
         if tls_version:
             tls_version = tls_map.get(tls_version, ssl.PROTOCOL_SSLv23)
         else:
-            if LooseVersion(platform.python_version()) <= "3.5.2":
+            if LooseVersion(platform.python_version()) <= LooseVersion("3.5.2"):
                 # Specifying `None` on later versions of python seems sufficient to
                 # instruct python to autonegotiate the SSL/TLS connection. On versions
                 # 3.5.2 and lower though we need to specify the version.