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

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
 
 

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