Merge branch 'main' into main

Author: Tranquility2

.github/.release-please-manifest.json

@@ -1,3 +1,3 @@
 {
-    ".": "4.12.0"
+    ".": "4.13.1"
 }

.github/workflows/ci-core.yml

@@ -14,7 +14,7 @@ jobs:
     strategy:
       fail-fast: false
       matrix:
-        python-version: ["3.9", "3.10", "3.11", "3.12"]
+        python-version: ["3.9", "3.11", "3.12", "3.13"]
     steps:
       - uses: actions/checkout@v4
       - name: Set up Python
@@ -24,7 +24,7 @@ jobs:
       - name: Install Python dependencies
         run: poetry install --all-extras
       - name: Run twine check
-        run: poetry build && poetry run twine check dist/*.tar.gz
+        run: rm -f LICENSE.txt && poetry build && poetry run twine check dist/*.tar.gz
       - name: Set up Docker
         uses: docker/setup-docker-action@v4
       - name: Run tests

CHANGELOG.md

@@ -1,5 +1,29 @@
 # Changelog
 
+## [4.13.1](https://github.com/testcontainers/testcontainers-python/compare/testcontainers-v4.13.0...testcontainers-v4.13.1) (2025-09-24)
+
+
+### Bug Fixes
+
+* **core:** Added 'compose' in compose_command_property ([#879](https://github.com/testcontainers/testcontainers-python/issues/879)) ([769b7b6](https://github.com/testcontainers/testcontainers-python/commit/769b7b688fe254cb8e38e05f453c4e3fe7999ad5))
+* **core:** make sure context manager exits ([#876](https://github.com/testcontainers/testcontainers-python/issues/876)) ([10089f6](https://github.com/testcontainers/testcontainers-python/commit/10089f6e2fe07e53cc47a69521e67a1bf3310065))
+
+## [4.13.0](https://github.com/testcontainers/testcontainers-python/compare/testcontainers-v4.12.0...testcontainers-v4.13.0) (2025-08-27)
+
+
+### Features
+
+* **azurite:** Enhance connection string generation for network and local access ([#859](https://github.com/testcontainers/testcontainers-python/issues/859)) ([b21e5e3](https://github.com/testcontainers/testcontainers-python/commit/b21e5e38075ddbd71fb4f97e843abc104dec6beb))
+* **core:** add enhanced wait strategies ([#855](https://github.com/testcontainers/testcontainers-python/issues/855)) ([60d21f8](https://github.com/testcontainers/testcontainers-python/commit/60d21f875f49f52e170b0714e8790080a6cb4c71))
+* **core:** DockerCompose: support list of env_files ([#847](https://github.com/testcontainers/testcontainers-python/issues/847)) ([fe206eb](https://github.com/testcontainers/testcontainers-python/commit/fe206eb48ee9e18623761926900bfc33a8a869a7))
+
+
+### Bug Fixes
+
+* assert-in-get_container_host_ip-before-start ([#862](https://github.com/testcontainers/testcontainers-python/issues/862)) ([fc4155e](https://github.com/testcontainers/testcontainers-python/commit/fc4155eb70509ba236fff771c2f8973667acb098))
+* **core:** improper reading of .testcontainers.properties ([#863](https://github.com/testcontainers/testcontainers-python/issues/863)) ([350f246](https://github.com/testcontainers/testcontainers-python/commit/350f246a3b6367d727046b8967a63d1c055cf324))
+* **core:** Make TC_POOLING_INTERVAL/sleep_time a float ([#839](https://github.com/testcontainers/testcontainers-python/issues/839)) ([a072f3f](https://github.com/testcontainers/testcontainers-python/commit/a072f3fad46b3b3e7c5bea6255f27b79826aaf5f))
+
 ## [4.12.0](https://github.com/testcontainers/testcontainers-python/compare/testcontainers-v4.11.0...testcontainers-v4.12.0) (2025-07-21)
 
 

conf.py

@@ -161,7 +161,7 @@
 
 intersphinx_mapping = {
     "python": ("https://docs.python.org/3", None),
-    "selenium": ("https://seleniumhq.github.io/selenium/docs/api/py/", None),
+    "selenium": ("https://www.selenium.dev/selenium/docs/api/py/", None),
     "typing_extensions": ("https://typing-extensions.readthedocs.io/en/latest/", None),
 }
 

core/README.rst

@@ -14,6 +14,8 @@ Testcontainers Core
 
 .. autoclass:: testcontainers.core.generic.DbContainer
 
+.. autoclass:: testcontainers.core.wait_strategies.WaitStrategy
+
 .. raw:: html
 
     <hr>

core/testcontainers/compose/compose.py

@@ -1,23 +1,24 @@
+import sys
 from dataclasses import asdict, dataclass, field, fields, is_dataclass
 from functools import cached_property
 from json import loads
-from logging import warning
+from logging import getLogger, warning
 from os import PathLike
 from platform import system
 from re import split
-from subprocess import CompletedProcess
+from subprocess import CalledProcessError, CompletedProcess
 from subprocess import run as subprocess_run
 from types import TracebackType
 from typing import Any, Callable, Literal, Optional, TypeVar, Union, cast
-from urllib.error import HTTPError, URLError
-from urllib.request import urlopen
 
 from testcontainers.core.exceptions import ContainerIsNotRunning, NoSuchPortExposed
-from testcontainers.core.waiting_utils import wait_container_is_ready
+from testcontainers.core.waiting_utils import WaitStrategy
 
 _IPT = TypeVar("_IPT")
 _WARNINGS = {"DOCKER_COMPOSE_GET_CONFIG": "get_config is experimental, see testcontainers/testcontainers-python#669"}
 
+logger = getLogger(__name__)
+
 
 def _ignore_properties(cls: type[_IPT], dict_: Any) -> _IPT:
     """omits extra fields like @JsonIgnoreProperties(ignoreUnknown = true)
@@ -35,8 +36,7 @@ def _ignore_properties(cls: type[_IPT], dict_: Any) -> _IPT:
 @dataclass
 class PublishedPortModel:
     """
-    Class that represents the response we get from compose when inquiring status
-    via `DockerCompose.get_running_containers()`.
+    Class that represents the response we get from compose when inquiring status via `DockerCompose.get_running_containers()`.
     """
 
     URL: Optional[str] = None
@@ -80,6 +80,7 @@ class ComposeContainer:
     Health: Optional[str] = None
     ExitCode: Optional[int] = None
     Publishers: list[PublishedPortModel] = field(default_factory=list)
+    _docker_compose: Optional["DockerCompose"] = field(default=None, init=False, repr=False)
 
     def __post_init__(self) -> None:
         if self.Publishers:
@@ -116,6 +117,41 @@ def _matches_protocol(prefer_ip_version: str, r: PublishedPortModel) -> bool:
         r_url = r.URL
         return (r_url is not None and ":" in r_url) is (prefer_ip_version == "IPv6")
 
+    # WaitStrategy compatibility methods
+    def get_container_host_ip(self) -> str:
+        """Get the host IP for the container."""
+        # Simplified implementation - wait strategies don't use this yet
+        return "127.0.0.1"
+
+    def get_exposed_port(self, port: int) -> int:
+        """Get the exposed port mapping for the given internal port."""
+        # Simplified implementation - wait strategies don't use this yet
+        return port
+
+    def get_logs(self) -> tuple[bytes, bytes]:
+        """Get container logs."""
+        if not self._docker_compose:
+            raise RuntimeError("DockerCompose reference not set on ComposeContainer")
+        if not self.Service:
+            raise RuntimeError("Service name not set on ComposeContainer")
+        stdout, stderr = self._docker_compose.get_logs(self.Service)
+        return stdout.encode(), stderr.encode()
+
+    def get_wrapped_container(self) -> "ComposeContainer":
+        """Get the underlying container object for compatibility."""
+        return self
+
+    def reload(self) -> None:
+        """Reload container information for compatibility with wait strategies."""
+        # ComposeContainer doesn't need explicit reloading as it's fetched fresh
+        # each time through get_container(), but we need this method for compatibility
+        pass
+
+    @property
+    def status(self) -> str:
+        """Get container status for compatibility with wait strategies."""
+        return self.State or "unknown"
+
 
 @dataclass
 class DockerCompose:
@@ -137,7 +173,7 @@ class DockerCompose:
             Wait for the services to be healthy
             (as per healthcheck definitions in the docker compose configuration)
         env_file:
-            Path to an '.env' file containing environment variables
+            Path(s) to an '.env' file containing environment variables
             to pass to docker compose.
         services:
             The list of services to use from this DockerCompose.
@@ -174,18 +210,25 @@ class DockerCompose:
     build: bool = False
     wait: bool = True
     keep_volumes: bool = False
-    env_file: Optional[str] = None
+    env_file: Optional[Union[str, list[str]]] = None
     services: Optional[list[str]] = None
     docker_command_path: Optional[str] = None
     profiles: Optional[list[str]] = None
+    _wait_strategies: Optional[dict[str, Any]] = field(default=None, init=False, repr=False)
 
     def __post_init__(self) -> None:
         if isinstance(self.compose_file_name, str):
             self.compose_file_name = [self.compose_file_name]
+        if isinstance(self.env_file, str):
+            self.env_file = [self.env_file]
 
     def __enter__(self) -> "DockerCompose":
-        self.start()
-        return self
+        try:
+            self.start()
+            return self
+        except:  # noqa: E722, RUF100
+            self.__exit__(*sys.exc_info())
+            raise
 
     def __exit__(
         self, exc_type: Optional[type[BaseException]], exc_val: Optional[BaseException], exc_tb: Optional[TracebackType]
@@ -203,16 +246,29 @@ def docker_compose_command(self) -> list[str]:
 
     @cached_property
     def compose_command_property(self) -> list[str]:
-        docker_compose_cmd = [self.docker_command_path] if self.docker_command_path else ["docker", "compose"]
+        docker_compose_cmd = (
+            [self.docker_command_path, "compose"] 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]
+            for env_file in self.env_file:
+                docker_compose_cmd += ["--env-file", env_file]
         return docker_compose_cmd
 
+    def waiting_for(self, strategies: dict[str, WaitStrategy]) -> "DockerCompose":
+        """
+        Set wait strategies for specific services.
+
+        Args:
+            strategies: Dictionary mapping service names to wait strategies
+        """
+        self._wait_strategies = strategies
+        return self
+
     def start(self) -> None:
         """
         Starts the docker compose environment.
@@ -241,6 +297,11 @@ def start(self) -> None:
 
         self._run_command(cmd=up_cmd)
 
+        if self._wait_strategies:
+            for service, strategy in self._wait_strategies.items():
+                container = self.get_container(service_name=service)
+                strategy.wait_until_ready(container)
+
     def stop(self, down: bool = True) -> None:
         """
         Stops the docker compose environment.
@@ -317,7 +378,7 @@ def get_containers(self, include_all: bool = False) -> list[ComposeContainer]:
         result = self._run_command(cmd=cmd)
         stdout = split(r"\r?\n", result.stdout.decode("utf-8"))
 
-        containers = []
+        containers: list[ComposeContainer] = []
         # one line per service in docker 25, single array for docker 24.0.2
         for line in stdout:
             if not line:
@@ -328,6 +389,10 @@ def get_containers(self, include_all: bool = False) -> list[ComposeContainer]:
             else:
                 containers.append(_ignore_properties(ComposeContainer, data))
 
+        # Set the docker_compose reference on each container
+        for container in containers:
+            container._docker_compose = self
+
         return containers
 
     def get_container(
@@ -352,6 +417,7 @@ def get_container(
         if not matching_containers:
             raise ContainerIsNotRunning(f"{service_name} is not running in the compose context")
 
+        matching_containers[0]._docker_compose = self
         return matching_containers[0]
 
     def exec_in_container(
@@ -388,12 +454,18 @@ def _run_command(
         context: Optional[str] = None,
     ) -> CompletedProcess[bytes]:
         context = context or str(self.context)
-        return subprocess_run(
-            cmd,
-            capture_output=True,
-            check=True,
-            cwd=context,
-        )
+        try:
+            return subprocess_run(
+                cmd,
+                capture_output=True,
+                check=True,
+                cwd=context,
+            )
+        except CalledProcessError as e:
+            logger.error(f"Command '{e.cmd}' failed with exit code {e.returncode}")
+            logger.error(f"STDOUT:\n{e.stdout.decode(errors='ignore')}")
+            logger.error(f"STDERR:\n{e.stderr.decode(errors='ignore')}")
+            raise e from e
 
     def get_service_port(
         self,
@@ -452,16 +524,54 @@ def get_service_host_and_port(
         publisher = self.get_container(service_name).get_publisher(by_port=port).normalize()
         return publisher.URL, publisher.PublishedPort
 
-    @wait_container_is_ready(HTTPError, URLError)
     def wait_for(self, url: str) -> "DockerCompose":
         """
         Waits for a response from a given URL. This is typically used to block until a service in
         the environment has started and is responding. Note that it does not assert any sort of
         return code, only check that the connection was successful.
 
+        This is a convenience method that internally uses HttpWaitStrategy. For more complex
+        wait scenarios, consider using the structured wait strategies with `waiting_for()`.
+
         Args:
             url: URL from one of the services in the environment to use to wait on.
+
+        Example:
+            # Simple URL wait (legacy style)
+            compose.wait_for("http://localhost:8080") \
+            \
+            # For more complex scenarios, use structured wait strategies:
+            from testcontainers.core.waiting_utils import HttpWaitStrategy, LogMessageWaitStrategy \
+            \
+            compose.waiting_for({ \
+                "web": HttpWaitStrategy(8080).for_status_code(200), \
+                "db": LogMessageWaitStrategy("database system is ready to accept connections") \
+            })
         """
+        import time
+        from urllib.error import HTTPError, URLError
+        from urllib.request import Request, urlopen
+
+        # For simple URL waiting when we have multiple containers,
+        # we'll do a direct HTTP check instead of using the container-based strategy
+        start_time = time.time()
+        timeout = 120  # Default timeout
+
+        while True:
+            if time.time() - start_time > timeout:
+                raise TimeoutError(f"URL {url} not ready within {timeout} seconds")
+
+            try:
+                request = Request(url, method="GET")
+                with urlopen(request, timeout=1) as response:
+                    if 200 <= response.status < 400:
+                        return self
+            except (URLError, HTTPError, ConnectionResetError, ConnectionRefusedError, BrokenPipeError, OSError):
+                # Any connection error means we should keep waiting
+                pass
+
+            time.sleep(1)
+
         with urlopen(url) as response:
             response.read()
         return self