Merge branch 'main' into typed_version

Author: Tranquility2

.github/.release-please-manifest.json

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

.github/CONTRIBUTING.md

@@ -33,13 +33,13 @@ You need to have the following tools available to you:
 - Run `make install` to get `poetry` to install all dependencies and set up `pre-commit`
   - **Recommended**: Run `make` or `make help` to see other commands available to you.
 - After this, you should have a working virtual environment and proceed with writing code with your favourite IDE
-- **TIP**: You can run `make core/tests` or `make module/<my-module>/tests` to run the tests specifically for that to speed up feedback cycles
+- **TIP**: You can run `make core/tests` or `make modules/<my-module>/tests` to run the tests specifically for that to speed up feedback cycles
 - You can also run `make lint` to run the `pre-commit` for the entire codebase.
 
 
 ## Adding new containers
 
-We have an [issue template](.github/ISSUE_TEMPLATE/new-container.md) for adding new containers, please refer to that for more information.
+We have an [issue template](./ISSUE_TEMPLATE/new-container.md) for adding new containers, please refer to that for more information.
 Once you've talked to the maintainers (we do our best to reply!) then you can proceed with contributing the new container.
 
 > [!WARNING]

.github/workflows/ci-community.yml

@@ -19,20 +19,20 @@ jobs:
       - name: Checkout contents
         uses: actions/checkout@v4
         with:
-          fetch-depth: 0  # recommended by tj-actions/changed-files
+          fetch-depth: 0
       - name: Get changed files
         id: changed-files
-        uses: tj-actions/changed-files@v42
+        uses: dorny/paths-filter@de90cc6fb38fc0963ad72b210f1f284cd68cea36 # v3
         with:
-          path: "./modules"
-          diff_relative: true
-          dir_names: true
-          dir_names_exclude_current_dir: true
-          json: true
+          base: ${{ github.ref }}
+          list-files: 'json'
+          filters: |
+            modules:
+              - 'modules/**'
       - name: Compute modules from files
         id: compute-changes
         run: |
-          modules=$(echo "${{ steps.changed-files.outputs.all_changed_files }}" |  jq '.[] | split("/") | first' | jq -s -c '. | unique')
+          modules=$(echo "${{ toJson(steps.changed-files.outputs.modules_files) }}" | jq '.[] | split("/") | nth(1)' | jq -s -c '. | unique')
           echo "computed_modules=$modules"
           echo "computed_modules=$modules" >> $GITHUB_OUTPUT
     outputs:

.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,66 @@
 # 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)
+
+
+### Bug Fixes
+
+* Change env var disabling OpenSearch security plugin ([#773](https://github.com/testcontainers/testcontainers-python/issues/773)) ([2620d7f](https://github.com/testcontainers/testcontainers-python/commit/2620d7fb1157caa18c3bef4bf2f9b3b79cd2f075))
+* **core:** create_label test ([#771](https://github.com/testcontainers/testcontainers-python/issues/771)) ([7517297](https://github.com/testcontainers/testcontainers-python/commit/751729722a013b46f67c09b4318b1b3d92b98008))
+* **core:** multiple container start invocations with custom labels ([#769](https://github.com/testcontainers/testcontainers-python/issues/769)) ([3e783a8](https://github.com/testcontainers/testcontainers-python/commit/3e783a80aa11b9c87201404a895d922624f0d451))
+* **keycloak:** Fixed Keycloak testcontainer for latest version v26.1.0 ([#766](https://github.com/testcontainers/testcontainers-python/issues/766)) ([b1642e9](https://github.com/testcontainers/testcontainers-python/commit/b1642e98c4d349564c4365782d1b58c9810b719a))
+* **scylla:** scylla get cluster method ([#778](https://github.com/testcontainers/testcontainers-python/issues/778)) ([46913c1](https://github.com/testcontainers/testcontainers-python/commit/46913c18a8b6f37bf8dc193828148926b6fc56a8))
+
+
+### Documentation
+
+* Fixed typo in CONTRIBUTING.md ([#767](https://github.com/testcontainers/testcontainers-python/issues/767)) ([f0bb0f5](https://github.com/testcontainers/testcontainers-python/commit/f0bb0f54bea83885698bd137e24c397498709362))
+
+## [4.9.1](https://github.com/testcontainers/testcontainers-python/compare/testcontainers-v4.9.0...testcontainers-v4.9.1) (2025-01-21)
+
+
+### Bug Fixes
+
+* milvus healthcheck: use correct requests errors ([#759](https://github.com/testcontainers/testcontainers-python/issues/759)) ([78b137c](https://github.com/testcontainers/testcontainers-python/commit/78b137cfe53fc81eb8d5d858e98610fb6a8792ad))
+* **mysql:** add dialect parameter instead of hardcoded mysql dialect ([#739](https://github.com/testcontainers/testcontainers-python/issues/739)) ([8d77bd3](https://github.com/testcontainers/testcontainers-python/commit/8d77bd3541e1c5e73c7ed5d5bd3c0d7bb617f5c0))
+* **tests:** replace dind-test direct docker usage with sdk ([#750](https://github.com/testcontainers/testcontainers-python/issues/750)) ([ace2a7d](https://github.com/testcontainers/testcontainers-python/commit/ace2a7d143fb80576ddc0859a9106aa8652f2356))
+
+## [4.9.0](https://github.com/testcontainers/testcontainers-python/compare/testcontainers-v4.8.2...testcontainers-v4.9.0) (2024-11-26)
+
+
+### Features
+
+* **compose:** support for setting profiles ([#738](https://github.com/testcontainers/testcontainers-python/issues/738)) ([3e00e71](https://github.com/testcontainers/testcontainers-python/commit/3e00e71da4d2b5e7fd30315468d4e54c86ba6150))
+* **core:** Support working with env files ([#737](https://github.com/testcontainers/testcontainers-python/issues/737)) ([932ee30](https://github.com/testcontainers/testcontainers-python/commit/932ee307955e3591a63f194aee8e2f6d8e2f6bf9))
+
+
+### Bug Fixes
+
+* allow running all tests ([#721](https://github.com/testcontainers/testcontainers-python/issues/721)) ([f958cf9](https://github.com/testcontainers/testcontainers-python/commit/f958cf9fe62a5f3ee2dc255713ec8b16de6a767d))
+* **core:** Avoid hanging upon bad docker host connection ([#742](https://github.com/testcontainers/testcontainers-python/issues/742)) ([4ced198](https://github.com/testcontainers/testcontainers-python/commit/4ced1983162914fe511a6e714f136b670e1dbdfb))
+* **core:** running testcontainer inside container ([#714](https://github.com/testcontainers/testcontainers-python/issues/714)) ([85a6666](https://github.com/testcontainers/testcontainers-python/commit/85a66667c23d76e87aecc6761bbb01429adb3dee))
+* **generic:** Also catch URLError waiting for ServerContainer ([#743](https://github.com/testcontainers/testcontainers-python/issues/743)) ([24e354f](https://github.com/testcontainers/testcontainers-python/commit/24e354f3bfa5912eaf7877da9442a885d7872f1a))
+* update wait_for_logs to not throw on 'created', and an optimization ([#719](https://github.com/testcontainers/testcontainers-python/issues/719)) ([271ca9a](https://github.com/testcontainers/testcontainers-python/commit/271ca9a0fef2e5f2b216457bfee44318e93990bf))
+* Vault health check ([#734](https://github.com/testcontainers/testcontainers-python/issues/734)) ([79434d6](https://github.com/testcontainers/testcontainers-python/commit/79434d6744b2918493884cf8fbf27aeadf78ecfd))
+
+
+### Documentation
+
+* Documentation fix for ServerContainer ([#671](https://github.com/testcontainers/testcontainers-python/issues/671)) ([0303d47](https://github.com/testcontainers/testcontainers-python/commit/0303d47d7173e1c4ec1a4f565efee9b2fe694928))
+
 ## [4.8.2](https://github.com/testcontainers/testcontainers-python/compare/testcontainers-v4.8.1...testcontainers-v4.8.2) (2024-09-27)
 
 

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:
 
@@ -171,6 +173,7 @@ class DockerCompose:
     env_file: Optional[str] = None
     services: Optional[list[str]] = None
     docker_command_path: Optional[str] = None
+    profiles: Optional[list[str]] = None
 
     def __post_init__(self):
         if isinstance(self.compose_file_name, str):
@@ -194,10 +197,12 @@ 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]
+        if self.profiles:
+            docker_compose_cmd += [item for profile in self.profiles for item in ["--profile", profile]]
         if self.env_file:
             docker_compose_cmd += ["--env-file", self.env_file]
         return docker_compose_cmd

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

@@ -1,16 +1,18 @@
 import contextlib
+from os import PathLike
 from socket import socket
 from typing import TYPE_CHECKING, Optional, Union
 
 import docker.errors
 from docker import version
 from docker.types import EndpointConfig
+from dotenv import dotenv_values
 from typing_extensions import Self, assert_never
 
 from testcontainers.core.config import ConnectionMode
 from testcontainers.core.config import testcontainers_config as c
 from testcontainers.core.docker_client import DockerClient
-from testcontainers.core.exceptions import ContainerStartException
+from testcontainers.core.exceptions import ContainerConnectException, ContainerStartException
 from testcontainers.core.labels import LABEL_SESSION_ID, SESSION_ID
 from testcontainers.core.network import Network
 from testcontainers.core.utils import is_arm, setup_logger
@@ -57,6 +59,12 @@ def with_env(self, key: str, value: str) -> Self:
         self.env[key] = value
         return self
 
+    def with_env_file(self, env_file: Union[str, PathLike]) -> Self:
+        env_values = dotenv_values(env_file)
+        for key, value in env_values.items():
+            self.with_env(key, value)
+        return self
+
     def with_bind_ports(self, container: int, host: Optional[int] = None) -> Self:
         self.ports[container] = host
         return self
@@ -147,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
 
@@ -220,15 +228,21 @@ def _create_instance(cls) -> "Reaper":
             .with_env("RYUK_RECONNECTION_TIMEOUT", c.ryuk_reconnection_timeout)
             .start()
         )
-        wait_for_logs(Reaper._container, r".* Started!")
+        wait_for_logs(Reaper._container, r".* Started!", timeout=20, raise_on_exit=True)
 
         container_host = Reaper._container.get_container_host_ip()
         container_port = int(Reaper._container.get_exposed_port(8080))
 
+        if not container_host or not container_port:
+            raise ContainerConnectException(
+                f"Could not obtain network details for {Reaper._container._container.id}. Host: {container_host} Port: {container_port}"
+            )
+
         last_connection_exception: Optional[Exception] = None
         for _ in range(50):
             try:
                 Reaper._socket = socket()
+                Reaper._socket.settimeout(1)
                 Reaper._socket.connect((container_host, container_port))
                 last_connection_exception = None
                 break

core/testcontainers/core/exceptions.py

@@ -16,6 +16,10 @@ class ContainerStartException(RuntimeError):
     pass
 
 
+class ContainerConnectException(RuntimeError):
+    pass
+
+
 class ContainerIsNotRunning(RuntimeError):
     pass
 

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/core/labels.py

@@ -21,12 +21,15 @@ def create_labels(image: str, labels: Optional[dict[str, str]]) -> dict[str, str
             if k.startswith(TESTCONTAINERS_NAMESPACE):
                 raise ValueError("The org.testcontainers namespace is reserved for internal use")
 
-    labels[LABEL_LANG] = "python"
-    labels[LABEL_TESTCONTAINERS] = "true"
-    labels[LABEL_VERSION] = importlib.metadata.version("testcontainers")
+    tc_labels = {
+        **labels,
+        LABEL_LANG: "python",
+        LABEL_TESTCONTAINERS: "true",
+        LABEL_VERSION: importlib.metadata.version("testcontainers"),
+    }
 
     if image == c.ryuk_image:
-        return labels
+        return tc_labels
 
-    labels[LABEL_SESSION_ID] = SESSION_ID
-    return labels
+    tc_labels[LABEL_SESSION_ID] = SESSION_ID
+    return tc_labels

core/testcontainers/socat/__init__.py

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