Add prune_containers method

Signed-off-by: Joffrey F <joffrey@docker.com>

docker/api/container.py

@@ -911,9 +911,6 @@ class ContainerApiMixin(object):
         Raises:
             :py:class:`docker.errors.APIError`
                 If the server returns an error.
-
-        Raises:
-            :py:class:`~docker.errors.APIError` If an error occurs.
         """
         params = {'path': path}
         url = self._url('/containers/{0}/archive', container)
@@ -921,6 +918,28 @@ class ContainerApiMixin(object):
         self._raise_for_status(res)
         return res.status_code == 200
 
+    @utils.minimum_version('1.25')
+    def prune_containers(self, filters=None):
+        """
+        Delete stopped containers
+
+        Args:
+            filters (dict): Filters to process on the prune list.
+
+        Returns:
+            (dict): A dict containing a list of deleted container IDs and
+                the amount of disk space reclaimed in bytes.
+
+        Raises:
+            :py:class:`docker.errors.APIError`
+                If the server returns an error.
+        """
+        params = {}
+        if filters:
+            params['filters'] = utils.convert_filters(filters)
+        url = self._url('/containers/prune')
+        return self._result(self._post(url, params=params), True)
+
     @utils.check_resource
     def remove_container(self, container, v=False, link=False, force=False):
         """

docker/models/containers.py

@@ -763,6 +763,23 @@ class ContainerCollection(Collection):
                                           since=since)
         return [self.get(r['Id']) for r in resp]
 
+    def prune(self, filters=None):
+        """
+        Delete stopped containers
+
+        Args:
+            filters (dict): Filters to process on the prune list.
+
+        Returns:
+            (dict): A dict containing a list of deleted container IDs and
+                the amount of disk space reclaimed in bytes.
+
+        Raises:
+            :py:class:`docker.errors.APIError`
+                If the server returns an error.
+        """
+        return self.client.api.prune_containers(filters=filters)
+
 
 # kwargs to copy straight from run to create
 RUN_CREATE_KWARGS = [

tests/integration/api_container_test.py

@@ -1094,6 +1094,20 @@ class PauseTest(BaseAPIIntegrationTest):
         self.assertEqual(state['Paused'], False)
 
 
+class PruneTest(BaseAPIIntegrationTest):
+    @requires_api_version('1.25')
+    def test_prune_containers(self):
+        container1 = self.client.create_container(BUSYBOX, ['echo', 'hello'])
+        container2 = self.client.create_container(BUSYBOX, ['sleep', '9999'])
+        self.client.start(container1)
+        self.client.start(container2)
+        self.client.wait(container1)
+        result = self.client.prune_containers()
+        assert container1['Id'] in result['ContainersDeleted']
+        assert result['SpaceReclaimed'] > 0
+        assert container2['Id'] not in result['ContainersDeleted']
+
+
 class GetContainerStatsTest(BaseAPIIntegrationTest):
     @requires_api_version('1.19')
     def test_get_container_stats_no_stream(self):