docker_prune: improve docs, fix handling of lists for filters (#966)

* Improve docs.

* Fix handling of lists for filters.

changelogs/fragments/966-prune-filters.yml

@@ -0,0 +1,3 @@
+bugfixes:
+  - "docker_prune - fix handling of lists for the filter options
+     (https://github.com/ansible-collections/community.docker/issues/961, https://github.com/ansible-collections/community.docker/pull/966)."

plugins/modules/docker_prune.py

@@ -122,6 +122,22 @@ EXAMPLES = '''
       # only consider containers created more than 24 hours ago
       until: 24h
 
+- name: Prune containers with labels
+  community.docker.docker_prune:
+    containers: true
+    containers_filters:
+      # Prune containers whose "foo" label has value "bar", and
+      # whose "bam" label has value "baz". If you only want to
+      # compare one label, you can provide it as a string instead
+      # of a list with one element.
+      label:
+        - foo=bar
+        - bam=baz
+      # Prune containers whose label "bar" does *not* have value
+      # "baz". If you want to avoid more than one label, you can
+      # provide a list of multiple label-value pairs.
+      "label!": bar=baz
+
 - name: Prune everything
   community.docker.docker_prune:
     containers: true
@@ -268,7 +284,7 @@ def main():
         changed = False
 
         if client.module.params['containers']:
-            filters = clean_dict_booleans_for_docker_api(client.module.params.get('containers_filters'))
+            filters = clean_dict_booleans_for_docker_api(client.module.params.get('containers_filters'), allow_sequences=True)
             params = {'filters': convert_filters(filters)}
             res = client.post_to_json('/containers/prune', params=params)
             result['containers'] = res.get('ContainersDeleted') or []
@@ -277,7 +293,7 @@ def main():
                 changed = True
 
         if client.module.params['images']:
-            filters = clean_dict_booleans_for_docker_api(client.module.params.get('images_filters'))
+            filters = clean_dict_booleans_for_docker_api(client.module.params.get('images_filters'), allow_sequences=True)
             params = {'filters': convert_filters(filters)}
             res = client.post_to_json('/images/prune', params=params)
             result['images'] = res.get('ImagesDeleted') or []
@@ -286,7 +302,7 @@ def main():
                 changed = True
 
         if client.module.params['networks']:
-            filters = clean_dict_booleans_for_docker_api(client.module.params.get('networks_filters'))
+            filters = clean_dict_booleans_for_docker_api(client.module.params.get('networks_filters'), allow_sequences=True)
             params = {'filters': convert_filters(filters)}
             res = client.post_to_json('/networks/prune', params=params)
             result['networks'] = res.get('NetworksDeleted') or []
@@ -294,7 +310,7 @@ def main():
                 changed = True
 
         if client.module.params['volumes']:
-            filters = clean_dict_booleans_for_docker_api(client.module.params.get('volumes_filters'))
+            filters = clean_dict_booleans_for_docker_api(client.module.params.get('volumes_filters'), allow_sequences=True)
             params = {'filters': convert_filters(filters)}
             res = client.post_to_json('/volumes/prune', params=params)
             result['volumes'] = res.get('VolumesDeleted') or []
@@ -303,7 +319,7 @@ def main():
                 changed = True
 
         if client.module.params['builder_cache']:
-            filters = clean_dict_booleans_for_docker_api(client.module.params.get('builder_cache_filters'))
+            filters = clean_dict_booleans_for_docker_api(client.module.params.get('builder_cache_filters'), allow_sequences=True)
             params = {'filters': convert_filters(filters)}
             if client.module.params.get('builder_cache_all'):
                 params['all'] = 'true'