✨ Better error message when using command as a string

python_on_whales/components/container/cli_wrapper.py

@@ -830,6 +830,23 @@ def execute(
         # Raises
             `python_on_whales.exceptions.NoSuchContainer` if the container does not exists.
         """
+        if not isinstance(command, list):
+            error_message = (
+                "When calling docker.execute(), the second argument ('command') "
+                "should be a list. "
+                "Here are some examples:"
+                "docker.execute('somecontainer', ['ls']), "
+                "docker.execute('somecontainer', ['cat', '/some/file.txt'])"
+            )
+            if isinstance(command, str):
+                # boy this is the most common error in the world
+                if isinstance(container, str):
+                    container = self.inspect(container)
+                error_message += (
+                    f" In your case, command should not be a string. "
+                    f"You can try docker.execute('{container.name}', {command.split()}, ...)."
+                )
+            raise TypeError(error_message)
         full_cmd = self.docker_cmd + ["exec"]
 
         full_cmd.add_flag("--detach", detach)
@@ -1432,6 +1449,21 @@ def run(
             The container output as a string if detach is `False` (the default),
             and a `python_on_whales.Container` if detach is `True`.
         """
+        if not isinstance(command, list):
+            error_message = (
+                "When calling docker.run(), the second argument ('command') "
+                "should be a list. "
+                "Here are some examples:"
+                "docker.run('ubuntu', ['ls']), "
+                "docker.run('ubuntu', ['cat', '/some/file.txt'])"
+            )
+            if isinstance(command, str):
+                # boy this is the most common error in the world
+                error_message += (
+                    f" In your case, command should not be a string. "
+                    f"You can try docker.run('{image}', {command.split()}, ...)."
+                )
+            raise TypeError(error_message)
 
         image_cli = python_on_whales.components.image.cli_wrapper.ImageCLI(
             self.client_config

tests/python_on_whales/components/test_container.py

@@ -31,6 +31,13 @@ def test_simple_command():
     assert "Hello from Docker!" in output
 
 
+def test_simple_mistake_on_run():
+    with pytest.raises(TypeError) as err:
+        docker.run("ubuntu", "ls")
+    assert "docker.run('ubuntu', ['ls'], ...)" in str(err)
+    docker.run("ubuntu", ["ls"], remove=True)
+
+
 def test_simple_command_create_start():
     output = docker.container.create("hello-world", remove=True).start(attach=True)
     assert "Hello from Docker!" in output
@@ -324,6 +331,17 @@ def test_execute():
     docker.kill(my_container)
 
 
+def test_execute_simple_mistake():
+    with docker.run(
+        "busybox:1", ["sleep", "infinity"], detach=True, remove=True
+    ) as my_container:
+        with pytest.raises(TypeError) as err:
+            docker.execute(my_container, "echo dodo")
+        assert f"docker.execute('{my_container.name}', ['echo', 'dodo'], ...)" in str(
+            err
+        )
+
+
 def test_execute_stream():
     my_container = docker.run(
         "busybox:1", ["sleep", "infinity"], detach=True, remove=True