feat: add support for build/prune API (#1007)

* feat: add support for build/prune API

* Fix mypy failure

* Apply suggestion from @bdraco

* Apply suggestion from @bdraco

* Remove unused image_name fixture

---------

Co-authored-by: J. Nick Koston <nick+github@koston.org>

Author: mdegat01

CHANGES/1007.feature.md

@@ -0,0 +1 @@
+Introduce support in the library for the `build/prune` API endpoint.

aiodocker/images.py

@@ -282,6 +282,53 @@ async def prune(
         response = await self.docker._query_json("images/prune", "POST", params=params)
         return response
 
+    async def prune_builds(
+        self,
+        *,
+        reserved_space: Optional[int] = None,
+        max_used_space: Optional[int] = None,
+        min_free_space: Optional[int] = None,
+        all_builds: Optional[bool] = None,
+        filters: Optional[Mapping[str, Any]] = None,
+    ) -> Dict[str, Any]:
+        """
+        Delete builder cache
+
+        Args:
+            reserved_space: Amount of disk space in bytes to keep for cache.
+            max_used_space: Maximum amount of disk space allowed to keep for cache.
+            min_free_space: Target amount of free disk space after pruning.
+            all_builds: When true, consider all unused build cache objects for pruning.
+                When false, only consider dangling build cache objects for pruning.
+            filters: Filter expressions to limit what types of build cache objects are pruned.
+                    Available filters:
+                    - until: Only remove build cache objects created before given timestamp.
+                    - id: id=<id>
+                    - parent: parent=<id>
+                    - type: type=<string>
+                    - description: description=<string>
+                    - inuse
+                    - shared
+                    - private
+
+        Returns:
+            Dictionary containing information about deleted caches and space reclaimed
+        """
+        params: Dict[str, Any] = {}
+        if reserved_space is not None:
+            params["reserved-space"] = reserved_space
+        if max_used_space is not None:
+            params["max-used-space"] = max_used_space
+        if min_free_space is not None:
+            params["min-free-space"] = min_free_space
+        if all_builds is not None:
+            params["all"] = all_builds
+        if filters is not None:
+            params["filters"] = clean_filters(filters)
+
+        response = await self.docker._query_json("build/prune", "POST", params=params)
+        return response
+
     @staticmethod
     async def _stream(fileobj: SupportsRead[bytes]) -> AsyncIterator[bytes]:
         chunk = fileobj.read(io.DEFAULT_BUFFER_SIZE)

tests/test_images.py

@@ -399,3 +399,35 @@ async def test_prune_images_without_filters(docker: Docker) -> None:
     assert "SpaceReclaimed" in result
     assert result["ImagesDeleted"] is None
     assert isinstance(result["SpaceReclaimed"], int)
+
+
+@pytest.mark.asyncio
+async def test_prune_builds_with_options(docker: Docker, random_name: str) -> None:
+    """Test builds prune with options set."""
+    result = await docker.images.prune_builds(
+        reserved_space=0,
+        max_used_space=10**9,
+        min_free_space=0,
+        all_builds=True,
+        filters={"id": random_name},
+    )
+
+    # Verify the response structure
+    assert isinstance(result, dict)
+    assert "CachesDeleted" in result
+    assert "SpaceReclaimed" in result
+    assert result["CachesDeleted"] is None
+    assert isinstance(result["SpaceReclaimed"], int)
+
+
+@pytest.mark.asyncio
+async def test_prune_builds_default_options(docker: Docker) -> None:
+    """Test builds prune using default options."""
+    result = await docker.images.prune_builds()
+
+    # Verify the response structure
+    assert isinstance(result, dict)
+    assert "CachesDeleted" in result
+    assert "SpaceReclaimed" in result
+    assert result["CachesDeleted"] is None
+    assert isinstance(result["SpaceReclaimed"], int)