pytest-testcontainers-django 0.2.0__py3-none-any.whl

pytest_testcontainers_django/__init__.py

@@ -0,0 +1,45 @@
+"""Bridge between ``pytest-testcontainers`` and ``pytest-django``.
+
+The pytest plugin auto-loads via the ``pytest11`` entry point declared
+in ``pyproject.toml`` — no ``-p`` flag or ``conftest.py`` import is
+required.  Most users only need to interact with the public surface
+re-exported here.
+
+See ``SPEC.md`` for the full design rationale (especially §6 on the
+hook-ordering timing dance).
+"""
+
+from __future__ import annotations
+
+from pytest_testcontainers_django._types import (
+    DjangoContainerConfig,
+    PostgresService,
+    RedisService,
+)
+from pytest_testcontainers_django.config import register
+from pytest_testcontainers_django.errors import (
+    BaselineMissingError,
+    ConfigError,
+    PytestTestcontainersDjangoError,
+    ReuseStaleContainerError,
+)
+
+__all__ = [
+    "BaselineMissingError",
+    "ConfigError",
+    "DjangoContainerConfig",
+    "PostgresService",
+    "PytestTestcontainersDjangoError",
+    "RedisService",
+    "ReuseStaleContainerError",
+    "register",
+]
+
+from importlib.metadata import PackageNotFoundError
+from importlib.metadata import version as _pkg_version
+
+try:
+    __version__ = _pkg_version("pytest-testcontainers-django")
+except PackageNotFoundError:  # pragma: no cover — only when running from a non-installed checkout
+    __version__ = "0.0.0+unknown"
+del PackageNotFoundError, _pkg_version

pytest_testcontainers_django/_types.py

@@ -0,0 +1,63 @@
+"""Public dataclasses used for programmatic configuration via :func:`register`.
+
+See SPEC §4.2 / §5. Default env-var names follow the ``DJANGO_DB_*`` /
+``DJANGO_REDIS_*`` prefix idiom (SPEC §5.1.3).
+"""
+
+from __future__ import annotations
+
+from dataclasses import dataclass, field
+from pathlib import Path
+
+DEFAULT_DB_ENV_NAMES: dict[str, str] = {
+    "host": "DJANGO_DB_HOST",
+    "port": "DJANGO_DB_PORT",
+    "name": "DJANGO_DB_NAME",
+    "user": "DJANGO_DB_USER",
+    "password": "DJANGO_DB_PASSWORD",
+    "test_template": "DJANGO_DB_TEST_TEMPLATE",
+}
+
+DEFAULT_REDIS_ENV_NAMES: dict[str, str] = {
+    "host": "DJANGO_REDIS_HOST",
+    "port": "DJANGO_REDIS_PORT",
+}
+
+
+@dataclass
+class PostgresService:
+    image: str = "postgres:16"
+    user: str = "postgres"
+    password: str = "postgres"
+    database: str = "postgres"
+    internal_port: int = 5432
+    template: str | None = None
+    init_scripts: list[Path] = field(default_factory=list)
+    env: dict[str, str] = field(default_factory=dict)
+    env_names: dict[str, str] = field(default_factory=lambda: dict(DEFAULT_DB_ENV_NAMES))
+
+
+@dataclass
+class RedisService:
+    image: str = "redis:7-alpine"
+    internal_port: int = 6379
+    env_names: dict[str, str] = field(default_factory=lambda: dict(DEFAULT_REDIS_ENV_NAMES))
+
+
+@dataclass
+class DjangoContainerConfig:
+    postgres: PostgresService = field(default_factory=PostgresService)
+    redis: RedisService | None = None
+    skip_dotenv_env: str = "DJANGO_SKIP_DOTENV"
+    disable_env: str = "PYTEST_TESTCONTAINERS_DISABLE"
+    reuse_env: str = "PYTEST_TESTCONTAINERS_REUSE"
+    use_django_pg_baseline: bool = False
+
+
+__all__ = [
+    "DEFAULT_DB_ENV_NAMES",
+    "DEFAULT_REDIS_ENV_NAMES",
+    "DjangoContainerConfig",
+    "PostgresService",
+    "RedisService",
+]

pytest_testcontainers_django/config.py

@@ -0,0 +1,232 @@
+"""Pyproject reader, ``register()`` API, validation.
+
+Resolution order (SPEC §5.1):
+
+1. ``register()`` value if ``conftest.py`` called it.
+2. ``[tool.pytest-testcontainers-django]`` table in nearest pyproject.toml.
+3. Built-in defaults from :mod:`pytest_testcontainers_django._types`.
+"""
+
+from __future__ import annotations
+
+import os
+import sys
+from dataclasses import replace
+from pathlib import Path
+from typing import Any
+
+if sys.version_info >= (3, 11):
+    import tomllib
+else:  # pragma: no cover — exercised on 3.10
+    import tomli as tomllib
+
+from pytest_testcontainers_django._types import (
+    DEFAULT_DB_ENV_NAMES,
+    DEFAULT_REDIS_ENV_NAMES,
+    DjangoContainerConfig,
+    PostgresService,
+    RedisService,
+)
+from pytest_testcontainers_django.errors import ConfigError
+
+_REGISTERED: DjangoContainerConfig | None = None
+
+
+def register(config: DjangoContainerConfig) -> None:
+    """Register a programmatic configuration from ``conftest.py``.
+
+    Overrides any ``[tool.pytest-testcontainers-django]`` pyproject table.
+    Last call wins (mostly relevant in test scenarios).
+    """
+    global _REGISTERED
+    if not isinstance(config, DjangoContainerConfig):
+        raise TypeError(
+            f"register() requires a DjangoContainerConfig instance, got {type(config).__name__}"
+        )
+    _REGISTERED = config
+
+
+def _reset_registered() -> None:
+    """Test-only helper. Not part of the public API."""
+    global _REGISTERED
+    _REGISTERED = None
+
+
+def _find_pyproject(start: Path) -> Path | None:
+    """Walk up from *start* looking for the nearest ``pyproject.toml``."""
+    current = start.resolve()
+    for candidate in [current, *current.parents]:
+        pyproject = candidate / "pyproject.toml"
+        if pyproject.is_file():
+            return pyproject
+    return None
+
+
+def _load_pyproject_table(pyproject: Path) -> dict[str, Any]:
+    with pyproject.open("rb") as fh:
+        data = tomllib.load(fh)
+    tool = data.get("tool", {})
+    return tool.get("pytest-testcontainers-django", {}) or {}
+
+
+def _resolve_init_scripts(raw: list[str | Path] | None, project_root: Path) -> list[Path]:
+    if not raw:
+        return []
+    out: list[Path] = []
+    for entry in raw:
+        path = Path(entry)
+        if not path.is_absolute():
+            path = project_root / path
+        out.append(path)
+    return out
+
+
+def _config_from_table(table: dict[str, Any], project_root: Path) -> DjangoContainerConfig:
+    """Translate a parsed ``[tool.pytest-testcontainers-django]`` table.
+
+    Unknown keys are ignored — TOML errors should be loud, but typos in
+    nested optional keys shouldn't break the plugin's bootstrap. (We do
+    raise on structurally impossible values, e.g. wrong types.)
+    """
+    db_env_names = dict(DEFAULT_DB_ENV_NAMES)
+    db_env_names_overrides = {
+        "host": table.get("db_host_env"),
+        "port": table.get("db_port_env"),
+        "name": table.get("db_name_env"),
+        "user": table.get("db_user_env"),
+        "password": table.get("db_password_env"),
+        "test_template": table.get("db_test_template_env"),
+    }
+    for key, value in db_env_names_overrides.items():
+        if value is not None:
+            db_env_names[key] = str(value)
+
+    postgres = PostgresService(
+        image=str(table.get("postgres_image", PostgresService.image)),
+        user=str(table.get("postgres_user", PostgresService.user)),
+        password=str(table.get("postgres_password", PostgresService.password)),
+        database=str(table.get("postgres_database", PostgresService.database)),
+        internal_port=int(table.get("postgres_internal_port", PostgresService.internal_port)),
+        template=(
+            str(table["postgres_template"]) if table.get("postgres_template") is not None else None
+        ),
+        init_scripts=_resolve_init_scripts(table.get("postgres_init_scripts"), project_root),
+        env=dict(table.get("postgres_env", {}) or {}),
+        env_names=db_env_names,
+    )
+
+    redis: RedisService | None = None
+    if table.get("redis_enabled", False):
+        redis_env_names = dict(DEFAULT_REDIS_ENV_NAMES)
+        if (override := table.get("redis_host_env")) is not None:
+            redis_env_names["host"] = str(override)
+        if (override := table.get("redis_port_env")) is not None:
+            redis_env_names["port"] = str(override)
+        redis = RedisService(
+            image=str(table.get("redis_image", RedisService.image)),
+            internal_port=int(table.get("redis_internal_port", RedisService.internal_port)),
+            env_names=redis_env_names,
+        )
+
+    return DjangoContainerConfig(
+        postgres=postgres,
+        redis=redis,
+        skip_dotenv_env=str(table.get("skip_dotenv_env", DjangoContainerConfig.skip_dotenv_env)),
+        disable_env=str(table.get("disable_env", DjangoContainerConfig.disable_env)),
+        reuse_env=str(table.get("reuse_env", DjangoContainerConfig.reuse_env)),
+        use_django_pg_baseline=bool(table.get("use_django_pg_baseline", False)),
+    )
+
+
+def load_config(rootdir: Path) -> DjangoContainerConfig:
+    """Load configuration. ``register()`` overrides pyproject; defaults fill gaps."""
+    if _REGISTERED is not None:
+        # register() expresses an override of *defaults*, not of pyproject;
+        # but per SPEC §4.2 the documented behavior is "register() wins" —
+        # so the registered config replaces the table wholesale.
+        return _REGISTERED
+
+    pyproject = _find_pyproject(rootdir)
+    if pyproject is None:
+        return DjangoContainerConfig()
+    table = _load_pyproject_table(pyproject)
+    return _config_from_table(table, project_root=pyproject.parent)
+
+
+def apply_template_default(config: DjangoContainerConfig) -> DjangoContainerConfig:
+    """SPEC §10.6: when init_scripts non-empty and template unset, default to ``database``.
+
+    Returns a (possibly) new config; never mutates the input.
+    """
+    pg = config.postgres
+    if pg.init_scripts and pg.template is None:
+        new_pg = replace(pg, template=pg.database)
+        return replace(config, postgres=new_pg)
+    return config
+
+
+def validate(config: DjangoContainerConfig) -> None:
+    """SPEC §5.6 validation.
+
+    Raises :class:`ConfigError` when the configuration is structurally bad.
+    """
+    pg = config.postgres
+    required_db_keys = {"host", "port", "name", "user", "password"}
+    missing = [k for k in required_db_keys if not pg.env_names.get(k)]
+    if missing:
+        raise ConfigError(f"PostgresService.env_names is missing required keys: {sorted(missing)}")
+
+    for path in pg.init_scripts:
+        if not path.is_file():
+            raise ConfigError(f"postgres_init_scripts entry does not exist: {path}")
+
+    if pg.template is not None and not pg.init_scripts:
+        raise ConfigError(
+            "postgres_template is set but postgres_init_scripts is empty — "
+            "cloning an empty template DB just slows test creation. "
+            "Either add init scripts or remove the template setting."
+        )
+
+    if config.redis is not None:
+        redis_env = config.redis.env_names
+        for key in ("host", "port"):
+            if not redis_env.get(key):
+                raise ConfigError(f"RedisService.env_names is missing required key: {key!r}")
+
+    if pg.internal_port <= 0 or pg.internal_port > 65535:
+        raise ConfigError(f"postgres_internal_port out of range: {pg.internal_port}")
+    if config.redis is not None and (
+        config.redis.internal_port <= 0 or config.redis.internal_port > 65535
+    ):
+        raise ConfigError(f"redis_internal_port out of range: {config.redis.internal_port}")
+
+
+def is_disabled(config: DjangoContainerConfig, args: list[str]) -> bool:
+    """Active by default. SPEC §6.5 step 5.
+
+    Disabled by ``--no-testcontainers`` CLI flag or by setting
+    ``config.disable_env`` to a truthy-falsy value (``1``, ``true``, ``yes``).
+    """
+    if "--no-testcontainers" in args:
+        return True
+    if not config.disable_env:
+        return False
+    raw = os.environ.get(config.disable_env, "").strip().lower()
+    return raw in {"1", "true", "yes", "on"}
+
+
+def is_reuse_enabled(config: DjangoContainerConfig) -> bool:
+    if not config.reuse_env:
+        return False
+    raw = os.environ.get(config.reuse_env, "").strip().lower()
+    return raw in {"1", "true", "yes", "on"}
+
+
+__all__ = [
+    "apply_template_default",
+    "is_disabled",
+    "is_reuse_enabled",
+    "load_config",
+    "register",
+    "validate",
+]

pytest_testcontainers_django/containers.py

@@ -0,0 +1,252 @@
+"""Container start/stop bridge.
+
+This is the only module that talks to ``testcontainers-python`` directly.
+The Django plugin code calls :func:`start_postgres` / :func:`start_redis`
+and gets back a small handle exposing ``host``, ``port``, ``stop()``.
+
+Why not simply call ``pytest_testcontainers.make_postgres``? Two
+practical reasons specific to the Django timing dance:
+
+* We need ``with_volume_mapping`` calls **before** ``.start()`` to mount
+  init scripts into ``/docker-entrypoint-initdb.d/`` (SPEC §10).  #1's
+  ``make_postgres`` doesn't expose pre-start mutation.
+* We want to detect "we attached to a pre-existing container" so we can
+  emit the SPEC §10.7 reuse warning.
+
+We *do* lean on #1 for: daemon ping (:class:`pytest_testcontainers.DockerNotRunningError`),
+atexit registration helpers, Ryuk-disable choreography, and
+named-container reuse lookup.  Those are imported from #1's surface so
+breakage is contained at one spot if #1 evolves.
+"""
+
+from __future__ import annotations
+
+import logging
+from dataclasses import dataclass
+from pathlib import Path
+from typing import Any
+
+from pytest_testcontainers import DockerNotRunningError
+from pytest_testcontainers.containers import (
+    bind_to_running,
+    deregister_atexit_stop,
+    disable_ryuk_once,
+    find_existing_container,
+    register_atexit_stop,
+    restart_stopped_or_raise,
+    start_or_raise,
+)
+from pytest_testcontainers.reuse import reuse_name_for
+
+from pytest_testcontainers_django.errors import ReuseStaleContainerError
+
+logger = logging.getLogger("pytest_testcontainers_django")
+
+
+@dataclass
+class ContainerHandle:
+    """Minimal handle returned by :func:`start_postgres` / :func:`start_redis`."""
+
+    host: str
+    port: int
+    name: str | None
+    is_bound_to_existing: bool
+    _instance: Any  # testcontainers DockerContainer; we only call .stop() on it
+    _owns_instance: bool  # False when bound to a pre-existing reuse container
+
+    def stop(self) -> None:
+        if not self._owns_instance:
+            return
+        deregister_atexit_stop(self._instance)
+        try:
+            self._instance.stop()
+        except Exception:
+            logger.exception("cleanup: container.stop() failed")
+
+
+def _check_daemon() -> None:
+    """Wrap #1's daemon ping so callers get a stable exception class."""
+    import docker
+    import docker.errors
+
+    try:
+        docker.from_env().ping()
+    except docker.errors.DockerException as exc:
+        raise DockerNotRunningError(str(exc)) from exc
+
+
+def _start_or_attach(
+    container: Any,
+    *,
+    reuse_name: str | None,
+) -> tuple[Any, bool]:
+    """Start *container*, or attach to a pre-existing one when reuse is on.
+
+    Returns ``(instance, is_bound_to_existing)``.  When bound to existing,
+    the caller MUST NOT register atexit stop and MUST NOT call ``stop()``.
+    """
+    if reuse_name is None:
+        return container, False
+
+    disable_ryuk_once()
+    existing = find_existing_container(reuse_name)
+    if existing is None:
+        container.with_name(reuse_name)
+        return container, False
+
+    container_cls = type(container)
+    status = getattr(existing, "status", "")
+    if status == "running":
+        return bind_to_running(container_cls, existing), True
+    if status in {"exited", "created", "paused"}:
+        restart_stopped_or_raise(existing, reuse_name)
+        return bind_to_running(container_cls, existing), True
+    # "dead" / "removing" / unknown: a fresh start would fail with a 409
+    # name conflict against the stale container, so surface an actionable
+    # error.  The user has to remove the stale container manually because
+    # we won't take destructive action on shared docker state.
+    raise ReuseStaleContainerError(
+        f"reuse-mode container {reuse_name!r} exists but is in state {status!r} — "
+        f"it cannot be restarted and starting a fresh container would conflict on "
+        f"the name. Remove it manually:\n"
+        f"  docker rm -f {reuse_name}"
+    )
+
+
+def start_postgres(
+    *,
+    image: str,
+    user: str,
+    password: str,
+    database: str,
+    internal_port: int,
+    env: dict[str, str],
+    init_scripts: list[Path],
+    reuse_name: str | None,
+) -> ContainerHandle:
+    """Construct + start (or attach to) a PostgresContainer."""
+    from testcontainers.postgres import PostgresContainer
+
+    _check_daemon()
+
+    container = PostgresContainer(
+        image=image,
+        username=user,
+        password=password,
+        dbname=database,
+        port=internal_port,
+        driver=None,
+    )
+    for key, value in env.items():
+        container.with_env(key, value)
+    for index, script in enumerate(init_scripts):
+        # SPEC §10.2: NN-name.sql, ordered.
+        container.with_volume_mapping(
+            str(script),
+            f"/docker-entrypoint-initdb.d/{index:02d}-{script.name}",
+            "ro",
+        )
+
+    instance, bound = _start_or_attach(container, reuse_name=reuse_name)
+    if bound:
+        host, port = _read_existing_host_port(instance, internal_port)
+        return ContainerHandle(
+            host=host,
+            port=port,
+            name=reuse_name,
+            is_bound_to_existing=True,
+            _instance=instance,
+            _owns_instance=False,
+        )
+
+    start_or_raise(instance, image)
+    if reuse_name is None:
+        register_atexit_stop(instance)
+
+    host = instance.get_container_host_ip()
+    port = int(instance.get_exposed_port(internal_port))
+    return ContainerHandle(
+        host=_normalize_host(host),
+        port=port,
+        name=reuse_name,
+        is_bound_to_existing=False,
+        _instance=instance,
+        _owns_instance=reuse_name is None,
+    )
+
+
+def start_redis(
+    *,
+    image: str,
+    internal_port: int,
+    reuse_name: str | None,
+) -> ContainerHandle:
+    """Construct + start (or attach to) a RedisContainer."""
+    from testcontainers.redis import RedisContainer
+
+    _check_daemon()
+
+    container = RedisContainer(image=image, port=internal_port)
+    instance, bound = _start_or_attach(container, reuse_name=reuse_name)
+    if bound:
+        host, port = _read_existing_host_port(instance, internal_port)
+        return ContainerHandle(
+            host=host,
+            port=port,
+            name=reuse_name,
+            is_bound_to_existing=True,
+            _instance=instance,
+            _owns_instance=False,
+        )
+
+    start_or_raise(instance, image)
+    if reuse_name is None:
+        register_atexit_stop(instance)
+
+    host = instance.get_container_host_ip()
+    port = int(instance.get_exposed_port(internal_port))
+    return ContainerHandle(
+        host=_normalize_host(host),
+        port=port,
+        name=reuse_name,
+        is_bound_to_existing=False,
+        _instance=instance,
+        _owns_instance=reuse_name is None,
+    )
+
+
+def _normalize_host(host: str) -> str:
+    if host in ("", "0.0.0.0"):
+        return "localhost"
+    return host
+
+
+def _read_existing_host_port(instance: Any, internal_port: int) -> tuple[str, int]:
+    """Read host/port from a docker-py container the testcontainers wrapper holds.
+
+    ``bind_to_running`` sets ``instance._container`` to the docker-py
+    Container object; that's where the port mapping lives.
+    """
+    docker_container = getattr(instance, "_container", None)
+    if docker_container is None:  # pragma: no cover — defensive
+        host = instance.get_container_host_ip()
+        port = int(instance.get_exposed_port(internal_port))
+        return _normalize_host(host), port
+    ports = docker_container.attrs["NetworkSettings"]["Ports"]
+    binding = (ports.get(f"{internal_port}/tcp") or [{}])[0]
+    host = binding.get("HostIp", "localhost")
+    return _normalize_host(host), int(binding["HostPort"])
+
+
+def reuse_name(service_slug: str) -> str:
+    """Compose a reuse-name for the eager-start path. Single-shared per controller."""
+    return reuse_name_for(service_slug)
+
+
+__all__ = [
+    "ContainerHandle",
+    "DockerNotRunningError",
+    "reuse_name",
+    "start_postgres",
+    "start_redis",
+]

pytest_testcontainers_django/errors.py

@@ -0,0 +1,31 @@
+"""Public exception classes."""
+
+from __future__ import annotations
+
+
+class PytestTestcontainersDjangoError(Exception):
+    """Base class for all errors raised by this plugin."""
+
+
+class ConfigError(PytestTestcontainersDjangoError):
+    """Raised when configuration is invalid (SPEC §5.6)."""
+
+
+class BaselineMissingError(PytestTestcontainersDjangoError):
+    """Raised when ``use_django_pg_baseline = true`` but ``django-pg-baseline`` is unavailable."""
+
+
+class ReuseStaleContainerError(PytestTestcontainersDjangoError):
+    """Raised when reuse mode finds a pre-existing container that can't be revived
+    (e.g. status ``dead``/``removing``).  Starting a fresh container with the same
+    name would fail with a Docker name conflict, so we surface a clear actionable
+    error instead.
+    """
+
+
+__all__ = [
+    "BaselineMissingError",
+    "ConfigError",
+    "PytestTestcontainersDjangoError",
+    "ReuseStaleContainerError",
+]