From 49c8fd0aa55aaf6d0ff09733376731ae5602333f Mon Sep 17 00:00:00 2001
From: Ajpantuso <ajpantuso@gmail.com>
Date: Tue, 22 Jun 2021 16:27:38 -0400
Subject: [PATCH] docker_host_info - Allow filters which are passed as lists
 (#160)

* Initial Commit

* Adding integration tests

* Adding example in docs

* Adding changelog fragment

* Applying initial review suggestions
---
 ...60-docker_host_info-label-fitler-lists.yml |  4 ++
 plugins/module_utils/common.py                | 23 +++++++----
 plugins/modules/docker_host_info.py           | 19 ++++++++-
 .../docker_host_info/tasks/test_host_info.yml | 41 +++++++++++++++++++
 4 files changed, 77 insertions(+), 10 deletions(-)
 create mode 100644 changelogs/fragments/160-docker_host_info-label-fitler-lists.yml

diff --git a/changelogs/fragments/160-docker_host_info-label-fitler-lists.yml b/changelogs/fragments/160-docker_host_info-label-fitler-lists.yml
new file mode 100644
index 00000000..4b58bfc4
--- /dev/null
+++ b/changelogs/fragments/160-docker_host_info-label-fitler-lists.yml
@@ -0,0 +1,4 @@
+---
+minor_changes:
+  - docker_host_info - allow values for keys in ``containers_filters``, ``images_filters``, ``networks_filters``, and
+    ``volumes_filters`` to be passed as YAML lists (https://github.com/ansible-collections/community.docker/pull/160).
diff --git a/plugins/module_utils/common.py b/plugins/module_utils/common.py
index 7e9f4a2e..99fb59c5 100644
--- a/plugins/module_utils/common.py
+++ b/plugins/module_utils/common.py
@@ -15,6 +15,7 @@ from distutils.version import LooseVersion
 
 
 from ansible.module_utils.basic import AnsibleModule, env_fallback, missing_required_lib
+from ansible.module_utils.common.collections import is_sequence
 from ansible.module_utils.common._collections_compat import Mapping, Sequence
 from ansible.module_utils.six import string_types
 from ansible.module_utils.six.moves.urllib.parse import urlparse
@@ -927,23 +928,27 @@ class DifferenceTracker(object):
         return result
 
 
-def clean_dict_booleans_for_docker_api(data):
+def clean_dict_booleans_for_docker_api(data, allow_sequences=False):
     '''
     Go doesn't like Python booleans 'True' or 'False', while Ansible is just
     fine with them in YAML. As such, they need to be converted in cases where
     we pass dictionaries to the Docker API (e.g. docker_network's
-    driver_options and docker_prune's filters).
+    driver_options and docker_prune's filters). When `allow_sequences=True`
+    YAML sequences (lists, tuples) are converted to [str] instead of str([...])
+    which is the expected format of filters which accept lists such as labels.
     '''
+    def sanitize(value):
+        if value is True:
+            return 'true'
+        elif value is False:
+            return 'false'
+        else:
+            return str(value)
+
     result = dict()
     if data is not None:
         for k, v in data.items():
-            if v is True:
-                v = 'true'
-            elif v is False:
-                v = 'false'
-            else:
-                v = str(v)
-            result[str(k)] = v
+            result[str(k)] = [sanitize(e) for e in v] if allow_sequences and is_sequence(v) else sanitize(v)
     return result
 
 
diff --git a/plugins/modules/docker_host_info.py b/plugins/modules/docker_host_info.py
index 3700a32a..599a92d7 100644
--- a/plugins/modules/docker_host_info.py
+++ b/plugins/modules/docker_host_info.py
@@ -33,6 +33,8 @@ options:
     description:
       - A dictionary of filter values used for selecting containers to list.
       - "For example, C(until: 24h)."
+      - C(label) is a special case of filter which can be a string C(<key>) matching when a label is present, a string
+        C(<key>=<value>) matching when a label has a particular value, or a list of strings C(<key>)/C(<key>=<value).
       - See L(the docker documentation,https://docs.docker.com/engine/reference/commandline/container_prune/#filtering)
         for more information on possible filters.
     type: dict
@@ -45,6 +47,8 @@ options:
     description:
       - A dictionary of filter values used for selecting images to list.
       - "For example, C(dangling: true)."
+      - C(label) is a special case of filter which can be a string C(<key>) matching when a label is present, a string
+        C(<key>=<value>) matching when a label has a particular value, or a list of strings C(<key>)/C(<key>=<value).
       - See L(the docker documentation,https://docs.docker.com/engine/reference/commandline/image_prune/#filtering)
         for more information on possible filters.
     type: dict
@@ -56,6 +60,8 @@ options:
   networks_filters:
     description:
       - A dictionary of filter values used for selecting networks to list.
+      - C(label) is a special case of filter which can be a string C(<key>) matching when a label is present, a string
+        C(<key>=<value>) matching when a label has a particular value, or a list of strings C(<key>)/C(<key>=<value).
       - See L(the docker documentation,https://docs.docker.com/engine/reference/commandline/network_prune/#filtering)
         for more information on possible filters.
     type: dict
@@ -67,6 +73,8 @@ options:
   volumes_filters:
     description:
       - A dictionary of filter values used for selecting volumes to list.
+      - C(label) is a special case of filter which can be a string C(<key>) matching when a label is present, a string
+        C(<key>=<value>) matching when a label has a particular value, or a list of strings C(<key>)/C(<key>=<value).
       - See L(the docker documentation,https://docs.docker.com/engine/reference/commandline/volume_prune/#filtering)
         for more information on possible filters.
     type: dict
@@ -126,6 +134,15 @@ EXAMPLES = '''
     disk_usage: yes
   register: result
 
+- name: Get info on docker host and list containers matching the filter
+  community.docker.docker_host_info:
+    containers: yes
+    containers_filters:
+      label:
+        - key1=value1
+        - key2=value2
+  register: result
+
 - ansible.builtin.debug:
     var: result.host_info
 
@@ -223,7 +240,7 @@ class DockerHostManager(DockerBaseClass):
             if self.client.module.params[docker_object]:
                 returned_name = docker_object
                 filter_name = docker_object + "_filters"
-                filters = clean_dict_booleans_for_docker_api(client.module.params.get(filter_name))
+                filters = clean_dict_booleans_for_docker_api(client.module.params.get(filter_name), True)
                 self.results[returned_name] = self.get_docker_items_list(docker_object, filters)
 
     def get_docker_host_info(self):
diff --git a/tests/integration/targets/docker_host_info/tasks/test_host_info.yml b/tests/integration/targets/docker_host_info/tasks/test_host_info.yml
index ef2a58a6..9c456ea8 100644
--- a/tests/integration/targets/docker_host_info/tasks/test_host_info.yml
+++ b/tests/integration/targets/docker_host_info/tasks/test_host_info.yml
@@ -31,6 +31,9 @@
       image: "{{ docker_test_image_alpine }}"
       command: '/bin/sh -c "sleep 10m"'
       name: "{{ cname }}"
+      labels:
+        key1: value1
+        key2: value2
       state: started
     register: container_output
 
@@ -63,6 +66,44 @@
          - 'output.containers[0].Image is string'
          - 'output.containers[0].ImageID is not defined'
 
+  - name: Get info on Docker host and list containers matching filters (single label)
+    docker_host_info:
+      containers: yes
+      containers_filters:
+        label: key1=value1
+    register: output
+
+  - name: assert container is returned when filters are matched (single label)
+    assert:
+      that: "{{ output.containers | length }} == 1"
+
+  - name: Get info on Docker host and list containers matching filters (multiple labels)
+    docker_host_info:
+      containers: yes
+      containers_filters:
+        label:
+          - key1=value1
+          - key2=value2
+    register: output
+
+  - name: assert container is returned when filters are matched (multiple labels)
+    assert:
+      that: "{{ output.containers | length }} == 1"
+
+  - name: Get info on Docker host and do not list containers which do not match filters
+    docker_host_info:
+      containers: yes
+      containers_filters:
+        label:
+          - key1=value1
+          - key2=value2
+          - key3=value3
+    register: output
+
+  - name: assert no container is returned when filters are not matched
+    assert:
+      that: "{{ output.containers | length }} == 0"
+
   - name: Get info on Docker host and list containers with verbose output
     docker_host_info:
       containers: yes