feat: support with_copy_to (#976)

This PR supports copying files into the container before startup time:

```python
DockerContainer("alpine")
    .with_command(["cat", "/tmp/copied.txt"])
    .with_copy_into_container(src, "/tmp/copied.txt")
```

To support this, I had to change how the container is started: `run` is
not longer used, but instead `create` and `start` are used now, in order
to be able to make the `copy` before the container is actually running.

Inspired by testcontainers/testcontainers-rs#730
where I did exactly the same feature for the rust implementation of
testcontainers :)

----

No tests are failing

```bash
> uv run pytest -v core/tests
...
======================================= 316 passed, 1 skipped in 160.87s (0:02:40) ========================================
```

Co-authored-by: David Ankin <daveankin@gmail.com>

Author: guenhter

core/testcontainers/core/container.py

@@ -204,10 +204,9 @@ def start(self) -> Self:
             else {}
         )
 
-        self._container = docker_client.run(
+        self._container = docker_client.create(
             self.image,
             command=self._command,
-            detach=True,
             environment=self.env,
             ports=cast("dict[int, Optional[int]]", self.ports),
             name=self._name,
@@ -216,14 +215,16 @@ def start(self) -> Self:
             **{**network_kwargs, **self._kwargs},
         )
 
+        for t in self._transferable_specs:
+            self._transfer_into_container(*t)
+
+        docker_client.start(self._container)
+
         if self._wait_strategy is not None:
             self._wait_strategy.wait_until_ready(self)
 
         logger.info("Container started: %s", self._container.short_id)
 
-        for t in self._transferable_specs:
-            self._transfer_into_container(*t)
-
         return self
 
     def stop(self, force: bool = True, delete_volume: bool = True) -> None:
@@ -330,6 +331,13 @@ def exec(self, command: Union[str, list[str]]) -> ExecResult:
             raise ContainerStartException("Container should be started before executing a command")
         return self._container.exec_run(command)
 
+    def wait(self) -> int:
+        """Wait for the container to stop and return its exit code."""
+        if not self._container:
+            raise ContainerStartException("Container should be started before waiting")
+        result = self._container.wait()
+        return int(result["StatusCode"])
+
     def get_container_info(self) -> Optional[ContainerInspectInfo]:
         """Get container information via docker inspect (lazy loaded).
 

core/testcontainers/core/docker_client.py

@@ -118,6 +118,43 @@ def run(
         )
         return container
 
+    @_wrapped_container_collection
+    def create(
+        self,
+        image: str,
+        command: Optional[Union[str, list[str]]] = None,
+        environment: Optional[dict[str, str]] = None,
+        ports: Optional[dict[int, Optional[int]]] = None,
+        labels: Optional[dict[str, str]] = None,
+        **kwargs: Any,
+    ) -> Container:
+        """Create a container without starting it, pulling the image first if not present locally."""
+        if "network" not in kwargs and not get_docker_host():
+            host_network = self.find_host_network()
+            if host_network:
+                kwargs["network"] = host_network
+
+        try:
+            # This is more or less a replication of what the self.client.containers.start does internally
+            self.client.images.get(image)
+        except docker.errors.ImageNotFound:
+            self.client.images.pull(image)
+
+        container = self.client.containers.create(
+            image,
+            command=command,
+            environment=environment,
+            ports=ports,
+            labels=create_labels(image, labels),
+            **kwargs,
+        )
+        return container
+
+    @_wrapped_container_collection
+    def start(self, container: Container) -> None:
+        """Start a previously created container."""
+        container.start()
+
     @_wrapped_image_collection
     def build(
         self, path: str, tag: Optional[str], rm: bool = True, **kwargs: Any

core/tests/test_transferable.py

@@ -104,6 +104,19 @@ def test_copy_into_container_at_startup(transferable: Transferable):
     assert result.output == b"hello world"
 
 
+def test_copy_into_startup_file(transferable: Transferable):
+    destination_in_container = "/tmp/my_file"
+
+    container = DockerContainer("bash", command=f"cat {destination_in_container}")
+    container.with_copy_into_container(transferable, destination_in_container)
+
+    with container:
+        exit_code = container.wait()
+        stdout, _ = container.get_logs()
+        assert exit_code == 0
+        assert stdout.decode() == "hello world"
+
+
 def test_copy_into_container_via_initializer(transferable: Transferable):
     destination_in_container = "/tmp/my_file"
     transferables: list[TransferSpec] = [(transferable, destination_in_container, 0o644)]