Merge branch 'main' into add-management-relative-path

Author: alexanderankin

core/README.rst

@@ -16,6 +16,8 @@ Testcontainers Core
 
 .. autoclass:: testcontainers.core.wait_strategies.WaitStrategy
 
+.. autoclass:: testcontainers.core.transferable.Transferable
+
 .. raw:: html
 
     <hr>

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
@@ -18,6 +21,7 @@
 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.transferable import Transferable, TransferSpec
 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 +73,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 +87,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
@@ -98,6 +105,11 @@ def __init__(
         self._kwargs = kwargs
         self._wait_strategy: Optional[WaitStrategy] = _wait_strategy
 
+        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
         return self
@@ -198,13 +210,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 +287,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
 
@@ -305,6 +332,68 @@ 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 isinstance(transferable, bytes):
+            self._transfer_file_content_into_container(transferable, destination_in_container, mode)
+        elif isinstance(transferable, pathlib.Path):
+            if transferable.is_file():
+                self._transfer_file_content_into_container(transferable.read_bytes(), destination_in_container, mode)
+            elif transferable.is_dir():
+                self._transfer_directory_into_container(transferable, destination_in_container, mode)
+            else:
+                raise TypeError(f"Path {transferable} is neither a file nor directory")
+        else:
+            raise TypeError("source must be bytes or PathLike")
+
+    def _transfer_file_content_into_container(
+        self, file_content: bytes, destination_in_container: str, mode: int
+    ) -> None:
+        fileobj = io.BytesIO()
+        with tarfile.open(fileobj=fileobj, mode="w") as tar:
+            tarinfo = tarfile.TarInfo(name=destination_in_container)
+            tarinfo.size = len(file_content)
+            tarinfo.mode = mode
+            tar.addfile(tarinfo, io.BytesIO(file_content))
+        fileobj.seek(0)
+        assert self._container is not None
+        rv = self._container.put_archive(path="/", data=fileobj.getvalue())
+        assert rv is True
+
+    def _transfer_directory_into_container(
+        self, source_directory: pathlib.Path, destination_in_container: str, mode: int
+    ) -> None:
+        assert self._container is not None
+        result = self._container.exec_run(["mkdir", "-p", destination_in_container])
+        assert result.exit_code == 0
+
+        fileobj = io.BytesIO()
+        with tarfile.open(fileobj=fileobj, mode="w") as tar:
+            tar.add(source_directory, arcname=source_directory.name)
+        fileobj.seek(0)
+        rv = self._container.put_archive(path=destination_in_container, data=fileobj.getvalue())
+        assert rv is True
+
+    def copy_from_container(self, source_in_container: str, destination_on_host: pathlib.Path) -> None:
+        assert self._container is not None
+        tar_stream, _ = self._container.get_archive(source_in_container)
+
+        for chunk in tar_stream:
+            with tarfile.open(fileobj=io.BytesIO(chunk)) as tar:
+                for member in tar.getmembers():
+                    with open(destination_on_host, "wb") as f:
+                        fileobj = tar.extractfile(member)
+                        assert fileobj is not None
+                        f.write(fileobj.read())
+
 
 class Reaper:
     """

core/testcontainers/core/generic.py

@@ -29,6 +29,8 @@
 class DbContainer(DockerContainer):
     """
     **DEPRECATED (for removal)**
+    Please use database-specific container classes or `SqlContainer` instead.
+    # from testcontainers.generic.sql import SqlContainer
 
     Generic database container.
     """

core/testcontainers/core/transferable.py

@@ -0,0 +1,6 @@
+import pathlib
+from typing import Union
+
+Transferable = Union[bytes, pathlib.Path]
+
+TransferSpec = Union[tuple[Transferable, str], tuple[Transferable, str, int]]

core/tests/test_core.py

@@ -1,7 +1,9 @@
 import tempfile
 from pathlib import Path
 
+import pytest
 from testcontainers.core.container import DockerContainer
+from testcontainers.core.transferable import Transferable, TransferSpec
 
 
 def test_garbage_collection_is_defensive():
@@ -46,3 +48,109 @@ def test_docker_container_with_env_file():
             assert "ADMIN_EMAIL=admin@example.org" in output
             assert "ROOT_URL=example.org/app" in output
             print(output)
+
+
+@pytest.fixture(name="transferable", params=(bytes, Path))
+def copy_sources_fixture(request, tmp_path: Path):
+    """
+    Provide source argument for tests of copy_into_container
+    """
+    raw_data = b"hello world"
+    if request.param is bytes:
+        return raw_data
+    elif request.param is Path:
+        my_file = tmp_path / "my_file"
+        my_file.write_bytes(raw_data)
+        return my_file
+    pytest.fail("Invalid type")
+
+
+def test_copy_into_container_at_runtime(transferable: Transferable):
+    # Given
+    destination_in_container = "/tmp/my_file"
+
+    with DockerContainer("bash", command="sleep infinity") as container:
+        # When
+        container.copy_into_container(transferable, destination_in_container)
+        result = container.exec(f"cat {destination_in_container}")
+
+    # Then
+    assert result.exit_code == 0
+    assert result.output == b"hello world"
+
+
+def test_copy_into_container_at_startup(transferable: Transferable):
+    # Given
+    destination_in_container = "/tmp/my_file"
+
+    container = DockerContainer("bash", command="sleep infinity")
+    container.with_copy_into_container(transferable, destination_in_container)
+
+    with container:
+        # When
+        result = container.exec(f"cat {destination_in_container}")
+
+    # Then
+    assert result.exit_code == 0
+    assert result.output == b"hello world"
+
+
+def test_copy_into_container_via_initializer(transferable: Transferable):
+    # Given
+    destination_in_container = "/tmp/my_file"
+    transferables: list[TransferSpec] = [(transferable, destination_in_container, 0o644)]
+
+    with DockerContainer("bash", command="sleep infinity", transferables=transferables) as container:
+        # When
+        result = container.exec(f"cat {destination_in_container}")
+
+    # Then
+    assert result.exit_code == 0
+    assert result.output == b"hello world"
+
+
+def test_copy_file_from_container(tmp_path: Path):
+    # Given
+    file_in_container = "/tmp/foo.txt"
+    destination_on_host = tmp_path / "foo.txt"
+    assert not destination_on_host.is_file()
+
+    with DockerContainer("bash", command="sleep infinity") as container:
+        result = container.exec(f'bash -c "echo -n hello world > {file_in_container}"')
+        assert result.exit_code == 0
+
+        # When
+        container.copy_from_container(file_in_container, destination_on_host)
+
+    # Then
+    assert destination_on_host.is_file()
+    assert destination_on_host.read_text() == "hello world"
+
+
+def test_copy_directory_into_container(tmp_path: Path):
+    # Given
+    source_dir = tmp_path / "my_directory"
+    source_dir.mkdir()
+    my_file = source_dir / "my_file"
+    my_file.write_bytes(b"hello world")
+
+    destination_in_container = "/tmp/my_destination_directory"
+
+    with DockerContainer("bash", command="sleep infinity") as container:
+        # When
+        container.copy_into_container(source_dir, destination_in_container)
+        result = container.exec(f"ls {destination_in_container}")
+
+        # Then - my_directory exists
+        assert result.exit_code == 0
+        assert result.output == b"my_directory\n"
+
+        # Then - my_file is in directory
+        result = container.exec(f"ls {destination_in_container}/my_directory")
+        assert result.exit_code == 0
+        assert result.output == b"my_file\n"
+
+        # Then - my_file contents are correct
+        result = container.exec(f"cat {destination_in_container}/my_directory/my_file")
+        assert result.exit_code == 0
+        assert result.output == b"hello world"

modules/generic/README.rst

@@ -9,6 +9,7 @@ FastAPI container that is using :code:`ServerContainer`
 
     >>> from testcontainers.generic import ServerContainer
     >>> from testcontainers.core.waiting_utils import wait_for_logs
+    >>> from testcontainers.core.image import DockerImage
 
     >>> with DockerImage(path="./modules/generic/tests/samples/fastapi", tag="fastapi-test:latest") as image:
     ...     with ServerContainer(port=80, image=image) as fastapi_server:
@@ -50,3 +51,39 @@ A more advance use-case, where we are using a FastAPI container that is using Re
     ...             response = client.get(f"/get/{test_data['key']}")
     ...             assert response.status_code == 200, "Failed to get data"
     ...             assert response.json() == {"key": test_data["key"], "value": test_data["value"]}
+
+.. autoclass:: testcontainers.generic.SqlContainer
+.. title:: testcontainers.generic.SqlContainer
+
+Postgres container that is using :code:`SqlContainer`
+
+.. doctest::
+
+    >>> from testcontainers.generic import SqlContainer
+    >>> from testcontainers.generic.providers.sql_connection_wait_strategy import SqlAlchemyConnectWaitStrategy
+    >>> from sqlalchemy import text
+    >>> import sqlalchemy
+
+    >>> class CustomPostgresContainer(SqlContainer):
+    ...     def __init__(self, image="postgres:15-alpine",
+    ...                  port=5432, username="test", password="test", dbname="test"):
+    ...         super().__init__(image=image, wait_strategy=SqlAlchemyConnectWaitStrategy())
+    ...         self.port_to_expose = port
+    ...         self.username = username
+    ...         self.password = password
+    ...         self.dbname = dbname
+    ...     def get_connection_url(self) -> str:
+    ...         host = self.get_container_host_ip()
+    ...         port = self.get_exposed_port(self.port_to_expose)
+    ...         return f"postgresql://{self.username}:{self.password}@{host}:{port}/{self.dbname}"
+    ...     def _configure(self) -> None:
+    ...         self.with_exposed_ports(self.port_to_expose)
+    ...         self.with_env("POSTGRES_USER", self.username)
+    ...         self.with_env("POSTGRES_PASSWORD", self.password)
+    ...         self.with_env("POSTGRES_DB", self.dbname)
+
+    >>> with CustomPostgresContainer() as postgres:
+    ...     engine = sqlalchemy.create_engine(postgres.get_connection_url())
+    ...     with engine.connect() as conn:
+    ...         result = conn.execute(text("SELECT 1"))
+    ...         assert result.scalar() == 1

modules/generic/testcontainers/generic/__init__.py

@@ -1 +1,2 @@
 from .server import ServerContainer  # noqa: F401
+from .sql import SqlContainer  # noqa: F401

modules/generic/testcontainers/generic/providers/__init__.py

@@ -0,0 +1 @@
+from .sql_connection_wait_strategy import SqlAlchemyConnectWaitStrategy  # noqa: F401

modules/generic/testcontainers/generic/providers/sql_connection_wait_strategy.py

@@ -0,0 +1,48 @@
+# This module provides a wait strategy for SQL database connectivity testing using SQLAlchemy.
+# It includes handling for transient exceptions and connection retries.
+
+import logging
+
+from testcontainers.core.waiting_utils import WaitStrategy, WaitStrategyTarget
+
+logger = logging.getLogger(__name__)
+
+ADDITIONAL_TRANSIENT_ERRORS = []
+try:
+    from sqlalchemy.exc import DBAPIError
+
+    ADDITIONAL_TRANSIENT_ERRORS.append(DBAPIError)
+except ImportError:
+    logger.debug("SQLAlchemy not available, skipping DBAPIError handling")
+
+
+class SqlAlchemyConnectWaitStrategy(WaitStrategy):
+    """Wait strategy for database connectivity testing using SQLAlchemy."""
+
+    def __init__(self):
+        super().__init__()
+        self.with_transient_exceptions(TimeoutError, ConnectionError, *ADDITIONAL_TRANSIENT_ERRORS)
+
+    def wait_until_ready(self, container: WaitStrategyTarget) -> None:
+        """Test database connectivity with retry logic until success or timeout."""
+        if not hasattr(container, "get_connection_url"):
+            raise AttributeError(f"Container {container} must have a get_connection_url method")
+
+        try:
+            import sqlalchemy
+        except ImportError as e:
+            raise ImportError("SQLAlchemy is required for database containers") from e
+
+        def _test_connection() -> bool:
+            """Test database connection, returning True if successful."""
+            engine = sqlalchemy.create_engine(container.get_connection_url())
+            try:
+                with engine.connect():
+                    logger.info("Database connection successful")
+                    return True
+            finally:
+                engine.dispose()
+
+        result = self._poll(_test_connection)
+        if not result:
+            raise TimeoutError(f"Database connection failed after {self._startup_timeout}s timeout")