pytest-testcontainers 0.1.0__py3-none-any.whl

pytest_testcontainers/__init__.py

@@ -0,0 +1,37 @@
+"""Named pytest fixtures + maker convention on top of testcontainers-python."""
+
+from __future__ import annotations
+
+from pytest_testcontainers._internal.conn_info import DbConnInfo
+from pytest_testcontainers.errors import (
+    CleanSessionFixtureError,
+    ContainerStartError,
+    DockerNotRunningError,
+    PytestTestcontainersError,
+    ReuseConflictError,
+)
+from pytest_testcontainers.makers import (
+    make_container,
+    make_mongo,
+    make_mysql,
+    make_postgres,
+    make_rabbitmq,
+    make_redis,
+)
+
+__all__ = [
+    "CleanSessionFixtureError",
+    "ContainerStartError",
+    "DbConnInfo",
+    "DockerNotRunningError",
+    "PytestTestcontainersError",
+    "ReuseConflictError",
+    "make_container",
+    "make_mongo",
+    "make_mysql",
+    "make_postgres",
+    "make_rabbitmq",
+    "make_redis",
+]
+
+__version__ = "0.1.0"

pytest_testcontainers/_internal/__init__.py

@@ -0,0 +1 @@
+"""Internal helpers — not part of the public API."""

pytest_testcontainers/_internal/clean_session_admin.py

@@ -0,0 +1,329 @@
+"""Admin commands behind clean-session fixtures.
+
+Each service gets a tiny dispatch table:
+
+* ``create_<service>_db`` / ``drop_<service>_db`` (Postgres, MySQL, Mongo)
+* ``flush_redis`` (Redis only — exec-only by design)
+
+Both branches (Python client + ``docker exec``) raise the same
+:class:`CleanSessionFixtureError` so user code sees one exception type.
+
+All commands invoked inside the container go through docker-py's
+``exec_run`` with an argv list (never a shell string). Generated
+identifiers are produced by us via ``secrets.token_hex`` upstream and
+are additionally quoted defensively at the SQL layer.
+"""
+
+from __future__ import annotations
+
+import logging
+import os
+import shlex
+import sys
+import threading
+from typing import TYPE_CHECKING, Any
+
+from pytest_testcontainers.errors import CleanSessionFixtureError
+
+if TYPE_CHECKING:
+    from testcontainers.core.container import DockerContainer
+
+logger = logging.getLogger("pytest_testcontainers")
+
+_warned_lock = threading.Lock()
+_warned_services: set[str] = set()
+
+
+def _is_truthy(value: str | None) -> bool:
+    return (value or "").strip().lower() in {"1", "true", "yes", "on"}
+
+
+def _is_quiet() -> bool:
+    return _is_truthy(os.environ.get("PYTEST_TESTCONTAINERS_QUIET"))
+
+
+def _maybe_warn_fallback(service: str, install_hint: str) -> None:
+    global _warned_services
+    if _is_quiet():
+        return
+    with _warned_lock:
+        if service in _warned_services:
+            return
+        _warned_services.add(service)
+    sys.stderr.write(
+        f"[pytest-testcontainers] {service} using docker exec fallback\n"
+        f"(~100ms per admin call). For ~20x speedup install the client:\n"
+        f"    pip install {install_hint}\n"
+        f"or via the convenience extra:\n"
+        f"    pip install pytest-testcontainers[clients]\n"
+        f"Suppress this notice with PYTEST_TESTCONTAINERS_QUIET=1.\n"
+    )
+
+
+def _reset_warnings_for_tests() -> None:
+    global _warned_services
+    with _warned_lock:
+        _warned_services = set()
+
+
+def _run_in_container(
+    container: DockerContainer,
+    argv: list[str],
+    *,
+    env: dict[str, str] | None = None,
+) -> tuple[int, str, str]:
+    """Execute ``argv`` inside the container; return ``(exit_code, stdout, stderr)``."""
+    raw_container = getattr(container, "_container", None)
+    if raw_container is None:
+        raise CleanSessionFixtureError(
+            "container has no underlying docker-py reference",
+            command=" ".join(shlex.quote(a) for a in argv),
+            stderr="container._container is None",
+            exit_code=None,
+        )
+    exec_kwargs: dict[str, Any] = {"demux": True}
+    if env:
+        exec_kwargs["environment"] = env
+    exit_code, output = raw_container.exec_run(argv, **exec_kwargs)
+    if isinstance(output, tuple):
+        stdout_b, stderr_b = output
+    else:
+        stdout_b, stderr_b = output, b""
+    stdout = (stdout_b or b"").decode(errors="replace")
+    stderr = (stderr_b or b"").decode(errors="replace")
+    return exit_code, stdout, stderr
+
+
+def _pg_admin_kwargs(container: DockerContainer) -> dict[str, Any]:
+    from pytest_testcontainers._internal.port_resolver import normalize_host
+
+    return {
+        "host": normalize_host(container.get_container_host_ip()),
+        "port": int(container.get_exposed_port(5432)),
+        "user": container.username,
+        "password": container.password,
+        "dbname": "postgres",
+    }
+
+
+def _pg_create_via_psycopg(container: DockerContainer, name: str) -> None:
+    import psycopg
+    from psycopg import sql
+
+    kwargs = _pg_admin_kwargs(container)
+    try:
+        with psycopg.connect(autocommit=True, **kwargs) as conn, conn.cursor() as cur:
+            cur.execute(sql.SQL("CREATE DATABASE {}").format(sql.Identifier(name)))
+    except Exception as exc:
+        raise CleanSessionFixtureError(
+            f"CREATE DATABASE {name!r} failed via psycopg",
+            command=f"CREATE DATABASE {name!r}",
+            stderr=repr(exc),
+            exit_code=None,
+        ) from exc
+
+
+def _pg_drop_via_psycopg(container: DockerContainer, name: str) -> None:
+    import psycopg
+    from psycopg import sql
+
+    kwargs = _pg_admin_kwargs(container)
+    try:
+        with psycopg.connect(autocommit=True, **kwargs) as conn, conn.cursor() as cur:
+            cur.execute(
+                sql.SQL("DROP DATABASE IF EXISTS {} WITH (FORCE)").format(sql.Identifier(name))
+            )
+    except Exception as exc:
+        raise CleanSessionFixtureError(
+            f"DROP DATABASE {name!r} failed via psycopg",
+            command=f"DROP DATABASE {name!r} WITH (FORCE)",
+            stderr=repr(exc),
+            exit_code=None,
+        ) from exc
+
+
+def _pg_run_in_container(container: DockerContainer, sql_text: str) -> None:
+    argv = [
+        "psql",
+        "-U",
+        container.username,
+        "-d",
+        "postgres",
+        "-v",
+        "ON_ERROR_STOP=1",
+        "-c",
+        sql_text,
+    ]
+    env = {"PGPASSWORD": container.password}
+    exit_code, stdout, stderr = _run_in_container(container, argv, env=env)
+    if exit_code != 0:
+        raise CleanSessionFixtureError(
+            f"psql admin command failed (exit={exit_code})",
+            command=sql_text,
+            stderr=(stderr or stdout).strip(),
+            exit_code=exit_code,
+        )
+
+
+def create_postgres_db(container: DockerContainer, name: str) -> None:
+    """Issue ``CREATE DATABASE <name>`` against the session container."""
+    try:
+        import psycopg  # noqa: F401
+    except ImportError:
+        _maybe_warn_fallback("tc_psql_db", "psycopg[binary]")
+        _pg_run_in_container(container, f'CREATE DATABASE "{name}"')
+        return
+    _pg_create_via_psycopg(container, name)
+
+
+def drop_postgres_db(container: DockerContainer, name: str) -> None:
+    """Issue ``DROP DATABASE <name> WITH (FORCE)``."""
+    try:
+        import psycopg  # noqa: F401
+    except ImportError:
+        _pg_run_in_container(container, f'DROP DATABASE IF EXISTS "{name}" WITH (FORCE)')
+        return
+    _pg_drop_via_psycopg(container, name)
+
+
+def _mysql_run_in_container(container: DockerContainer, sql_text: str) -> None:
+    argv = [
+        "mysql",
+        f"-u{container.username}",
+        f"-p{container.password}",
+        "-e",
+        sql_text,
+    ]
+    exit_code, stdout, stderr = _run_in_container(container, argv)
+    if exit_code != 0:
+        raise CleanSessionFixtureError(
+            f"mysql admin command failed (exit={exit_code})",
+            command=sql_text,
+            stderr=(stderr or stdout).strip(),
+            exit_code=exit_code,
+        )
+
+
+def _mysql_run_pymysql(container: DockerContainer, sql_text: str) -> None:
+    import pymysql
+
+    from pytest_testcontainers._internal.port_resolver import normalize_host
+
+    try:
+        conn = pymysql.connect(
+            host=normalize_host(container.get_container_host_ip()),
+            port=int(container.get_exposed_port(3306)),
+            user=container.username,
+            password=container.password,
+            autocommit=True,
+        )
+    except Exception as exc:
+        raise CleanSessionFixtureError(
+            "mysql admin connect failed",
+            command=sql_text,
+            stderr=repr(exc),
+            exit_code=None,
+        ) from exc
+    try:
+        with conn.cursor() as cur:
+            cur.execute(sql_text)
+    except Exception as exc:
+        raise CleanSessionFixtureError(
+            "mysql admin command failed via pymysql",
+            command=sql_text,
+            stderr=repr(exc),
+            exit_code=None,
+        ) from exc
+    finally:
+        try:
+            conn.close()
+        except Exception as exc:
+            logger.debug("pymysql conn.close() failed: %r", exc)
+
+
+def create_mysql_db(container: DockerContainer, name: str) -> None:
+    try:
+        import pymysql  # noqa: F401
+    except ImportError:
+        _maybe_warn_fallback("tc_mysql_db", "pymysql")
+        _mysql_run_in_container(container, f"CREATE DATABASE `{name}`")
+        return
+    _mysql_run_pymysql(container, f"CREATE DATABASE `{name}`")
+
+
+def drop_mysql_db(container: DockerContainer, name: str) -> None:
+    try:
+        import pymysql  # noqa: F401
+    except ImportError:
+        _mysql_run_in_container(container, f"DROP DATABASE IF EXISTS `{name}`")
+        return
+    _mysql_run_pymysql(container, f"DROP DATABASE IF EXISTS `{name}`")
+
+
+def _mongo_run_in_container_drop(container: DockerContainer, name: str) -> None:
+    uri = (
+        f"mongodb://{container.username}:{container.password}"
+        f"@127.0.0.1:27017/admin?authSource=admin"
+    )
+    js = f"db.getSiblingDB({name!r}).dropDatabase()"
+    argv = ["mongosh", "--quiet", uri, "--eval", js]
+    exit_code, stdout, stderr = _run_in_container(container, argv)
+    if exit_code != 0:
+        raise CleanSessionFixtureError(
+            f"mongosh dropDatabase failed (exit={exit_code})",
+            command=js,
+            stderr=(stderr or stdout).strip(),
+            exit_code=exit_code,
+        )
+
+
+def _mongo_run_pymongo_drop(container: DockerContainer, name: str) -> None:
+    from pymongo import MongoClient
+
+    from pytest_testcontainers._internal.port_resolver import normalize_host
+
+    host = normalize_host(container.get_container_host_ip())
+    port = int(container.get_exposed_port(27017))
+    try:
+        client = MongoClient(
+            host=host,
+            port=port,
+            username=container.username,
+            password=container.password,
+            serverSelectionTimeoutMS=5000,
+        )
+        try:
+            client.drop_database(name)
+        finally:
+            client.close()
+    except Exception as exc:
+        raise CleanSessionFixtureError(
+            "mongo dropDatabase failed via pymongo",
+            command=f"dropDatabase({name!r})",
+            stderr=repr(exc),
+            exit_code=None,
+        ) from exc
+
+
+def drop_mongo_db(container: DockerContainer, name: str) -> None:
+    """Drop a Mongo database. First write materializes it, so no create step."""
+    try:
+        import pymongo  # noqa: F401
+    except ImportError:
+        _maybe_warn_fallback("tc_mongo_db", "pymongo")
+        _mongo_run_in_container_drop(container, name)
+        return
+    _mongo_run_pymongo_drop(container, name)
+
+
+def flush_redis(container: DockerContainer) -> None:
+    """Run ``redis-cli FLUSHALL`` inside the container (exec-only by design)."""
+    argv = ["redis-cli", "FLUSHALL"]
+    exit_code, stdout, stderr = _run_in_container(container, argv)
+    if exit_code != 0:
+        raise CleanSessionFixtureError(
+            f"redis-cli FLUSHALL failed (exit={exit_code})",
+            command="redis-cli FLUSHALL",
+            stderr=(stderr or stdout).strip(),
+            exit_code=exit_code,
+        )

pytest_testcontainers/_internal/conn_info.py

@@ -0,0 +1,29 @@
+"""``DbConnInfo`` — connection-info dataclass yielded by clean-session DB fixtures."""
+
+from __future__ import annotations
+
+from dataclasses import dataclass
+
+
+@dataclass(frozen=True)
+class DbConnInfo:
+    """Frozen bundle of connection coordinates for a clean-session DB fixture.
+
+    Yielded by ``tc_psql_db`` / ``tc_mysql_db`` / ``tc_mongo_db``. The
+    fixture is about isolation, not about handing back a live client —
+    user code constructs its preferred client/ORM/URL from these fields.
+    """
+
+    host: str
+    port: int
+    username: str
+    password: str
+    database: str
+
+    def url(self, scheme: str = "postgresql") -> str:
+        """Render a DB URL of the form ``<scheme>://user:pass@host:port/db``.
+
+        ``scheme`` defaults to ``"postgresql"``. Pass ``"mysql"``,
+        ``"mongodb"``, or any other scheme as needed — no validation.
+        """
+        return f"{scheme}://{self.username}:{self.password}@{self.host}:{self.port}/{self.database}"

pytest_testcontainers/_internal/docker_health.py

@@ -0,0 +1,59 @@
+"""Docker daemon health check — single source of truth for daemon ping.
+
+The cache stores **only successful pings**. A successful ping flips a
+process-wide flag; subsequent maker calls in the same process skip the
+probe. A failed ping does NOT poison the cache, so a transient daemon
+restart inside a long-running pytest session does not permanently
+disable the plugin.
+"""
+
+from __future__ import annotations
+
+import os
+import threading
+
+from pytest_testcontainers.errors import DockerNotRunningError
+
+_lock = threading.Lock()
+_ping_ok: bool = False
+
+
+def _is_truthy(value: str | None) -> bool:
+    return (value or "").strip().lower() in {"1", "true", "yes", "on"}
+
+
+def reset_cache() -> None:
+    """Reset the success cache. Used in tests."""
+    global _ping_ok
+    with _lock:
+        _ping_ok = False
+
+
+def check_docker_daemon() -> None:
+    """Ping the Docker daemon once per process (on success).
+
+    Raises :class:`DockerNotRunningError` (chained from the underlying
+    docker-py exception) if the daemon cannot be reached.
+    """
+    global _ping_ok
+    if _ping_ok:
+        return
+    if _is_truthy(os.environ.get("PYTEST_TESTCONTAINERS_NO_DAEMON_CHECK")):
+        return
+
+    try:
+        import docker  # local import: never trigger at module-import time
+    except ImportError as exc:  # pragma: no cover — docker is a hard dep
+        raise DockerNotRunningError(
+            "docker-py is not installed; cannot ping Docker daemon"
+        ) from exc
+
+    try:
+        client = docker.from_env()
+        client.ping()
+    except Exception as exc:
+        # Surface the underlying daemon failure with a concrete cause.
+        raise DockerNotRunningError(f"docker.from_env().ping() failed: {exc!r}") from exc
+
+    with _lock:
+        _ping_ok = True

pytest_testcontainers/_internal/port_resolver.py

@@ -0,0 +1,20 @@
+"""Host/port resolution that normalizes Docker's quirks.
+
+Docker's ``NetworkSettings.Ports`` returns ``HostIp`` strings that vary
+across platforms: ``""`` and ``"0.0.0.0"`` on Linux, ``"::"`` on macOS
+with Docker Desktop. We normalize all of those to ``localhost`` so test
+code does not have to know about the platform difference.
+"""
+
+from __future__ import annotations
+
+_LOOPBACK_ALIASES = {"", "0.0.0.0", "::", "::0"}
+
+
+def normalize_host(host: str | None) -> str:
+    """Map Docker's ``HostIp`` to a usable hostname for connecting back."""
+    if host is None:
+        return "localhost"
+    if host in _LOOPBACK_ALIASES:
+        return "localhost"
+    return host

pytest_testcontainers/containers.py

@@ -0,0 +1,181 @@
+"""Reuse lookup, atexit registration, Ryuk-disable choreography.
+
+Lives between the maker layer (which orchestrates lifecycle) and the
+underlying ``testcontainers-python`` / ``docker-py`` libraries.
+"""
+
+from __future__ import annotations
+
+import atexit
+import logging
+import threading
+import traceback
+from typing import TYPE_CHECKING, Any
+
+from pytest_testcontainers.errors import (
+    ContainerStartError,
+    ReuseConflictError,
+)
+
+if TYPE_CHECKING:
+    from testcontainers.core.container import DockerContainer
+
+logger = logging.getLogger("pytest_testcontainers")
+
+# --------------------------------------------------------------------------
+# Ryuk disable — idempotent, lazy
+# --------------------------------------------------------------------------
+_ryuk_lock = threading.Lock()
+_ryuk_disabled: bool = False
+
+
+def disable_ryuk_once() -> None:
+    """Flip ``testcontainers_config.ryuk_disabled = True`` exactly once.
+
+    Per §8.5: testcontainers-python does not spawn the Ryuk reaper at
+    import time; the flag must just be set before the first container's
+    ``.start()``. We do it lazily inside the maker so module import has
+    no side effects.
+    """
+    global _ryuk_disabled
+    with _ryuk_lock:
+        if _ryuk_disabled:
+            return
+        try:
+            from testcontainers.core.config import testcontainers_config
+        except ImportError:  # pragma: no cover — testcontainers is a hard dep
+            return
+        testcontainers_config.ryuk_disabled = True
+        _ryuk_disabled = True
+
+
+# --------------------------------------------------------------------------
+# atexit safety net — only fires when pytest_unconfigure is skipped
+# --------------------------------------------------------------------------
+_atexit_lock = threading.Lock()
+_atexit_callbacks: dict[int, Any] = {}  # id(container) -> bound callback
+
+
+def _make_atexit_stop(container: DockerContainer) -> Any:
+    def _cb() -> None:
+        try:
+            container.stop()
+        except Exception as exc:
+            # Common case: normal teardown already stopped+removed the
+            # container, so a Docker NotFound is expected and silent.
+            # Anything else gets printed (no re-raise — interpreter
+            # shutdown would discard the exception anyway). Per CLAUDE.md,
+            # this is the one suppress-exception pattern allowed; the
+            # narrowed branch + log make the rationale auditable.
+            try:
+                from docker.errors import NotFound
+            except ImportError:  # pragma: no cover
+                NotFound = ()  # type: ignore[assignment]
+            if not isinstance(exc, NotFound):
+                traceback.print_exc()
+
+    return _cb
+
+
+def register_atexit_stop(container: DockerContainer) -> None:
+    """Register an atexit callback that stops ``container`` exactly once."""
+    key = id(container)
+    with _atexit_lock:
+        if key in _atexit_callbacks:
+            return
+        cb = _make_atexit_stop(container)
+        _atexit_callbacks[key] = cb
+    atexit.register(cb)
+
+
+def deregister_atexit_stop(container: DockerContainer) -> None:
+    """Remove the atexit callback for ``container`` after normal cleanup."""
+    key = id(container)
+    with _atexit_lock:
+        cb = _atexit_callbacks.pop(key, None)
+    if cb is not None:
+        atexit.unregister(cb)
+
+
+# --------------------------------------------------------------------------
+# Reuse-by-name lookup
+# --------------------------------------------------------------------------
+def find_existing_container(name: str) -> Any | None:
+    """Return the docker-py container object for ``name``, or None.
+
+    "Found" includes any state — the caller decides what to do based on
+    ``container.status`` (``"running"``, ``"exited"``, ``"created"``,
+    ``"paused"``, …).
+    """
+    import docker
+    from docker.errors import NotFound
+
+    client = docker.from_env()
+    try:
+        container = client.containers.get(name)
+    except NotFound:
+        return None
+    return container
+
+
+def restart_stopped_or_raise(docker_container: Any, name: str) -> None:
+    """Bring a stopped/created/paused container back to running.
+
+    Raises :class:`ReuseConflictError` if Docker refuses to start it
+    (typically because the previously-mapped host port is now taken).
+    """
+    try:
+        docker_container.start()
+        docker_container.reload()
+    except Exception as exc:
+        raise ReuseConflictError(f"cannot start existing container {name!r}: {exc!r}") from exc
+
+
+def bind_to_running(
+    container_cls: type[DockerContainer],
+    docker_container: Any,
+    *constructor_args: Any,
+    **constructor_kwargs: Any,
+) -> DockerContainer:
+    """Build a ``testcontainers-python`` instance bound to a running container.
+
+    The instance is constructed but ``.start()`` is *not* called — instead
+    we set the private attributes that ``.start()`` would normally set
+    so that ``.get_container_host_ip()`` / ``.get_exposed_port()`` work
+    against the existing container.
+    """
+    instance = container_cls(*constructor_args, **constructor_kwargs)
+    # testcontainers-python's DockerContainer keeps the live wrapper as
+    # `_container`. After `.start()`, this attribute is the docker-py
+    # Container object; before, it's None.
+    instance._container = docker_container
+    return instance
+
+
+# --------------------------------------------------------------------------
+# Convenience wrapper: wrap a .start() call so failures convert cleanly
+# --------------------------------------------------------------------------
+def start_or_raise(container: DockerContainer, image_for_msg: str) -> None:
+    """Call ``container.start()`` and convert failures to ``ContainerStartError``."""
+    try:
+        container.start()
+    except Exception as exc:
+        log_tail = ""
+        try:
+            raw = container.get_logs() if hasattr(container, "get_logs") else None
+            if raw:
+                # testcontainers' get_logs returns (stdout, stderr) bytes
+                stdout = raw[0] if isinstance(raw, tuple) else raw
+                if isinstance(stdout, bytes):
+                    log_tail = stdout.decode(errors="replace")
+                else:
+                    log_tail = str(stdout)
+                # last 50 lines
+                log_tail = "\n".join(log_tail.splitlines()[-50:])
+        except Exception as log_exc:
+            logger.debug("could not retrieve container logs: %r", log_exc)
+
+        message = f"failed to start container (image={image_for_msg!r}): {exc!r}"
+        if log_tail:
+            message = f"{message}\n--- last 50 log lines ---\n{log_tail}"
+        raise ContainerStartError(message) from exc