Merge branch 'main' into influxdb3

Author: Tranquility2

Makefile

@@ -25,6 +25,9 @@ ${TESTS}: %/tests:
 quick-core-tests:  ## Run core tests excluding long_running
 	uv run coverage run --parallel -m pytest -v -m "not long_running" core/tests
 
+core-tests:  ## Run tests for the core package
+	uv run coverage run --parallel -m pytest -v core/tests
+
 coverage:  ## Target to combine and report coverage.
 	uv run coverage combine
 	uv run coverage report

conf.py

@@ -168,4 +168,5 @@
 nitpick_ignore = [
     ("py:class", "typing_extensions.Self"),
     ("py:class", "docker.models.containers.ExecResult"),
+    ("py:class", "testcontainers.core.docker_client.ContainerInspectInfo"),
 ]

core/README.rst

@@ -16,6 +16,8 @@ Testcontainers Core
 
 .. autoclass:: testcontainers.core.wait_strategies.WaitStrategy
 
+.. autoclass:: testcontainers.core.transferable.Transferable
+
 .. raw:: html
 
     <hr>
@@ -49,3 +51,20 @@ Using `DockerContainer` and `DockerImage` to create a container:
 
 The `DockerImage` class is used to build the image from the specified path and tag.
 The `DockerContainer` class is then used to create a container from the image.
+
+Copying a file from disk into a container:
+
+.. doctest::
+
+    >>> import tempfile
+    >>> from pathlib import Path
+    >>> from testcontainers.core.container import DockerContainer
+
+    >>> with tempfile.TemporaryDirectory() as tmp:
+    ...     my_file = Path(tmp) / "my_file.txt"
+    ...     _ = my_file.write_text("file content")
+    ...     with DockerContainer("bash", command="sleep infinity") as container:
+    ...         container.copy_into_container(my_file, "/tmp/my_file.txt")
+    ...         result = container.exec("cat /tmp/my_file.txt")
+    ...         result.output
+    b'file content'

core/testcontainers/compose/compose.py

@@ -1,5 +1,5 @@
 import sys
-from dataclasses import asdict, dataclass, field, fields, is_dataclass
+from dataclasses import asdict, dataclass, field
 from functools import cached_property
 from json import loads
 from logging import getLogger, warning
@@ -11,28 +11,16 @@
 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.exceptions import ContainerIsNotRunning, NoSuchPortExposed
+from testcontainers.core.inspect import ContainerInspectInfo, _ignore_properties
 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)
-
-    https://gist.github.com/alexanderankin/2a4549ac03554a31bef6eaaf2eaf7fd5"""
-    if isinstance(dict_, cls):
-        return dict_
-    if not is_dataclass(cls):
-        raise TypeError(f"Expected a dataclass type, got {cls}")
-    class_fields = {f.name for f in fields(cls)}
-    filtered = {k: v for k, v in dict_.items() if k in class_fields}
-    return cls(**filtered)
-
-
 @dataclass
 class PublishedPortModel:
     """
@@ -45,10 +33,21 @@ class PublishedPortModel:
     Protocol: Optional[str] = None
 
     def normalize(self) -> "PublishedPortModel":
-        url_not_usable = system() == "Windows" and self.URL == "0.0.0.0"
-        if url_not_usable:
+        url = self.URL
+
+        # 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.
+        ssh_host = get_docker_host_hostname()
+        if ssh_host and 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":
+            url = "127.0.0.1"
+
+        if url != self.URL:
             self_dict = asdict(self)
-            self_dict.update({"URL": "127.0.0.1"})
+            self_dict.update({"URL": url})
             return PublishedPortModel(**self_dict)
         return self
 
@@ -81,6 +80,7 @@ class ComposeContainer:
     ExitCode: Optional[int] = None
     Publishers: list[PublishedPortModel] = field(default_factory=list)
     _docker_compose: Optional["DockerCompose"] = field(default=None, init=False, repr=False)
+    _cached_container_info: Optional[ContainerInspectInfo] = field(default=None, init=False, repr=False)
 
     def __post_init__(self) -> None:
         if self.Publishers:
@@ -147,6 +147,28 @@ def reload(self) -> None:
         # each time through get_container(), but we need this method for compatibility
         pass
 
+    def get_container_info(self) -> Optional[ContainerInspectInfo]:
+        """Get container information via docker inspect (lazy loaded).
+
+        Returns:
+            Container inspect information or None if container is not started.
+        """
+        if self._cached_container_info is not None:
+            return self._cached_container_info
+
+        if not self._docker_compose or not self.ID:
+            return None
+
+        try:
+            docker_client = self._docker_compose._get_docker_client()
+            self._cached_container_info = docker_client.get_container_inspect_info(self.ID)
+
+        except Exception as e:
+            logger.warning(f"Failed to get container info for {self.ID}: {e}")
+            self._cached_container_info = None
+
+        return self._cached_container_info
+
     @property
     def status(self) -> str:
         """Get container status for compatibility with wait strategies."""
@@ -221,6 +243,7 @@ class DockerCompose:
     quiet_pull: bool = False
     quiet_build: bool = False
     _wait_strategies: Optional[dict[str, Any]] = field(default=None, init=False, repr=False)
+    _docker_client: Optional[DockerClient] = field(default=None, init=False, repr=False)
 
     def __post_init__(self) -> None:
         if isinstance(self.compose_file_name, str):
@@ -494,7 +517,7 @@ def get_service_port(
 
         Returns
         -------
-        str:
+        int:
             The mapped port on the host
         """
         normalize: PublishedPortModel = self.get_container(service_name).get_publisher(by_port=port).normalize()
@@ -585,3 +608,9 @@ def wait_for(self, url: str) -> "DockerCompose":
         with urlopen(url) as response:
             response.read()
         return self
+
+    def _get_docker_client(self) -> DockerClient:
+        """Get Docker client instance."""
+        if self._docker_client is None:
+            self._docker_client = DockerClient()
+        return self._docker_client

core/testcontainers/core/container.py

@@ -1,5 +1,8 @@
 import contextlib
+import io
+import pathlib
 import sys
+import tarfile
 from os import PathLike
 from socket import socket
 from types import TracebackType
@@ -16,8 +19,10 @@
 from testcontainers.core.config import testcontainers_config as c
 from testcontainers.core.docker_client import DockerClient
 from testcontainers.core.exceptions import ContainerConnectException, ContainerStartException
+from testcontainers.core.inspect import ContainerInspectInfo
 from testcontainers.core.labels import LABEL_SESSION_ID, SESSION_ID
 from testcontainers.core.network import Network
+from testcontainers.core.transferable import Transferable, TransferSpec, build_transfer_tar
 from testcontainers.core.utils import is_arm, setup_logger
 from testcontainers.core.wait_strategies import LogMessageWaitStrategy
 from testcontainers.core.waiting_utils import WaitStrategy
@@ -69,6 +74,7 @@ def __init__(
         network: Optional[Network] = None,
         network_aliases: Optional[list[str]] = None,
         _wait_strategy: Optional[WaitStrategy] = None,
+        transferables: Optional[list[TransferSpec]] = None,
         **kwargs: Any,
     ) -> None:
         self.env = env or {}
@@ -82,6 +88,8 @@ def __init__(
             for vol in volumes:
                 self.with_volume_mapping(*vol)
 
+        self.tmpfs: dict[str, str] = {}
+
         self.image = image
         self._docker = DockerClient(**(docker_client_kw or {}))
         self._container: Optional[Container] = None
@@ -97,6 +105,12 @@ def __init__(
 
         self._kwargs = kwargs
         self._wait_strategy: Optional[WaitStrategy] = _wait_strategy
+        self._cached_container_info: Optional[ContainerInspectInfo] = None
+
+        self._transferable_specs: list[TransferSpec] = []
+        if transferables:
+            for t in transferables:
+                self.with_copy_into_container(*t)
 
     def with_env(self, key: str, value: str) -> Self:
         self.env[key] = value
@@ -198,13 +212,18 @@ def start(self) -> Self:
             ports=cast("dict[int, Optional[int]]", self.ports),
             name=self._name,
             volumes=self.volumes,
+            tmpfs=self.tmpfs,
             **{**network_kwargs, **self._kwargs},
         )
 
         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:
@@ -270,6 +289,16 @@ def with_volume_mapping(self, host: Union[str, PathLike[str]], container: str, m
         self.volumes[str(host)] = mapping
         return self
 
+    def with_tmpfs_mount(self, container_path: str, size: Optional[str] = None) -> Self:
+        """Mount a tmpfs volume on the container.
+
+        :param container_path: Container path to mount tmpfs on (e.g., '/data')
+        :param size: Optional size limit (e.g., '256m', '1g'). If None, unbounded.
+        :return: Self for chaining
+        """
+        self.tmpfs[container_path] = size or ""
+        return self
+
     def get_wrapped_container(self) -> "Container":
         return self._container
 
@@ -301,10 +330,60 @@ 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 get_container_info(self) -> Optional[ContainerInspectInfo]:
+        """Get container information via docker inspect (lazy loaded).
+
+        Returns:
+            Container inspect information or None if container is not started.
+        """
+        if self._cached_container_info is not None:
+            return self._cached_container_info
+
+        if not self._container:
+            return None
+
+        try:
+            self._cached_container_info = self.get_docker_client().get_container_inspect_info(self._container.id)
+
+        except Exception as e:
+            logger.warning(f"Failed to get container info for {self._container.id}: {e}")
+            self._cached_container_info = None
+
+        return self._cached_container_info
+
     def _configure(self) -> None:
         # placeholder if subclasses want to define this and use the default start method
         pass
 
+    def with_copy_into_container(
+        self, transferable: Transferable, destination_in_container: str, mode: int = 0o644
+    ) -> Self:
+        self._transferable_specs.append((transferable, destination_in_container, mode))
+        return self
+
+    def copy_into_container(self, transferable: Transferable, destination_in_container: str, mode: int = 0o644) -> None:
+        return self._transfer_into_container(transferable, destination_in_container, mode)
+
+    def _transfer_into_container(self, transferable: Transferable, destination_in_container: str, mode: int) -> None:
+        if not self._container:
+            raise ContainerStartException("Container must be started before transferring files")
+
+        data = build_transfer_tar(transferable, destination_in_container, mode)
+        if not self._container.put_archive(path="/", data=data):
+            raise OSError(f"Failed to put archive into container at {destination_in_container}")
+
+    def copy_from_container(self, source_in_container: str, destination_on_host: pathlib.Path) -> None:
+        if not self._container:
+            raise ContainerStartException("Container must be started before copying files")
+
+        tar_stream, _ = self._container.get_archive(source_in_container)
+
+        with tarfile.open(fileobj=io.BytesIO(b"".join(tar_stream))) as tar:
+            for member in tar.getmembers():
+                extracted = tar.extractfile(member)
+                if extracted is not None:
+                    destination_on_host.write_bytes(extracted.read())
+
 
 class Reaper:
     """