Add deprecation warnings supporting old form of filters

Author: LewisGaul

python_on_whales/components/container/cli_wrapper.py

@@ -4,6 +4,7 @@
 import json
 import shlex
 import textwrap
+import warnings
 from datetime import datetime, timedelta
 from pathlib import Path
 from typing import (
@@ -1173,18 +1174,27 @@ def logs(
     def list(
         self,
         all: bool = False,
-        filters: Iterable[ContainerListFilter] = (),
+        filters: Union[Iterable[ContainerListFilter], Mapping[str, Any]] = (),
     ) -> List[Container]:
         """List the containers on the host.
 
         Alias: `docker.ps(...)`
 
         Parameters:
             all: If `True`, also returns containers that are not running.
+            filters: Filters to apply when listing containers.
 
         # Returns
             A `List[python_on_whales.Container]`
         """
+        if isinstance(filters, Mapping):
+            filters = filters.items()
+            warnings.warn(
+                "Passing filters as a mapping is deprecated, replace with an "
+                "iterable of tuples instead, as so:\n"
+                f"filters={list(filters)}",
+                DeprecationWarning,
+            )
         full_cmd = self.docker_cmd
         full_cmd += ["container", "list", "-q", "--no-trunc"]
         full_cmd.add_flag("--all", all)
@@ -1222,20 +1232,20 @@ def pause(
     @overload
     def prune(
         self,
-        filters: Iterable[ContainerListFilter] = (),
+        filters: Union[Iterable[ContainerListFilter], Mapping[str, Any]] = (),
         stream_logs: Literal[True] = ...,
     ) -> Iterable[Tuple[str, bytes]]: ...
 
     @overload
     def prune(
         self,
-        filters: Iterable[ContainerListFilter] = (),
+        filters: Union[Iterable[ContainerListFilter], Mapping[str, Any]] = (),
         stream_logs: Literal[False] = ...,
     ) -> None: ...
 
     def prune(
         self,
-        filters: Iterable[ContainerListFilter] = (),
+        filters: Union[Iterable[ContainerListFilter], Mapping[str, Any]] = (),
         stream_logs: bool = False,
     ):
         """Remove containers that are not running.
@@ -1247,11 +1257,13 @@ def prune(
                 the function returns `None`, but when it returns, then the prune operation has already been
                 done.
         """
-        if isinstance(filter, list):
-            raise TypeError(
-                "since python-on-whales 0.38.0, the filter argument is expected to be "
-                "a dict, not a list, please replace your function call by "
-                "docker.container.prune(filters={...})"
+        if isinstance(filters, Mapping):
+            filters = filters.items()
+            warnings.warn(
+                "Passing filters as a mapping is deprecated, replace with an "
+                "iterable of tuples instead, as so:\n"
+                f"filters={list(filters)}",
+                DeprecationWarning,
             )
         full_cmd = self.docker_cmd + ["container", "prune", "--force"]
         full_cmd.add_args_iterable("--filter", (f"{f[0]}={f[1]}" for f in filters))

python_on_whales/components/image/cli_wrapper.py

@@ -433,7 +433,7 @@ def _load_from_generator(self, full_cmd: List[str], input: Iterator[bytes]):
     def list(
         self,
         repository_or_tag: Optional[str] = None,
-        filters: Iterable[ImageListFilter] = [],
+        filters: Union[Iterable[ImageListFilter], Mapping[str, Any]] = (),
         all: bool = False,
     ) -> List[Image]:
         """Returns the list of Docker images present on the machine.
@@ -445,21 +445,14 @@ def list(
         # Returns
             A `List[python_on_whales.Image]` object.
         """
-        # previously the signature was
-        # def list(self,filters: Dict[str, str] = {}) -> List[Image]:
-        # so to avoid breakages when people used positional arguments, we can check the types and send a warning
-        if isinstance(repository_or_tag, dict):
-            # after a while, we can convert that to an error. No hurry though.
+        if isinstance(filters, Mapping):
+            filters = filters.items()
             warnings.warn(
-                f"You are calling docker.image.list({repository_or_tag}) with the filter as the first argument."
-                f"Since Python-on-whales v0.51.0, the first argument has be changed to `repository_or_tag`."
-                f"To fix this warning, please add the filters keyword argument, "
-                f"like so: docker.image.list(filters={repository_or_tag}) ",
+                "Passing filters as a mapping is deprecated, replace with an "
+                "iterable of tuples instead, as so:\n"
+                f"filters={list(filters)}",
                 DeprecationWarning,
             )
-            filters = repository_or_tag
-            repository_or_tag = None
-
         full_cmd = self.docker_cmd + [
             "image",
             "list",
@@ -478,7 +471,11 @@ def list(
 
         return [Image(self.client_config, x, is_immutable_id=True) for x in ids]
 
-    def prune(self, all: bool = False, filters: List[ImageListFilter] = []) -> str:
+    def prune(
+        self,
+        all: bool = False,
+        filters: Union[Iterable[ImageListFilter], Mapping[str, Any]] = (),
+    ) -> str:
         """Remove unused images
 
         Parameters:
@@ -488,6 +485,14 @@ def prune(self, all: bool = False, filters: List[ImageListFilter] = []) -> str:
         Returns:
             The output of the CLI (the layers removed).
         """
+        if isinstance(filters, Mapping):
+            filters = filters.items()
+            warnings.warn(
+                "Passing filters as a mapping is deprecated, replace with an "
+                "iterable of tuples instead, as so:\n"
+                f"filters={list(filters)}",
+                DeprecationWarning,
+            )
         full_cmd = self.docker_cmd + ["image", "prune", "--force"]
         full_cmd.add_flag("--all", all)
         full_cmd.add_args_iterable("--filter", (f"{f[0]}={f[1]}" for f in filters))

python_on_whales/components/network/cli_wrapper.py

@@ -1,8 +1,21 @@
 from __future__ import annotations
 
 import json
+import warnings
 from datetime import datetime
-from typing import Any, Dict, List, Literal, Optional, Tuple, TypeAlias, Union, overload
+from typing import (
+    Any,
+    Dict,
+    Iterable,
+    List,
+    Literal,
+    Mapping,
+    Optional,
+    Tuple,
+    TypeAlias,
+    Union,
+    overload,
+)
 
 import python_on_whales.components.container.cli_wrapper
 from python_on_whales.client_config import (
@@ -265,27 +278,47 @@ def inspect(self, x: Union[str, List[str]]) -> Union[Network, List[Network]]:
         else:
             return [Network(self.client_config, reference) for reference in x]
 
-    def list(self, filters: List[NetworkListFilter] = []) -> List[Network]:
+    def list(
+        self, filters: Union[Iterable[NetworkListFilter], Mapping[str, Any]] = ()
+    ) -> List[Network]:
         """List all the networks available.
 
         Parameters:
-            filters: Filters as strings or list of strings.
+            filters: Filters to apply when listing networks.
 
         # Returns
             List of `python_on_whales.Network`.
         """
+        if isinstance(filters, Mapping):
+            filters = filters.items()
+            warnings.warn(
+                "Passing filters as a mapping is deprecated, replace with an "
+                "iterable of tuples instead, as so:\n"
+                f"filters={list(filters)}",
+                DeprecationWarning,
+            )
         full_cmd = self.docker_cmd + ["network", "ls", "--no-trunc", "--quiet"]
         full_cmd.add_args_iterable("--filter", (f"{f[0]}={f[1]}" for f in filters))
 
         ids = run(full_cmd).splitlines()
         return [Network(self.client_config, id_, is_immutable_id=True) for id_ in ids]
 
-    def prune(self, filters: List[NetworkListFilter] = []) -> None:
+    def prune(
+        self, filters: Union[Iterable[NetworkListFilter], Mapping[str, Any]] = ()
+    ) -> None:
         """Remove Docker networks which are not used by any containers.
 
         Parameters:
             filters: Filters to apply when finding networks to prune.
         """
+        if isinstance(filters, Mapping):
+            filters = filters.items()
+            warnings.warn(
+                "Passing filters as a mapping is deprecated, replace with an "
+                "iterable of tuples instead, as so:\n"
+                f"filters={list(filters)}",
+                DeprecationWarning,
+            )
         full_cmd = self.docker_cmd + ["network", "prune", "--force"]
         full_cmd.add_args_iterable("--filter", (f"{f[0]}={f[1]}" for f in filters))
         run(full_cmd)

python_on_whales/components/pod/cli_wrapper.py

@@ -1,6 +1,7 @@
 from __future__ import annotations
 
 import json
+import warnings
 from datetime import datetime, timedelta
 from typing import (
     Any,
@@ -33,7 +34,6 @@
 from python_on_whales.utils import (
     ValidPath,
     ValidPortMapping,
-    format_mapping_for_cli,
     format_port_arg,
     format_signal_arg,
     format_time_arg,
@@ -515,7 +515,9 @@ def kill(
         full_cmd.extend([str(p) for p in pods])
         run(full_cmd)
 
-    def list(self, *, filters: List[PodListFilter] = []) -> List[Pod]:
+    def list(
+        self, *, filters: Union[Iterable[PodListFilter], Mapping[str, Any]] = ()
+    ) -> List[Pod]:
         """List the pods on the host.
 
         Parameters:
@@ -524,6 +526,14 @@ def list(self, *, filters: List[PodListFilter] = []) -> List[Pod]:
         # Returns
             A `List[python_on_whales.Pod]`
         """
+        if isinstance(filters, Mapping):
+            filters = filters.items()
+            warnings.warn(
+                "Passing filters as a mapping is deprecated, replace with an "
+                "iterable of tuples instead, as so:\n"
+                f"filters={list(filters)}",
+                DeprecationWarning,
+            )
         full_cmd = self.docker_cmd + ["pod", "ps", "-q", "--no-trunc"]
         full_cmd.add_args_iterable("--filter", (f"{f[0]}={f[1]}" for f in filters))
 

python_on_whales/components/secret/cli_wrapper.py

@@ -1,5 +1,17 @@
 import json
-from typing import Any, Dict, List, Literal, Optional, Tuple, TypeAlias, Union
+import warnings
+from typing import (
+    Any,
+    Dict,
+    Iterable,
+    List,
+    Literal,
+    Mapping,
+    Optional,
+    Tuple,
+    TypeAlias,
+    Union,
+)
 
 from python_on_whales.client_config import (
     ClientConfig,
@@ -87,8 +99,18 @@ def inspect(self, x: Union[str, List[str]]) -> Union[Secret, List[Secret]]:
         else:
             return Secret(self.client_config, x)
 
-    def list(self, filters: List[SecretListFilter] = []) -> List[Secret]:
+    def list(
+        self, filters: Union[Iterable[SecretListFilter], Mapping[str, Any]] = ()
+    ) -> List[Secret]:
         """Returns all secrets as a `List[python_on_whales.Secret]`."""
+        if isinstance(filters, Mapping):
+            filters = filters.items()
+            warnings.warn(
+                "Passing filters as a mapping is deprecated, replace with an "
+                "iterable of tuples instead, as so:\n"
+                f"filters={list(filters)}",
+                DeprecationWarning,
+            )
         full_cmd = self.docker_cmd + ["secret", "list", "--quiet"]
         full_cmd.add_args_iterable("--filter", (f"{f[0]}={f[1]}" for f in filters))
         ids = run(full_cmd).splitlines()

python_on_whales/components/service/cli_wrapper.py

@@ -1,8 +1,21 @@
 from __future__ import annotations
 
 import json
+import warnings
 from datetime import datetime, timedelta
-from typing import Any, Dict, List, Literal, Optional, Tuple, TypeAlias, Union, overload
+from typing import (
+    Any,
+    Dict,
+    Iterable,
+    List,
+    Literal,
+    Mapping,
+    Optional,
+    Tuple,
+    TypeAlias,
+    Union,
+    overload,
+)
 
 import python_on_whales.components.task.cli_wrapper
 from python_on_whales.client_config import (
@@ -359,7 +372,9 @@ def logs(
         else:
             return "".join(x[1].decode() for x in iterator)
 
-    def list(self, filters: List[ServiceListFilter] = []) -> List[Service]:
+    def list(
+        self, filters: Union[Iterable[ServiceListFilter], Mapping[str, Any]] = ()
+    ) -> List[Service]:
         """Returns the list of services
 
         Parameters:
@@ -369,6 +384,14 @@ def list(self, filters: List[ServiceListFilter] = []) -> List[Service]:
         # Returns
             A `List[python_on_whales.Services]`
         """
+        if isinstance(filters, Mapping):
+            filters = filters.items()
+            warnings.warn(
+                "Passing filters as a mapping is deprecated, replace with an "
+                "iterable of tuples instead, as so:\n"
+                f"filters={list(filters)}",
+                DeprecationWarning,
+            )
         full_cmd = self.docker_cmd + ["service", "list", "--quiet"]
         full_cmd.add_args_iterable("--filter", (f"{f[0]}={f[1]}" for f in filters))