Merge branch 'main' into typed_docker_client

Author: Tranquility2

.github/.release-please-manifest.json

@@ -1,3 +1,3 @@
 {
-    ".": "4.9.2"
+    ".": "4.10.0"
 }

.readthedocs.yml

@@ -14,6 +14,6 @@ build:
   # https://github.com/readthedocs/readthedocs.org/issues/4912#issuecomment-1143587902s
   jobs:
     post_install:
-      - pip install poetry==1.7.1  # match version from poetry.lock
+      - pip install poetry==2.1.2  # match version from poetry.lock
       - poetry config virtualenvs.create false
       - poetry install --all-extras

CHANGELOG.md

@@ -1,5 +1,18 @@
 # Changelog
 
+## [4.10.0](https://github.com/testcontainers/testcontainers-python/compare/testcontainers-v4.9.2...testcontainers-v4.10.0) (2025-04-02)
+
+
+### Features
+
+* Add SocatContainer ([#795](https://github.com/testcontainers/testcontainers-python/issues/795)) ([2f9139c](https://github.com/testcontainers/testcontainers-python/commit/2f9139ca3ea9fba36325373b63635a5f539a3003))
+
+
+### Bug Fixes
+
+* **ollama:** make device request a list ([#799](https://github.com/testcontainers/testcontainers-python/issues/799)) ([9497a45](https://github.com/testcontainers/testcontainers-python/commit/9497a45c39d13761aa3dd30dd5605676cbbe4b46))
+* **security:** Update track-modules job  ([#787](https://github.com/testcontainers/testcontainers-python/issues/787)) ([f979525](https://github.com/testcontainers/testcontainers-python/commit/f97952505eba089f9cbbc979f8091dafbf520669))
+
 ## [4.9.2](https://github.com/testcontainers/testcontainers-python/compare/testcontainers-v4.9.1...testcontainers-v4.9.2) (2025-02-26)
 
 

core/testcontainers/compose/compose.py

@@ -139,6 +139,8 @@ class DockerCompose:
             The list of services to use from this DockerCompose.
         client_args:
             arguments to pass to docker.from_env()
+        docker_command_path:
+            The docker compose command to run.
 
     Example:
 
@@ -195,7 +197,7 @@ def docker_compose_command(self) -> list[str]:
 
     @cached_property
     def compose_command_property(self) -> list[str]:
-        docker_compose_cmd = [self.docker_command_path or "docker", "compose"]
+        docker_compose_cmd = [self.docker_command_path] if self.docker_command_path else ["docker", "compose"]
         if self.compose_file_name:
             for file in self.compose_file_name:
                 docker_compose_cmd += ["-f", file]

core/testcontainers/core/config.py

@@ -6,6 +6,8 @@
 from pathlib import Path
 from typing import Optional, Union
 
+import docker
+
 
 class ConnectionMode(Enum):
     bridge_ip = "bridge_ip"
@@ -24,14 +26,32 @@ def use_mapped_port(self) -> bool:
         return True
 
 
+def get_docker_socket() -> str:
+    """
+    Determine the docker socket, prefer value given by env variable
+
+    Using the docker api ensure we handle rootless docker properly
+    """
+    if socket_path := environ.get("TESTCONTAINERS_DOCKER_SOCKET_OVERRIDE"):
+        return socket_path
+
+    client = docker.from_env()
+    try:
+        socket_path = client.api.get_adapter(client.api.base_url).socket_path
+        # return the normalized path as string
+        return str(Path(socket_path).absolute())
+    except AttributeError:
+        return "/var/run/docker.sock"
+
+
 MAX_TRIES = int(environ.get("TC_MAX_TRIES", 120))
 SLEEP_TIME = int(environ.get("TC_POOLING_INTERVAL", 1))
 TIMEOUT = MAX_TRIES * SLEEP_TIME
 
 RYUK_IMAGE: str = environ.get("RYUK_CONTAINER_IMAGE", "testcontainers/ryuk:0.8.1")
 RYUK_PRIVILEGED: bool = environ.get("TESTCONTAINERS_RYUK_PRIVILEGED", "false") == "true"
 RYUK_DISABLED: bool = environ.get("TESTCONTAINERS_RYUK_DISABLED", "false") == "true"
-RYUK_DOCKER_SOCKET: str = environ.get("TESTCONTAINERS_DOCKER_SOCKET_OVERRIDE", "/var/run/docker.sock")
+RYUK_DOCKER_SOCKET: str = get_docker_socket()
 RYUK_RECONNECTION_TIMEOUT: str = environ.get("RYUK_RECONNECTION_TIMEOUT", "10s")
 TC_HOST_OVERRIDE: Optional[str] = environ.get("TC_HOST", environ.get("TESTCONTAINERS_HOST_OVERRIDE"))
 
@@ -86,7 +106,7 @@ class TestcontainersConfiguration:
     tc_properties: dict[str, str] = field(default_factory=read_tc_properties)
     _docker_auth_config: Optional[str] = field(default_factory=lambda: environ.get("DOCKER_AUTH_CONFIG"))
     tc_host_override: Optional[str] = TC_HOST_OVERRIDE
-    connection_mode_override: Optional[ConnectionMode] = None
+    connection_mode_override: Optional[ConnectionMode] = field(default_factory=get_user_overwritten_connection_mode)
 
     """
     https://github.com/testcontainers/testcontainers-go/blob/dd76d1e39c654433a3d80429690d07abcec04424/docker.go#L644

core/testcontainers/core/container.py

@@ -155,7 +155,7 @@ def get_exposed_port(self, port: int) -> int:
             return self.get_docker_client().port(self._container.id, port)
         return port
 
-    def with_command(self, command: str) -> Self:
+    def with_command(self, command: Union[str, list[str]]) -> Self:
         self._command = command
         return self
 

core/testcontainers/core/image.py

@@ -23,10 +23,13 @@ class DockerImage:
             >>> with DockerImage(path="./core/tests/image_fixtures/sample/", tag="test-image") as image:
             ...    logs = image.get_logs()
 
-    :param tag: Tag for the image to be built (default: None)
     :param path: Path to the build context
+    :param docker_client_kw: Keyword arguments to pass to the DockerClient
+    :param tag: Tag for the image to be built (default: None)
+    :param clean_up: Remove the image after exiting the context (default: True)
     :param dockerfile_path: Path to the Dockerfile within the build context path (default: Dockerfile)
     :param no_cache: Bypass build cache; CLI's --no-cache
+    :param kwargs: Additional keyword arguments to pass to the underlying docker-py
     """
 
     def __init__(
@@ -49,11 +52,11 @@ def __init__(
         self._dockerfile_path = dockerfile_path
         self._no_cache = no_cache
 
-    def build(self, **kwargs) -> Self:
+    def build(self) -> Self:
         logger.info(f"Building image from {self.path}")
         docker_client = self.get_docker_client()
         self._image, self._logs = docker_client.build(
-            path=str(self.path), tag=self.tag, dockerfile=self._dockerfile_path, nocache=self._no_cache, **kwargs
+            path=str(self.path), tag=self.tag, dockerfile=self._dockerfile_path, nocache=self._no_cache, **self._kwargs
         )
         logger.info(f"Built image {self.short_id} with tag {self.tag}")
         return self

core/testcontainers/socat/__init__.py

@@ -0,0 +1,2 @@
+# flake8: noqa
+from testcontainers.socat.socat import SocatContainer

core/testcontainers/socat/socat.py

@@ -0,0 +1,88 @@
+#
+#    Licensed under the Apache License, Version 2.0 (the "License"); you may
+#    not use this file except in compliance with the License. You may obtain
+#    a copy of the License at
+#
+#         http://www.apache.org/licenses/LICENSE-2.0
+#
+#    Unless required by applicable law or agreed to in writing, software
+#    distributed under the License is distributed on an "AS IS" BASIS, WITHOUT
+#    WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. See the
+#    License for the specific language governing permissions and limitations
+#    under the License.
+import random
+import socket
+import string
+from typing import Optional
+
+from testcontainers.core.container import DockerContainer
+from testcontainers.core.waiting_utils import wait_container_is_ready
+
+
+class SocatContainer(DockerContainer):
+    """
+    A container that uses socat to forward TCP connections.
+    """
+
+    def __init__(
+        self,
+        image: str = "alpine/socat:1.7.4.3-r0",
+        **kwargs,
+    ) -> None:
+        """
+        Initialize a new SocatContainer with the given image.
+
+        Args:
+            image: The Docker image to use. Defaults to "alpine/socat:1.7.4.3-r0".
+            **kwargs: Additional keyword arguments to pass to the DockerContainer constructor.
+        """
+        # Dictionary to store targets (port -> host:port mappings)
+        self.targets: dict[int, str] = {}
+
+        kwargs["entrypoint"] = "/bin/sh"
+
+        random_suffix = "".join(random.choices(string.ascii_lowercase + string.digits, k=8))
+        self.with_name(f"testcontainers-socat-{random_suffix}")
+
+        super().__init__(image=image, **kwargs)
+
+    def with_target(self, exposed_port: int, host: str, internal_port: Optional[int] = None) -> "SocatContainer":
+        """
+        Add a target to forward connections from the exposed port to the given host and port.
+
+        Args:
+            exposed_port: The port to expose on the container.
+            host: The host to forward connections to.
+            internal_port: The port on the host to forward connections to. Defaults to the exposed_port if not provided.
+
+        Returns:
+            Self: The container instance for chaining.
+        """
+        if internal_port is None:
+            internal_port = exposed_port
+
+        self.with_exposed_ports(exposed_port)
+        self.targets[exposed_port] = f"{host}:{internal_port}"
+        return self
+
+    def _configure(self) -> None:
+        if not self.targets:
+            return
+
+        socat_commands = []
+        for port, target in self.targets.items():
+            socat_commands.append(f"socat TCP-LISTEN:{port},fork,reuseaddr TCP:{target}")
+
+        command = " & ".join(socat_commands)
+
+        self.with_command(f'-c "{command}"')
+
+    def start(self) -> "SocatContainer":
+        super().start()
+        self._connect()
+        return self
+
+    @wait_container_is_ready(OSError)
+    def _connect(self) -> None:
+        with socket.socket(socket.AF_INET, socket.SOCK_STREAM) as s:
+            s.connect((self.get_container_host_ip(), int(self.get_exposed_port(next(iter(self.ports))))))

core/tests/test_config.py

@@ -3,14 +3,17 @@
 from testcontainers.core.config import (
     TestcontainersConfiguration as TCC,
     TC_FILE,
+    TestcontainersConfiguration,
     get_user_overwritten_connection_mode,
     ConnectionMode,
+    get_docker_socket,
 )
 
 from pytest import MonkeyPatch, mark, LogCaptureFixture
 
 import logging
 import tempfile
+from unittest.mock import Mock
 
 
 def test_read_tc_properties(monkeypatch: MonkeyPatch) -> None:
@@ -79,8 +82,67 @@ def test_invalid_connection_mode(monkeypatch: pytest.MonkeyPatch) -> None:
 def test_valid_connection_mode(monkeypatch: pytest.MonkeyPatch, mode: str, use_mapped: bool) -> None:
     monkeypatch.setenv("TESTCONTAINERS_CONNECTION_MODE", mode)
     assert get_user_overwritten_connection_mode().use_mapped_port is use_mapped
+    assert TestcontainersConfiguration().connection_mode_override.use_mapped_port is use_mapped
 
 
 def test_no_connection_mode_given(monkeypatch: pytest.MonkeyPatch) -> None:
     monkeypatch.delenv("TESTCONTAINERS_CONNECTION_MODE", raising=False)
     assert get_user_overwritten_connection_mode() is None
+
+
+def test_get_docker_socket_uses_env(monkeypatch: pytest.MonkeyPatch) -> None:
+    """
+    If TESTCONTAINERS_DOCKER_SOCKET_OVERRIDE env var is given prefer it
+    """
+    monkeypatch.setenv("TESTCONTAINERS_DOCKER_SOCKET_OVERRIDE", "/var/test.socket")
+    assert get_docker_socket() == "/var/test.socket"
+
+
+@pytest.fixture
+def mock_docker_client_connections(monkeypatch: pytest.MonkeyPatch) -> None:
+    """
+    Ensure the docker client does not make any actual network calls
+    """
+    from docker.transport.sshconn import SSHHTTPAdapter
+    from docker.api.client import APIClient
+
+    # ensure that no actual connection is tried
+    monkeypatch.setattr(SSHHTTPAdapter, "_connect", Mock())
+    monkeypatch.setattr(SSHHTTPAdapter, "_create_paramiko_client", Mock())
+    monkeypatch.setattr(APIClient, "_retrieve_server_version", Mock(return_value="1.47"))
+
+
+@pytest.mark.usefixtures("mock_docker_client_connections")
+def test_get_docker_host_default(monkeypatch: pytest.MonkeyPatch) -> None:
+    """
+    If non socket docker-host is given return default
+
+    Still ryuk will properly still not work but this is the historical default
+
+    """
+    monkeypatch.delenv("TESTCONTAINERS_DOCKER_SOCKET_OVERRIDE", raising=False)
+    # Define Fake SSH Docker client
+    monkeypatch.setenv("DOCKER_HOST", "ssh://remote_host")
+    assert get_docker_socket() == "/var/run/docker.sock"
+
+
+@pytest.mark.usefixtures("mock_docker_client_connections")
+def test_get_docker_host_non_root(monkeypatch: pytest.MonkeyPatch) -> None:
+    """
+    Use the socket determined by the Docker API Adapter
+    """
+    monkeypatch.delenv("TESTCONTAINERS_DOCKER_SOCKET_OVERRIDE", raising=False)
+    # Define a Non-Root like Docker Client
+    monkeypatch.setenv("DOCKER_HOST", "unix://var/run/user/1000/docker.sock")
+    assert get_docker_socket() == "/var/run/user/1000/docker.sock"
+
+
+@pytest.mark.usefixtures("mock_docker_client_connections")
+def test_get_docker_host_root(monkeypatch: pytest.MonkeyPatch) -> None:
+    """
+    Use the socket determined by the Docker API Adapter
+    """
+    monkeypatch.delenv("TESTCONTAINERS_DOCKER_SOCKET_OVERRIDE", raising=False)
+    # Define a Root like Docker Client
+    monkeypatch.setenv("DOCKER_HOST", "unix://")
+    assert get_docker_socket() == "/var/run/docker.sock"

core/tests/test_image.py

@@ -64,3 +64,24 @@ def test_docker_image_with_custom_dockerfile_path(dockerfile_path: Optional[Path
             with DockerContainer(str(image)) as container:
                 assert container._container.image.short_id.endswith(image_short_id), "Image ID mismatch"
                 assert container.get_logs() == (("Hello world!\n").encode(), b""), "Container logs mismatch"
+
+
+def test_docker_image_with_kwargs():
+    with tempfile.TemporaryDirectory() as temp_directory:
+        with open(f"{temp_directory}/Dockerfile", "w") as f:
+            f.write(
+                f"""
+                FROM alpine:latest
+                ARG TEST_ARG
+                ENV TEST_ARG $TEST_ARG
+                CMD echo $TEST_ARG
+                """
+            )
+        with DockerImage(
+            path=temp_directory, tag="test", clean_up=True, no_cache=True, buildargs={"TEST_ARG": "new_arg"}
+        ) as image:
+            image_short_id = image.short_id
+            assert image.get_wrapped_image() is not None
+            with DockerContainer(str(image)) as container:
+                assert container._container.image.short_id.endswith(image_short_id), "Image ID mismatch"
+                assert container.get_logs() == (("new_arg\n").encode(), b""), "Container logs mismatch"

core/tests/test_socat.py

@@ -0,0 +1,22 @@
+import httpx
+import pytest
+from testcontainers.core.container import DockerContainer
+from testcontainers.core.network import Network
+from testcontainers.socat.socat import SocatContainer
+
+
+def test_socat_with_helloworld():
+    with (
+        Network() as network,
+        DockerContainer("testcontainers/helloworld:1.2.0")
+        .with_exposed_ports(8080)
+        .with_network(network)
+        .with_network_aliases("helloworld"),
+        SocatContainer().with_network(network).with_target(8080, "helloworld") as socat,
+    ):
+        socat_url = f"http://{socat.get_container_host_ip()}:{socat.get_exposed_port(8080)}"
+
+        response = httpx.get(f"{socat_url}/ping")
+
+        assert response.status_code == 200
+        assert response.content == b"PONG"

modules/ollama/testcontainers/ollama/__init__.py

@@ -101,7 +101,7 @@ def __init__(
     def _check_and_add_gpu_capabilities(self):
         info = self.get_docker_client().client.info()
         if "nvidia" in info["Runtimes"]:
-            self._kwargs = {**self._kwargs, "device_requests": DeviceRequest(count=-1, capabilities=[["gpu"]])}
+            self._kwargs = {**self._kwargs, "device_requests": [DeviceRequest(count=-1, capabilities=[["gpu"]])]}
 
     def start(self) -> "OllamaContainer":
         """