From 3802e424d947b401351141f6d8299a79b0aaef03 Mon Sep 17 00:00:00 2001
From: Felix Fontein <felix@fontein.de>
Date: Tue, 17 Sep 2024 20:50:48 +0200
Subject: [PATCH] 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 |  3 +++
 plugins/modules/docker_prune.py            | 26 +++++++++++++++++-----
 2 files changed, 24 insertions(+), 5 deletions(-)
 create mode 100644 changelogs/fragments/966-prune-filters.yml

diff --git a/changelogs/fragments/966-prune-filters.yml b/changelogs/fragments/966-prune-filters.yml
new file mode 100644
index 00000000..470b4158
--- /dev/null
+++ b/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)."
diff --git a/plugins/modules/docker_prune.py b/plugins/modules/docker_prune.py
index a333c52f..d2b1e193 100644
--- a/plugins/modules/docker_prune.py
+++ b/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'