Merge branch 'main' into dependabot/uv/urllib3-2.7.0

Author: Tranquility2

.github/.release-please-manifest.json

@@ -1,3 +1,3 @@
 {
-    ".": "4.15.0-rc2"
+    ".": "4.15.0-rc3"
 }

.github/dependabot.yml

@@ -0,0 +1,6 @@
+version: 2
+updates:
+  - package-ecosystem: "uv"
+    directory: "/"
+    schedule:
+      interval: "weekly"

CHANGELOG.md

@@ -1,5 +1,23 @@
 # Changelog
 
+## [4.15.0-rc3](https://github.com/testcontainers/testcontainers-python/compare/testcontainers-v4.15.0-rc2...testcontainers-v4.15.0-rc3) (2026-06-03)
+
+
+### Features
+
+* **core:** add Podman compatibility ([#1028](https://github.com/testcontainers/testcontainers-python/issues/1028)) ([37093ab](https://github.com/testcontainers/testcontainers-python/commit/37093ab8e1a86d1aecbad915f1af20934861ac35))
+* **core:** auto-detect DOCKER_HOST from current docker context ([#1026](https://github.com/testcontainers/testcontainers-python/issues/1026)) ([d4b8ff6](https://github.com/testcontainers/testcontainers-python/commit/d4b8ff66197e7eb57708c9579fa1fb41d6988f5e)), closes [#1025](https://github.com/testcontainers/testcontainers-python/issues/1025)
+
+
+### Bug Fixes
+
+* **core:** add container logs to TimeoutError when wait strategy times out ([#1007](https://github.com/testcontainers/testcontainers-python/issues/1007)) ([1fadb40](https://github.com/testcontainers/testcontainers-python/commit/1fadb40c456c3ccd4f13b1b82cd19c3ab22c2687))
+* **core:** close Reaper socket at interpreter exit to prevent ResourceWarning ([#1017](https://github.com/testcontainers/testcontainers-python/issues/1017)) ([d3a1517](https://github.com/testcontainers/testcontainers-python/commit/d3a1517f2c5c2e2a48a4c051b2203b80d9141759))
+* **cosmosdb:** replace distutils.strtobool removed in Python 3.12 ([#1018](https://github.com/testcontainers/testcontainers-python/issues/1018)) ([3e487f4](https://github.com/testcontainers/testcontainers-python/commit/3e487f4bab679204820826cfcbc282cb8fc60008))
+* **mongodb:** Use wait strategy instead of deprecated wait_for_logs ([#943](https://github.com/testcontainers/testcontainers-python/issues/943)) ([c8118e7](https://github.com/testcontainers/testcontainers-python/commit/c8118e7c9832743486115221fd8253bdc8c2a5ec))
+* **mssql:** use `ExecWaitStrategy` instead of deprecated `wait_container_is_ready` ([#1016](https://github.com/testcontainers/testcontainers-python/issues/1016)) ([4c53b89](https://github.com/testcontainers/testcontainers-python/commit/4c53b89a1faad9a592d2bb49123ef3e6bf33fdb9)), closes [#874](https://github.com/testcontainers/testcontainers-python/issues/874)
+* **neo4j:** Swap out use of depricated wait utils for wait_strategies ([#1012](https://github.com/testcontainers/testcontainers-python/issues/1012)) ([6deaf3b](https://github.com/testcontainers/testcontainers-python/commit/6deaf3b27e5f8d54ff9ae404dbd092e8014df079))
+
 ## [4.15.0-rc2](https://github.com/testcontainers/testcontainers-python/compare/testcontainers-v4.15.0-rc.1...testcontainers-v4.15.0-rc2) (2026-04-30)
 
 

core/testcontainers/compose/compose.py

@@ -1,3 +1,4 @@
+import shutil
 import sys
 from dataclasses import asdict, dataclass, field
 from functools import cached_property
@@ -11,7 +12,7 @@
 from types import TracebackType
 from typing import Any, Callable, Literal, Optional, TypeVar, Union, cast
 
-from testcontainers.core.docker_client import DockerClient, get_docker_host_hostname
+from testcontainers.core.docker_client import DockerClient, get_docker_host_hostname, is_podman
 from testcontainers.core.exceptions import ContainerIsNotRunning, NoSuchPortExposed
 from testcontainers.core.inspect import ContainerInspectInfo, _ignore_properties
 from testcontainers.core.waiting_utils import WaitStrategy
@@ -21,6 +22,20 @@
 logger = getLogger(__name__)
 
 
+def _default_compose_binary() -> str:
+    """Return the binary used to drive ``compose`` subcommands.
+
+    Prefers ``docker`` when available; otherwise falls back to ``podman``
+    when the daemon is detected as podman. This means a pure-podman host
+    without the ``podman-docker`` shim works out of the box.
+    """
+    if shutil.which("docker"):
+        return "docker"
+    if is_podman() and shutil.which("podman"):
+        return "podman"
+    return "docker"
+
+
 @dataclass
 class PublishedPortModel:
     """
@@ -38,8 +53,9 @@ def normalize(self) -> "PublishedPortModel":
         # For SSH-based DOCKER_HOST, local addresses (0.0.0.0, 127.0.0.1, localhost, ::, ::1)
         # refer to the remote machine, not the local one.
         # Replace them with the actual remote hostname.
+        # Podman may also return empty string or None for the URL.
         ssh_host = get_docker_host_hostname()
-        if ssh_host and url in ("0.0.0.0", "127.0.0.1", "localhost", "::", "::1"):
+        if ssh_host and (not url or url in ("0.0.0.0", "127.0.0.1", "localhost", "::", "::1")):
             url = ssh_host
         # On Windows, 0.0.0.0 is not usable — replace with 127.0.0.1
         elif system() == "Windows" and url == "0.0.0.0":
@@ -275,9 +291,8 @@ def docker_compose_command(self) -> list[str]:
 
     @cached_property
     def compose_command_property(self) -> list[str]:
-        docker_compose_cmd = (
-            [self.docker_command_path, "compose"] if self.docker_command_path else ["docker", "compose"]
-        )
+        binary = self.docker_command_path or _default_compose_binary()
+        docker_compose_cmd = [binary, "compose"]
         if self.compose_file_name:
             for file in self.compose_file_name:
                 docker_compose_cmd += ["-f", file]

core/testcontainers/core/docker_client.py

@@ -22,6 +22,7 @@
 from typing import TYPE_CHECKING, Any, Callable, Optional, TypeVar, Union, cast
 
 import docker
+from docker.context import ContextAPI
 from docker.models.containers import Container, ContainerCollection
 from docker.models.images import Image, ImageCollection
 from typing_extensions import ParamSpec
@@ -320,12 +321,33 @@ def get_container_inspect_info(self, container_id: str) -> "ContainerInspectInfo
 
 
 def get_docker_host() -> Optional[str]:
-    host = c.tc_properties_get_tc_host() or os.getenv("DOCKER_HOST")
+    host = c.tc_properties_get_tc_host() or os.getenv("DOCKER_HOST") or _get_docker_host_from_context()
     if host:
         return _sanitize_docker_host(host)
     return None
 
 
+def _get_docker_host_from_context() -> Optional[str]:
+    """
+    Look up the docker host from the current docker context (e.g. as set by``docker context use``).
+    This allows users with a remote docker host configured via docker contexts to use testcontainers
+    without having to additionally export ``DOCKER_HOST``.
+    """
+    try:
+        context = ContextAPI.get_current_context()
+    except Exception as e:
+        LOGGER.debug(f"failed to read current docker context: {e}")
+        return None
+    if context is None:
+        return None
+    host = context.Host
+    # The default context points at the local unix socket / named pipe; let
+    # docker-py fall back to its own defaults in that case.
+    if not host or context.Name == "default":
+        return None
+    return cast("str", host)
+
+
 def get_docker_host_hostname() -> Optional[str]:
     """Extract the remote hostname from an SSH-based DOCKER_HOST.
 
@@ -344,6 +366,30 @@ def is_ssh_docker_host() -> bool:
     return get_docker_host_hostname() is not None
 
 
+@ft.lru_cache(maxsize=1)
+def is_podman() -> bool:
+    """Detect whether the configured Docker daemon is actually Podman.
+
+    The result is cached for the lifetime of the process: detection requires a
+    daemon round-trip, and this helper is invoked at test-collection time via
+    ``pytest.mark.skipif`` decorators.
+    """
+    try:
+        # Use docker.from_env() directly rather than DockerClient() so we avoid
+        # the constructor's side effects (DOCKER_HOST mutation, registry login).
+        version = docker.from_env().version()
+    except Exception as e:
+        LOGGER.debug(f"is_podman: failed to query daemon version: {e}")
+        return False
+
+    # Prefer the top-level Platform.Name field (matches testcontainers-go).
+    platform_name = (version.get("Platform") or {}).get("Name", "")
+    if "podman" in platform_name.lower():
+        return True
+    # Fall back to scanning the Components array for older podman versions.
+    return any("podman" in comp.get("Name", "").lower() for comp in version.get("Components") or [])
+
+
 def _sanitize_docker_host(docker_host: str) -> str:
     """
     Sanitize the DOCKER_HOST value for compatibility with the Docker SDK.

core/tests/test_compose.py

@@ -10,10 +10,16 @@
 from pytest_mock import MockerFixture
 
 from testcontainers.compose import DockerCompose, ComposeContainer
+from testcontainers.core.docker_client import is_podman
 from testcontainers.core.exceptions import ContainerIsNotRunning, NoSuchPortExposed
 
 FIXTURES = Path(__file__).parent.joinpath("compose_fixtures")
 
+_skip_if_podman_port_range = pytest.mark.skipif(
+    is_podman(),
+    reason="Podman does not support published port ranges (e.g. '5000-5999')",
+)
+
 
 def test_compose_no_file_name():
     basic = DockerCompose(context=FIXTURES / "basic")
@@ -189,6 +195,7 @@ def test_compose_ports():
 
 
 # noinspection HttpUrlsUsage
+@_skip_if_podman_port_range
 def test_compose_multiple_containers_and_ports():
     """test for the logic encapsulated in 'one' function
 
@@ -286,6 +293,7 @@ def test_exec_in_container():
 
 
 # noinspection HttpUrlsUsage
+@_skip_if_podman_port_range
 def test_exec_in_container_multiple():
     """same as above, except we exec into a particular service"""
     multiple = DockerCompose(context=FIXTURES / "port_multiple")
@@ -390,6 +398,8 @@ def test_compose_profile_support(profiles: Optional[list[str]], running: list[st
         pytest.param("ssh://user@10.0.0.5", "0.0.0.0", "10.0.0.5", id="ssh_replaces_wildcard"),
         pytest.param("ssh://user@10.0.0.5", "127.0.0.1", "10.0.0.5", id="ssh_replaces_loopback"),
         pytest.param("ssh://user@10.0.0.5", "::", "10.0.0.5", id="ssh_replaces_ipv6_any"),
+        pytest.param("ssh://user@10.0.0.5", "", "10.0.0.5", id="ssh_replaces_empty"),
+        pytest.param("ssh://user@10.0.0.5", None, "10.0.0.5", id="ssh_replaces_none"),
         pytest.param("tcp://localhost:2375", "0.0.0.0", "0.0.0.0", id="non_ssh_keeps_original"),
     ],
 )
@@ -410,6 +420,33 @@ def test_compose_normalize_rewrites_local_url_for_ssh_docker_host(
     assert result.PublishedPort == 9999
 
 
+@pytest.mark.parametrize(
+    "docker_on_path, podman_on_path, podman_detected, expected",
+    [
+        pytest.param(True, True, True, "docker", id="docker_wins_over_podman"),
+        pytest.param(False, True, True, "podman", id="podman_when_no_docker_and_podman_daemon"),
+        pytest.param(False, False, True, "docker", id="fallback_to_docker_when_no_podman_binary"),
+    ],
+)
+def test_default_compose_binary(
+    monkeypatch: pytest.MonkeyPatch,
+    docker_on_path: bool,
+    podman_on_path: bool,
+    podman_detected: bool,
+    expected: str,
+) -> None:
+    from testcontainers.compose import compose as compose_module
+
+    paths = {
+        "docker": "/usr/bin/docker" if docker_on_path else None,
+        "podman": "/usr/bin/podman" if podman_on_path else None,
+    }
+    monkeypatch.setattr("testcontainers.compose.compose.shutil.which", lambda name: paths.get(name))
+    monkeypatch.setattr(compose_module, "is_podman", lambda: podman_detected)
+
+    assert compose_module._default_compose_binary() == expected
+
+
 def test_container_info():
     """Test get_container_info functionality"""
     basic = DockerCompose(context=FIXTURES / "basic")

core/tests/test_core_ports.py

@@ -4,15 +4,31 @@
 
 from docker.errors import APIError
 
+from testcontainers.core.docker_client import is_podman
+
 
 @pytest.mark.parametrize(
     "container_port, host_port",
     [
         ("8080", "8080"),
-        ("8125/udp", "8125/udp"),
-        ("8092/udp", "8092/udp"),
-        ("9000/tcp", "9000/tcp"),
-        ("8080", "8080/udp"),
+        pytest.param(
+            "8125/udp",
+            "8125/udp",
+            marks=pytest.mark.skipif(is_podman(), reason="Podman rejects protocol in host_port"),
+        ),
+        pytest.param(
+            "8092/udp",
+            "8092/udp",
+            marks=pytest.mark.skipif(is_podman(), reason="Podman rejects protocol in host_port"),
+        ),
+        pytest.param(
+            "9000/tcp",
+            "9000/tcp",
+            marks=pytest.mark.skipif(is_podman(), reason="Podman rejects protocol in host_port"),
+        ),
+        pytest.param(
+            "8080", "8080/udp", marks=pytest.mark.skipif(is_podman(), reason="Podman rejects protocol in host_port")
+        ),
         (8080, 8080),
         (9000, None),
         ("9009", None),
@@ -42,7 +58,18 @@ def test_docker_container_with_bind_ports(container_port: Union[str, int], host_
     expected = {container_port: [{"HostIp": "", "HostPort": host_port}]}
 
     # compare PortBindings to expected output
-    assert client.containers.get(container_id).attrs["HostConfig"]["PortBindings"] == expected
+    actual = client.containers.get(container_id).attrs["HostConfig"]["PortBindings"]
+    if is_podman():
+        # Normalize Podman differences:
+        # - HostIp '0.0.0.0' vs '' (both mean all interfaces)
+        # - Empty host_port: Podman stores the assigned port, Docker stores ''
+        for bindings in actual.values():
+            for binding in bindings:
+                if binding.get("HostIp") == "0.0.0.0":
+                    binding["HostIp"] = ""
+                if not host_port and binding.get("HostPort", "").isdigit():
+                    binding["HostPort"] = ""
+    assert actual == expected
     container.stop()
 
 

core/tests/test_core_registry.py

@@ -22,16 +22,16 @@
 
 from testcontainers.registry import DockerRegistryContainer
 from testcontainers.core.utils import is_mac
+from testcontainers.core.docker_client import is_podman
 
 
-@pytest.mark.skipif(
-    is_mac(),
-    reason="Docker Desktop on macOS does not support insecure private registries without daemon reconfiguration",
-)
-@pytest.mark.skipif(
-    is_ssh_docker_host(),
-    reason="Remote Docker via SSH requires HTTPS for non-localhost registries; insecure HTTP registries are not accessible",
+_skip_insecure_registry = pytest.mark.skipif(
+    is_mac() or is_podman() or is_ssh_docker_host(),
+    reason="Insecure HTTP registries are not supported without daemon reconfiguration on macOS, Podman, or SSH-based Docker hosts",
 )
+
+
+@_skip_insecure_registry
 def test_missing_on_private_registry(monkeypatch):
     username = "user"
     password = "pass"
@@ -53,14 +53,7 @@ def test_missing_on_private_registry(monkeypatch):
                 wait_for_logs(test_container, "Hello from Docker!")
 
 
-@pytest.mark.skipif(
-    is_mac(),
-    reason="Docker Desktop on macOS does not support local insecure registries over HTTP without modifying daemon settings",
-)
-@pytest.mark.skipif(
-    is_ssh_docker_host(),
-    reason="Remote Docker via SSH requires HTTPS for non-localhost registries; insecure HTTP registries are not accessible",
-)
+@_skip_insecure_registry
 @pytest.mark.parametrize(
     "image,tag,username,password,expected_output",
     [