iris-devtester 1.9.3__py3-none-any.whl → 1.10.2__py3-none-any.whl

iris_devtester/__init__.py

@@ -26,7 +26,7 @@ LangChain Integration:
     ...     # Build your RAG app...
 """
 
-__version__ = "1.9.3"
+__version__ = "1.10.1"
 __author__ = "InterSystems Community"
 __license__ = "MIT"
 

iris_devtester/cli/__init__.py

@@ -13,9 +13,38 @@ from .fixture_commands import fixture
 @click.version_option(version=__version__, prog_name="iris-devtester")
 def main():
     """
-    iris-devtester - Battle-tested InterSystems IRIS infrastructure utilities.
-
-    Provides tools for container management, fixture handling, and testing.
+    iris-devtester - Python testing toolkit for InterSystems IRIS databases.
+
+    \b
+    WHAT THIS TOOL DOES:
+      Manages IRIS database containers, fixtures, and connections for testing.
+      Designed for CI/CD pipelines, local development, and AI agent automation.
+
+    \b
+    CONTAINER EDITIONS:
+      community   Full IRIS Community (~3.5GB) - default, all features
+      light       Minimal for CI/CD (~580MB) - SQL/DBAPI only, 6x smaller
+      enterprise  Licensed IRIS - requires iris.key file
+
+    \b
+    QUICK START:
+      iris-devtester container up                    # Start community
+      iris-devtester container up --edition light    # Start light (CI/CD)
+      iris-devtester container list                  # List containers
+      iris-devtester test-connection                 # Verify connectivity
+      iris-devtester container status                # Check health
+
+    \b
+    COMMON WORKFLOWS:
+      Local dev:    container up → test-connection → (your tests)
+      CI/CD:        container up --edition light → test-connection → pytest
+      Fixtures:     fixture load --fixture ./data → (verify data)
+
+    \b
+    FOR AI AGENTS:
+      All commands support --help for detailed options. Commands return
+      structured exit codes (0=success, 1=error, 2=not found, 5=timeout).
+      Use 'container list --format json' for machine-readable output.
     """
     pass
 

iris_devtester/cli/container.py

@@ -21,8 +21,23 @@ def container_group(ctx):
     """
     Container lifecycle management commands.
 
-    Manage IRIS containers from the command line with zero-config support.
-    Supports both Community and Enterprise editions.
+    \b
+    Manage IRIS database containers for testing and development.
+    Supports Community, Enterprise, and Light editions.
+
+    \b
+    EDITIONS:
+      community    Full IRIS Community Edition (~3.5GB, all features)
+      light        Minimal CI/CD image (~580MB, SQL/DBAPI only)
+      enterprise   Licensed IRIS (requires --license iris.key)
+
+    \b
+    QUICK START:
+      up              Create and start a container
+      list            Show running containers
+      status          Check container health
+      test-connection Verify database connectivity
+      stop/remove     Clean up containers
     """
     pass
 
@@ -37,6 +52,25 @@ def container_group(ctx):
     default=None,
     help="Container name (default: iris_db)",
 )
+@click.option(
+    "--edition",
+    type=click.Choice(["community", "enterprise", "light"], case_sensitive=False),
+    default="community",
+    help="IRIS edition: community (default), enterprise (requires license), light (minimal for CI/CD)",
+)
+@click.option(
+    "--image",
+    type=str,
+    default=None,
+    help="Custom Docker image (overrides --edition). Example: myregistry/iris:2024.1",
+)
+@click.option(
+    "--license",
+    "license_key",
+    type=click.Path(exists=True),
+    default=None,
+    help="Path to iris.key license file (required for enterprise edition)",
+)
 @click.option(
     "--detach/--no-detach",
     default=True,
@@ -47,37 +81,31 @@ def container_group(ctx):
 )
 @click.option("--cpf", help="Path to CPF merge file or raw CPF content")
 @click.pass_context
-def up(ctx, config, name, detach, timeout, cpf):
+def up(ctx, config, name, edition, image, license_key, detach, timeout, cpf):
     """
     Create and start IRIS container from configuration.
 
     Similar to docker-compose up. Creates a new container or starts existing one.
     Supports zero-config mode - works without any configuration file.
 
-    Container Lifecycle (Feature 011):
+    \b
+    Container Lifecycle:
       - Containers persist until explicitly removed with 'container remove'
       - Volume mounts are verified during creation
       - No automatic cleanup when CLI exits
 
     \b
     Examples:
-        # Zero-config (uses Community edition defaults)
         iris-devtester container up
-
-        # With custom container name
+        iris-devtester container up --edition light
+        iris-devtester container up --edition enterprise --license ./iris.key
+        iris-devtester container up --image myregistry/iris:2024.1
         iris-devtester container up --name my-test-db
-
-        # With custom configuration including volumes
         iris-devtester container up --config iris-config.yml
 
-        # Example iris-config.yml with volumes:
-        # edition: community
-        # volumes:
-        #   - ./workspace:/external/workspace
-        #   - ./config:/opt/config:ro
-
-        # Foreground mode (see logs)
-        iris-devtester container up --no-detach
+    \b
+    NOTE: For multi-container setups (sharding, mirroring, clusters),
+    use docker-compose instead. This tool manages single containers.
     """
     try:
         # Load configuration
@@ -99,6 +127,36 @@ def up(ctx, config, name, detach, timeout, cpf):
             container_config.container_name = name
             click.echo(f"  → Container name: {name}")
 
+        # Override image if provided via --image (takes precedence over --edition)
+        if image:
+            container_config.image = image
+            click.echo(f"  → Image: {image} (custom)")
+        # Override edition if provided via --edition (only if --image not set)
+        elif edition:
+            edition_lower = edition.lower()
+            container_config.edition = edition_lower
+
+            # Set appropriate image based on edition
+            if edition_lower == "light":
+                # Light edition: caretdev/iris-community-light (85% smaller)
+                container_config.image_tag = "latest-em"
+                click.echo(
+                    click.style(f"  → Edition: light", fg="cyan")
+                    + " (minimal for CI/CD, ~580MB vs ~3.5GB)"
+                )
+            elif edition_lower == "enterprise":
+                if not license_key:
+                    raise click.ClickException(
+                        "Enterprise edition requires --license option.\n"
+                        "\n"
+                        "Usage: iris-devtester container up --edition enterprise --license /path/to/iris.key"
+                    )
+                container_config.license_key = license_key
+                click.echo(f"  → Edition: enterprise")
+                click.echo(f"  → License: {license_key}")
+            else:
+                click.echo(f"  → Edition: community")
+
         if cpf:
             container_config.cpf_merge = cpf
             click.echo(f"  → CPF Merge: {cpf[:50]}...")
@@ -272,6 +330,141 @@ def up(ctx, config, name, detach, timeout, cpf):
         ctx.exit(1)
 
 
+@container_group.command(name="list")
+@click.option(
+    "--all", "-a", "show_all", is_flag=True, help="Show all containers (including stopped)"
+)
+@click.option(
+    "--format",
+    "output_format",
+    type=click.Choice(["table", "json"], case_sensitive=False),
+    default="table",
+    help="Output format (default: table)",
+)
+@click.pass_context
+def list_containers(ctx, show_all, output_format):
+    """
+    List IRIS containers.
+
+    Shows all IRIS containers managed by iris-devtester, with their status,
+    edition, ports, and age.
+
+    \b
+    Examples:
+        # List running containers
+        iris-devtester container list
+
+        # List all containers (including stopped)
+        iris-devtester container list --all
+
+        # JSON output for scripting
+        iris-devtester container list --format json
+    """
+    from datetime import datetime
+
+    import docker
+
+    try:
+        client = docker.from_env()
+
+        # Find IRIS containers (by image name patterns)
+        iris_patterns = [
+            "iris-community",
+            "intersystems/iris",
+            "caretdev/iris",
+            "intersystemsdc/iris",
+        ]
+
+        containers = client.containers.list(all=show_all)
+        iris_containers = []
+
+        for container in containers:
+            image_name = (
+                container.image.tags[0] if container.image.tags else str(container.image.id)[:12]
+            )
+
+            # Check if this is an IRIS container
+            is_iris = any(pattern in image_name.lower() for pattern in iris_patterns)
+            if not is_iris:
+                continue
+
+            # Determine edition from image name
+            if "light" in image_name.lower():
+                edition = "light"
+            elif "community" in image_name.lower():
+                edition = "community"
+            else:
+                edition = "enterprise"
+
+            # Get port mappings
+            ports = container.attrs.get("NetworkSettings", {}).get("Ports", {})
+            port_str = "-"
+            if ports and ports.get("1972/tcp"):
+                host_port = ports["1972/tcp"][0]["HostPort"]
+                port_str = f"{host_port}->1972"
+
+            # Calculate age
+            created = container.attrs.get("Created", "")
+            age_str = "unknown"
+            if created:
+                try:
+                    # Parse ISO format timestamp
+                    created_dt = datetime.fromisoformat(created.replace("Z", "+00:00"))
+                    now = datetime.now(created_dt.tzinfo)
+                    delta = now - created_dt
+                    if delta.days > 0:
+                        age_str = f"{delta.days}d"
+                    elif delta.seconds > 3600:
+                        age_str = f"{delta.seconds // 3600}h"
+                    else:
+                        age_str = f"{delta.seconds // 60}m"
+                except Exception:
+                    pass
+
+            iris_containers.append(
+                {
+                    "name": container.name,
+                    "edition": edition,
+                    "status": container.status,
+                    "ports": port_str,
+                    "age": age_str,
+                    "image": image_name,
+                }
+            )
+
+        if output_format == "json":
+            import json as json_module
+
+            click.echo(json_module.dumps(iris_containers, indent=2))
+        else:
+            # Table format
+            if not iris_containers:
+                click.echo("No IRIS containers found.")
+                if not show_all:
+                    click.echo("Use --all to include stopped containers.")
+            else:
+                # Print header
+                click.echo(f"{'NAME':<20} {'EDITION':<12} {'STATUS':<10} {'PORTS':<15} {'AGE':<6}")
+                click.echo("-" * 65)
+
+                for c in iris_containers:
+                    status_color = "green" if c["status"] == "running" else "yellow"
+                    click.echo(
+                        f"{c['name']:<20} "
+                        f"{c['edition']:<12} "
+                        f"{click.style(c['status'], fg=status_color):<19} "
+                        f"{c['ports']:<15} "
+                        f"{c['age']:<6}"
+                    )
+
+    except docker.errors.DockerException as e:
+        progress.print_error(f"Docker error: {e}")
+        ctx.exit(1)
+    except Exception as e:
+        progress.print_error(f"Error listing containers: {e}")
+        ctx.exit(1)
+
+
 @container_group.command(name="start")
 @click.argument("container_name", required=False, default="iris_db")
 @click.option(
@@ -657,7 +850,7 @@ def remove(ctx, container_name, force, volumes):
 
 
 @container_group.command(name="reset-password")
-@click.argument("container_name")
+@click.argument("container_name", required=False, default="iris_db")
 @click.option("--user", default="_SYSTEM", help="Username to reset password for (default: _SYSTEM)")
 @click.option("--password", default="SYS", help="New password (default: SYS)")
 @click.option(
@@ -723,7 +916,7 @@ def reset_password_cmd(ctx, container_name, user, password, port):
 
 
 @container_group.command(name="test-connection")
-@click.argument("container_name")
+@click.argument("container_name", required=False, default="iris_db")
 @click.option(
     "--namespace", default="USER", help="IRIS namespace to test connection to (default: USER)"
 )
@@ -812,7 +1005,7 @@ def test_connection_cmd(ctx, container_name, namespace, username, password):
 
 
 @container_group.command(name="enable-callin")
-@click.argument("container_name")
+@click.argument("container_name", required=False, default="iris_db")
 @click.option(
     "--timeout", type=int, default=30, help="Timeout in seconds for docker commands (default: 30)"
 )

iris_devtester/config/container_config.py

@@ -51,7 +51,7 @@ class ContainerConfig(BaseModel):
         ... )
     """
 
-    edition: Literal["community", "enterprise"] = Field(
+    edition: Literal["community", "enterprise", "light"] = Field(
         default="community", description="IRIS edition to use"
     )
     container_name: str = Field(
@@ -245,15 +245,21 @@ class ContainerConfig(BaseModel):
         return cls()
 
     def get_image_name(self) -> str:
+        """Get the Docker image name based on edition and configuration."""
         if self.image:
             return self.image
 
         if self.edition == "community":
-
-            # Bug Fix #1: Community images use 'intersystemsdc/' prefix on Docker Hub
+            # Community images use 'intersystemsdc/' prefix on Docker Hub
             return f"intersystemsdc/iris-community:{self.image_tag}"
+        elif self.edition == "light":
+            # Light edition: caretdev/iris-community-light (85% smaller)
+            # Use latest-em for LTS stability
+            tag = self.image_tag if self.image_tag != "latest" else "latest-em"
+            return f"caretdev/iris-community-light:{tag}"
         else:
-            return f"intersystems/iris:{self.image_tag}"
+            # Enterprise edition
+            return f"containers.intersystems.com/intersystems/iris:{self.image_tag}"
 
     def validate_volume_paths(self) -> List[str]:
         """

iris_devtester/containers/iris_container.py

@@ -5,6 +5,7 @@ from typing import Any, Optional
 
 from iris_devtester.config import IRISConfig
 from iris_devtester.connections import get_connection
+from iris_devtester.containers.models import HealthCheckLevel, ValidationResult
 
 logger = logging.getLogger(__name__)
 
@@ -59,6 +60,9 @@ class IRISContainer(IRISBase):
     Enhanced IRIS container with automatic connection and password management.
     """
 
+    # Custom kwargs that should NOT be passed to parent/Docker SDK
+    _CUSTOM_KWARGS = {"port_registry", "preferred_port", "project_path"}
+
     def __init__(
         self,
         image: str = "intersystemsdc/iris-community:latest",
@@ -70,6 +74,12 @@ class IRISContainer(IRISBase):
         if not HAS_TESTCONTAINERS:
             logger.warning("testcontainers not installed. Functionality will be limited.")
 
+        # Extract custom kwargs before passing to parent
+        self._port_registry = kwargs.pop("port_registry", None)
+        self._preferred_port = kwargs.pop("preferred_port", None)
+        self._project_path = kwargs.pop("project_path", None)
+        self._port_assignment = None  # Will be set in start() if port_registry is used
+
         super().__init__(image=image, **kwargs)
         self._username = username
         self._password = password
@@ -94,30 +104,176 @@ class IRISContainer(IRISBase):
         self._preconfigure_username: Optional[str] = None
 
     @classmethod
-    def community(cls, image: Optional[str] = None, **kwargs) -> "IRISContainer":
-        """Create a Community Edition container."""
+    def community(
+        cls, image: Optional[str] = None, version: str = "latest", **kwargs
+    ) -> "IRISContainer":
+        """
+        Create a Community Edition container.
+
+        Auto-detects architecture (ARM64 vs x86) and pulls the appropriate image.
+
+        Args:
+            image: Docker image to use. If None, auto-detects based on architecture.
+            version: Image version tag. Options: 'latest', '2025.1', '2025.2', etc.
+        """
         if image is None:
             import platform as platform_module
 
             if platform_module.machine() == "arm64":
-                image = "containers.intersystems.com/intersystems/iris-community:2025.1"
+                # ARM64 (Apple Silicon) - use official InterSystems registry
+                tag = version if version != "latest" else "2025.1"
+                image = f"containers.intersystems.com/intersystems/iris-community:{tag}"
             else:
-                image = "intersystemsdc/iris-community:latest"
+                # x86_64 - use Docker Hub community image
+                image = f"intersystemsdc/iris-community:{version}"
         return cls(image=image, **kwargs)
 
     @classmethod
-    def enterprise(cls, license_key: str, image: Optional[str] = None, **kwargs) -> "IRISContainer":
-        """Create an Enterprise Edition container."""
+    def enterprise(
+        cls, license_key: Optional[str] = None, image: Optional[str] = None, **kwargs
+    ) -> "IRISContainer":
+        """
+        Create an Enterprise Edition container.
+
+        Args:
+            license_key: Path to iris.key file. If None, checks IRIS_LICENSE_KEY env var.
+            image: Docker image to use. Defaults to containers.intersystems.com/intersystems/iris:latest
+
+        Raises:
+            ValueError: If no license key is provided or found in environment.
+        """
+        import os
+
+        if license_key is None:
+            license_key = os.environ.get("IRIS_LICENSE_KEY")
+
+        if license_key is None:
+            raise ValueError(
+                "Enterprise edition requires a license key.\n"
+                "\n"
+                "Provide license_key parameter or set IRIS_LICENSE_KEY environment variable:\n"
+                "  IRISContainer.enterprise(license_key='/path/to/iris.key')\n"
+                "  # or\n"
+                "  export IRIS_LICENSE_KEY=/path/to/iris.key"
+            )
+
+        if not os.path.exists(license_key):
+            raise ValueError(
+                f"License key file not found: {license_key}\n"
+                "\n"
+                "Verify the license key path exists and is readable."
+            )
+
         if image is None:
             image = "containers.intersystems.com/intersystems/iris:latest"
+
         container = cls(image=image, **kwargs)
+        # Mount license key into container
+        container._license_key_path = license_key
         return container
 
+    @classmethod
+    def light(
+        cls, image: Optional[str] = None, version: str = "latest", **kwargs
+    ) -> "IRISContainer":
+        """
+        Create a Light Edition container optimized for CI/CD.
+
+        Light edition is ~85% smaller than full Community edition (~580MB vs ~3.5GB).
+        It removes Interoperability, Management Portal, DeepSee, and web components.
+        DBAPI, JDBC, and ODBC connectivity are fully supported.
+
+        Args:
+            image: Docker image to use. Defaults to caretdev/iris-community-light.
+            version: Image version tag. Options: 'latest', 'latest-em' (LTS), '2025.1', etc.
+
+        Best for:
+            - CI/CD pipelines
+            - Microservices
+            - Automated testing
+            - SQL-only workloads
+
+        Not supported:
+            - Interoperability/Ensemble
+            - Management Portal
+            - DeepSee/BI
+            - CSP/REST web framework
+        """
+        if image is None:
+            # Use latest-em for LTS stability, or allow version override
+            tag = version if version != "latest" else "latest-em"
+            image = f"caretdev/iris-community-light:{tag}"
+        return cls(image=image, **kwargs)
+
     def with_name(self, name: str) -> "IRISContainer":
         """Set the container name."""
         self._container_name = name
-        if hasattr(self, "with_kwargs"):
-            self.with_kwargs(name=name)
+        # Use parent's _name attribute directly - do NOT use with_kwargs(name=...)
+        # as that causes duplicate 'name' kwarg in Docker's run() call
+        # (parent passes both name=self._name and **self._kwargs to run())
+        self._name = name
+        return self
+
+    def with_cpf_merge(self, cpf_content_or_path: str) -> "IRISContainer":
+        """Configure CPF merge for IRIS startup customization.
+
+        CPF merge allows customizing IRIS configuration at startup time
+        using a merge file that is applied during container initialization.
+        This enables features like:
+        - Enabling CallIn service automatically
+        - Setting memory configuration
+        - Pre-configuring users and security settings
+
+        Args:
+            cpf_content_or_path: Either a CPF merge content string or a
+                path to a CPF merge file. If the string contains newlines
+                or CPF section markers like "[Actions]", it's treated as
+                content. Otherwise, it's treated as a file path.
+
+        Returns:
+            Self for method chaining.
+
+        Examples:
+            >>> # From preset content
+            >>> iris = IRISContainer.community().with_cpf_merge(CPFPreset.ENABLE_CALLIN)
+
+            >>> # From file path
+            >>> iris = IRISContainer.community().with_cpf_merge("/path/to/merge.cpf")
+        """
+        import os
+        import tempfile
+
+        # Determine if it's content or a file path
+        is_content = "\n" in cpf_content_or_path or "[" in cpf_content_or_path
+
+        if is_content:
+            # Write content to a temporary file
+            # Note: The temp file needs to persist until container is started
+            if not hasattr(self, "_cpf_temp_files"):
+                self._cpf_temp_files = []
+
+            fd, temp_path = tempfile.mkstemp(suffix=".cpf", prefix="iris_merge_")
+            os.write(fd, cpf_content_or_path.encode("utf-8"))
+            os.close(fd)
+            self._cpf_temp_files.append(temp_path)
+            host_path = temp_path
+        else:
+            # Treat as file path
+            host_path = os.path.abspath(cpf_content_or_path)
+            if not os.path.exists(host_path):
+                raise FileNotFoundError(f"CPF merge file not found: {host_path}")
+
+        # Container path for the merge file
+        container_path = "/tmp/merge.cpf"
+
+        # Mount the CPF file into the container
+        if hasattr(self, "with_volume_mapping"):
+            self.with_volume_mapping(host_path, container_path, "ro")
+
+        # Set the environment variable to tell IRIS to use the merge file
+        if hasattr(self, "with_env"):
+            self.with_env("ISC_CPF_MERGE_FILE", container_path)
+
         return self
 
     def get_container_name(self) -> str:
@@ -222,14 +378,19 @@ class IRISContainer(IRISBase):
         self.execute_objectscript(script, namespace="%SYS")
 
     def get_config(self) -> IRISConfig:
-        """Get connection configuration."""
-        if self._config is None:
-            self._config = IRISConfig(
-                username=self._username,
-                password=self._password,
-                namespace=self._namespace,
-                container_name=self.get_container_name(),
-            )
+        """Get connection configuration.
+
+        Note: Credentials are always read fresh from _username/_password
+        to support credential updates after container start.
+        """
+        # Always create fresh config to pick up any credential changes
+        # (e.g., conftest may update _username/_password after start())
+        self._config = IRISConfig(
+            username=self._username,
+            password=self._password,
+            namespace=self._namespace,
+            container_name=self.get_container_name(),
+        )
         config = self._config
         try:
             # Get host and mapped port from testcontainers
@@ -297,20 +458,91 @@ class IRISContainer(IRISBase):
         return self
 
     def start(self) -> "IRISContainer":
-        """Start container with pre-config support."""
+        """Start container with pre-config support and port registry integration."""
         if self._preconfigure_password:
             self.with_env("IRIS_PASSWORD", self._preconfigure_password)
         if self._preconfigure_username:
             self.with_env("IRIS_USERNAME", self._preconfigure_username)
 
+        # Port registry integration: assign port before starting
+        if self._port_registry is not None and self._project_path is not None:
+            from iris_devtester.ports import PortAssignment
+
+            self._port_assignment = self._port_registry.assign_port(
+                project_path=self._project_path,
+                preferred_port=self._preferred_port,
+            )
+            # Configure container to use the assigned port
+            # Note: testcontainers uses with_bind_ports() for port mapping
+            if hasattr(self, "with_bind_ports"):
+                self.with_bind_ports(1972, self._port_assignment.port)
+
         super().start()
         # Ensure host/port are updated after start
         self.get_config()
         self._password_preconfigured = True
         return self
 
+    def get_assigned_port(self) -> Optional[int]:
+        """
+        Get the port assigned by the port registry.
+
+        Returns:
+            The assigned port number, or None if no port registry was used.
+        """
+        if hasattr(self, "_port_assignment") and self._port_assignment is not None:
+            return self._port_assignment.port
+        return None
+
+    def get_project_path(self) -> Optional[str]:
+        """
+        Get the project path associated with this container.
+
+        Returns:
+            The project path, or None if no port registry was used.
+        """
+        return self._project_path
+
     def wait_for_ready(self, timeout: int = 60) -> bool:
         """Wait for IRIS to be ready."""
         # Simple wait for prototype
         time.sleep(15)
         return True
+
+    def validate(self, level: HealthCheckLevel = HealthCheckLevel.STANDARD) -> ValidationResult:
+        """Validate this container's health status.
+
+        Args:
+            level: Validation depth level (MINIMAL, STANDARD, or FULL).
+
+        Returns:
+            ValidationResult with success status, details, and remediation steps.
+
+        Examples:
+            >>> with IRISContainer.community() as iris:
+            ...     result = iris.validate()
+            ...     assert result.success is True
+        """
+        # Import here to avoid circular import
+        from iris_devtester.containers.validation import validate_container
+
+        container_name = self.get_container_name()
+        return validate_container(container_name=container_name, level=level)
+
+    def assert_healthy(self, level: HealthCheckLevel = HealthCheckLevel.STANDARD) -> None:
+        """Assert that this container is healthy, raising RuntimeError if not.
+
+        Args:
+            level: Validation depth level (MINIMAL, STANDARD, or FULL).
+
+        Raises:
+            RuntimeError: If container validation fails, with structured error
+                message including "What went wrong" and "How to fix it" sections.
+
+        Examples:
+            >>> with IRISContainer.community() as iris:
+            ...     iris.assert_healthy()  # No exception = healthy
+        """
+        result = self.validate(level=level)
+        if not result.success:
+            raise RuntimeError(result.format_message())

iris_devtester/fixtures/__init__.py

@@ -1,17 +1,23 @@
-"""IRIS .DAT Fixture Management.
+"""IRIS Fixture Management.
 
 This module provides tools for creating, loading, and validating IRIS database
-fixtures stored as .DAT files. Fixtures enable fast, reproducible test data
-setup by exporting database namespaces to version-controlled files.
+fixtures. Fixtures enable fast, reproducible test data setup by exporting
+database namespaces to version-controlled files.
 
 Key Features:
-- Create fixtures from IRIS namespaces (entire database backup)
-- Load fixtures via namespace mounting (<1 second)
+- Create fixtures from IRIS namespaces (globals + class definitions)
+- Load fixtures via global import (<1 second for most fixtures)
 - Validate fixture integrity with SHA256 checksums
 - CLI commands for fixture management
 
+Fixture Format:
+    Fixtures are stored as directories containing:
+    - manifest.json: Metadata, checksums, and table information
+    - globals.gof: Global data in IRIS %GOF format
+    - classes.xml: Class definitions (optional, for SQL tables)
+
 Example:
-    >>> from iris_devtester.fixtures import DATFixtureLoader, FixtureCreator
+    >>> from iris_devtester.fixtures import FixtureLoader, FixtureCreator
     >>>
     >>> # Create fixture from existing namespace
     >>> creator = FixtureCreator(container=iris_container)
@@ -22,7 +28,7 @@ Example:
     ... )
     >>>
     >>> # Load fixture into new namespace
-    >>> loader = DATFixtureLoader(container=iris_container)
+    >>> loader = FixtureLoader(container=iris_container)
     >>> target_ns = iris_container.get_test_namespace(prefix="LOADED")
     >>> result = loader.load_fixture(
     ...     fixture_path="./fixtures/test-data",
@@ -35,7 +41,7 @@ pytest Integration:
 
         @pytest.fixture
         def loaded_fixture(iris_container):
-            loader = DATFixtureLoader(container=iris_container)
+            loader = FixtureLoader(container=iris_container)
             target_ns = iris_container.get_test_namespace(prefix="TEST")
             result = loader.load_fixture(
                 fixture_path="./fixtures/test-data",
@@ -53,7 +59,7 @@ pytest Integration:
 __version__ = "0.1.0"
 
 from .creator import FixtureCreator
-from .loader import DATFixtureLoader
+from .loader import FixtureLoader
 
 # Import data models and exceptions
 from .manifest import (
@@ -83,6 +89,9 @@ from .obj_export import (
 # Import validator, loader, and creator
 from .validator import FixtureValidator
 
+# Backward compatibility alias
+DATFixtureLoader = FixtureLoader
+
 # Public API
 __all__ = [
     # Data models
@@ -98,8 +107,10 @@ __all__ = [
     "ChecksumMismatchError",
     # Classes
     "FixtureValidator",
-    "DATFixtureLoader",
+    "FixtureLoader",
     "FixtureCreator",
+    # Backward compatibility
+    "DATFixtureLoader",
     # $SYSTEM.OBJ utilities (Feature 017)
     "ExportResult",
     "ImportResult",

iris_devtester/fixtures/creator.py

@@ -17,7 +17,12 @@ from .validator import FixtureValidator
 
 class FixtureCreator:
     """
-    Creates .DAT fixtures by exporting IRIS namespaces.
+    Creates IRIS fixtures by exporting namespace globals and class definitions.
+
+    Fixture Format:
+        - globals.gof: Global data in IRIS %GOF format
+        - classes.xml: Class definitions for SQL tables
+        - manifest.json: Metadata and checksums
     """
 
     def __init__(
@@ -64,7 +69,12 @@ class FixtureCreator:
         from iris_devtester.config import discover_config
         from iris_devtester.connections import get_connection as get_conn_factory
 
-        base_config = self.connection_config or discover_config()
+        # Use container's config if available, otherwise fall back to discovery
+        base_config = self.connection_config
+        if base_config is None and self.container is not None:
+            base_config = self.container.get_config()
+        if base_config is None:
+            base_config = discover_config()
         ns_config = dataclasses.replace(base_config, namespace=namespace)
 
         ns_connection = get_conn_factory(ns_config)
@@ -223,7 +233,12 @@ class FixtureCreator:
                 get_connection as get_modern_connection,
             )
 
-            self._connection = get_modern_connection(self.connection_config)
+            # If container is provided but no explicit connection_config, use container's config
+            config = self.connection_config
+            if config is None and self.container is not None:
+                config = self.container.get_config()
+
+            self._connection = get_modern_connection(config)
         return self._connection
 
     def _get_iris_version(self) -> str:

iris_devtester/fixtures/loader.py

@@ -12,7 +12,7 @@ from .manifest import FixtureLoadError, FixtureManifest, FixtureValidationError,
 logger = logging.getLogger(__name__)
 
 
-class DATFixtureLoader:
+class FixtureLoader:
 
     def __init__(self, container: Optional[IRISContainer] = None, **kwargs):
         self.container = container
@@ -45,14 +45,17 @@ class DATFixtureLoader:
     ) -> LoadResult:
         start_time = time.time()
 
+        # Validate fixture exists BEFORE starting a container (Fail Fast)
+        manifest = self._load_manifest(fixture_path)
+
         if not self.container:
             self.container = IRISContainer.community()
             self.container.start()
             self._owns_container = True
 
         try:
-            manifest = self._load_manifest(fixture_path)
             namespace = target_namespace or manifest.namespace
+            # Note: manifest already loaded above (fail-fast before container start)
 
             dat_file_path = Path(fixture_path) / "IRIS.DAT"
             if not dat_file_path.exists():

iris_devtester/fixtures/manifest.py

@@ -1,7 +1,13 @@
 """Fixture manifest data models and validation.
 
-This module defines the data structures for IRIS .DAT fixture manifests,
+This module defines the data structures for IRIS fixture manifests,
 including FixtureManifest, TableInfo, ValidationResult, and LoadResult.
+
+Fixture Format:
+    Fixtures are stored as directories containing:
+    - manifest.json: Metadata, checksums, and table information
+    - globals.gof: Global data in IRIS %GOF format
+    - classes.xml: Class definitions (optional, for SQL tables)
 """
 
 import json
@@ -46,7 +52,6 @@ class TableInfo:
     """
     Information about a single table in a fixture.
 
-    Note: All tables are stored in a single IRIS.DAT file.
     This class tracks which tables are included in the fixture.
 
     Attributes:
@@ -69,11 +74,12 @@ class TableInfo:
 @dataclass
 class FixtureManifest:
     """
-    Manifest describing a .DAT fixture.
+    Manifest describing an IRIS fixture.
 
     A fixture is a directory containing:
     - manifest.json (this schema)
-    - IRIS.DAT (single database file containing all tables)
+    - globals.gof (global data in %GOF format)
+    - classes.xml (optional, class definitions for SQL tables)
 
     Example manifest.json:
     {
@@ -93,6 +99,9 @@ class FixtureManifest:
         }
       ]
     }
+
+    Note: The dat_file field is kept for backward compatibility but the actual
+    data is stored in globals.gof (GOF format).
     """
 
     # Required fields

iris_devtester/fixtures/validator.py

@@ -1,7 +1,13 @@
-"""IRIS .DAT Fixture Validator.
+"""IRIS Fixture Validator.
 
 This module provides the FixtureValidator class for validating fixture
 integrity including manifest structure, file existence, and SHA256 checksums.
+
+Fixture Format:
+    Fixtures are stored as directories containing:
+    - manifest.json: Metadata, checksums, and table information
+    - globals.gof: Global data in IRIS %GOF format
+    - classes.xml: Class definitions (optional, for SQL tables)
 """
 
 import hashlib
@@ -18,11 +24,11 @@ from .manifest import (
 
 class FixtureValidator:
     """
-    Validates .DAT fixture integrity.
+    Validates fixture integrity.
 
     This is a stateless validator that checks:
     - Manifest structure and required fields
-    - File existence (manifest.json, IRIS.DAT)
+    - File existence (manifest.json, globals.gof)
     - SHA256 checksum matching
     - Fixture size statistics
 

{iris_devtester-1.9.3.dist-info → iris_devtester-1.10.2.dist-info}/METADATA

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: iris-devtester
-Version: 1.9.3
+Version: 1.10.2
 Summary: Battle-tested InterSystems IRIS infrastructure utilities for Python development
 Author-email: InterSystems Community <community@intersystems.com>
 Maintainer-email: Thomas Dyar <thomas.dyar@intersystems.com>
@@ -107,9 +107,17 @@ def test_connection():
         assert cursor.fetchone()[0] == 1
 ```
 
-## Container API
+## Container Editions
 
-### Basic Usage
+Three canonical container editions are available:
+
+| Edition | Size | Use Case | Image |
+|---------|------|----------|-------|
+| **Community** | ~972MB | Development, testing | `intersystemsdc/iris-community` |
+| **Enterprise** | ~1GB+ | Production testing | `containers.intersystems.com/intersystems/iris` |
+| **Light** | **~580MB** | CI/CD pipelines | `caretdev/iris-community-light` |
+
+### Python API
 ```python
 from iris_devtester.containers import IRISContainer
 
@@ -117,11 +125,42 @@ from iris_devtester.containers import IRISContainer
 with IRISContainer.community() as iris:
     conn = iris.get_connection()
 
+# Light Edition (85% smaller, for CI/CD)
+with IRISContainer.light() as iris:
+    conn = iris.get_connection()
+
 # Enterprise Edition (requires license)
 with IRISContainer.enterprise(license_key="/path/to/iris.key") as iris:
     conn = iris.get_connection()
+
+# Specify version
+with IRISContainer.community(version="2025.1") as iris:
+    conn = iris.get_connection()
+```
+
+### CLI Usage
+```bash
+# Community (default)
+iris-devtester container up
+
+# Light edition for CI/CD
+iris-devtester container up --edition light
+
+# Enterprise edition with license
+iris-devtester container up --edition enterprise --license /path/to/iris.key
+
+# List running IRIS containers
+iris-devtester container list
 ```
 
+### Light Edition Details
+
+The Light edition removes components unnecessary for SQL-only workloads:
+- **Removed**: Interoperability/Ensemble, Management Portal, DeepSee/BI, CSP/REST
+- **Kept**: SQL engine, DBAPI, JDBC, ODBC, SQLAlchemy-IRIS support
+
+Perfect for microservices, automated testing, and Python/SQL pipelines.
+
 ### Builder Methods
 ```python
 # Set a custom container name (for debugging, logs, multiple containers)

{iris_devtester-1.9.3.dist-info → iris_devtester-1.10.2.dist-info}/RECORD

@@ -1,13 +1,13 @@
-iris_devtester/__init__.py,sha256=HzbADwcjJamdWENJTE4FaervonOKGTfKdxU8VkG_kcM,1848
-iris_devtester/cli/__init__.py,sha256=yakDJH-EsnTBmKl_K7r2n47EDiWvfpwLVcY11KriQQQ,691
+iris_devtester/__init__.py,sha256=7Ud7QRVdnZQ205YQ02_a-OFoKidWXBeTS9peUW6u60g,1849
+iris_devtester/cli/__init__.py,sha256=Gs11Sj_v4OaKWBf2-dCaUB7RwXSxwGcuYjn8rHgsnRU,1914
 iris_devtester/cli/__main__.py,sha256=YgFAn0Q02AXgXRwAg70MR3U0IIjFHUSz38h5tPFJnGg,125
 iris_devtester/cli/connection_commands.py,sha256=cabAufSsrrhwpxlPZFlsE-5Zi54176eGdJOApPLdZXA,11467
-iris_devtester/cli/container.py,sha256=FcDb6EiSa8SYvzsntxu5j5q6PCh1jba7wosd_KUqe0U,30736
+iris_devtester/cli/container.py,sha256=ZVWmoxCzZPezjSNPQZRJLdGmeJCJzs7yw_iqK-UVt-Y,37763
 iris_devtester/cli/container_commands.py,sha256=lOxa2TXnBK1ATCIzbbXexk-p0lItStUwU_gKVnv_p1w,4451
 iris_devtester/cli/fixture_commands.py,sha256=w1n6MIujQsY46ZKG_L0aRF4lhohWh5dOrF0lgH_K3r0,17493
 iris_devtester/config/__init__.py,sha256=acRVXpdKAp7lkZzrpKGnOYLgSfkxN3kpL1RU0b0hhlM,486
 iris_devtester/config/auto_discovery.py,sha256=y1BD26rfEut1vjw77IXh0yel95BaUvMfMxzskIPPQec,10638
-iris_devtester/config/container_config.py,sha256=UNtgjfWlO517KzH0upwpx1xBWpyvhXIZQmxRQ-OKLNI,10925
+iris_devtester/config/container_config.py,sha256=RsxfMIi9SF5tnmIAl_srASZrZrFSaV8BCxlFfMusYcQ,11353
 iris_devtester/config/container_state.py,sha256=O2i69oVj_B1NQRZqmPKPdjmYwonhPD0QLe1UZmGupI4,11218
 iris_devtester/config/defaults.py,sha256=RgQal0IeDr215KIy6ZToDrsOdV4DwVJvMJE2SgAzVA4,1846
 iris_devtester/config/discovery.py,sha256=7R64ykibns6N2W9hNZlg_8CQqpNwiWSITl6G72VnNws,5879
@@ -24,19 +24,19 @@ iris_devtester/connections/models.py,sha256=rfKCFtm86wQZAv_cLOVS6N7P5vGlfkInSHbs
 iris_devtester/connections/retry.py,sha256=FxNhlTA2RHI2ayvEF5w7P_EjO7k6xKgeA3mplJd3-co,2893
 iris_devtester/containers/__init__.py,sha256=quWN4CtxRUMje8QkpZWMY79XlVOSM79HF5ewHLNz5YA,729
 iris_devtester/containers/cpf_manager.py,sha256=GBkuM5mPw85lo7djINlTNkrQ8bGgRe2QEWv7YQQL6KU,1969
-iris_devtester/containers/iris_container.py,sha256=GA9fgcjU0nLJnSP-PnZDWVMZcwOR7s45ZHK5pNxgYok,11083
+iris_devtester/containers/iris_container.py,sha256=VdxX88785sY6WEj-NtV-BjTrhVpd2lXvMzzMX8xJORw,20276
 iris_devtester/containers/models.py,sha256=f66fwQjlmw1Sl4M33QlglCv4ewNtk4TJLXXcmhNsbDA,13693
 iris_devtester/containers/monitor_utils.py,sha256=cCsLp1cZYAbMmj7o6tUYhVurMEE7GOOe9Y5FLAxl6hM,4917
 iris_devtester/containers/monitoring.py,sha256=E4v-5VW-_W7CVSRm_ryzpOfLQgP9NZ6WN7GYglsAFro,41172
 iris_devtester/containers/performance.py,sha256=fNLUqsTDgPrIBb2sP2ubVPM5oVconrXA1cn6Bq_2JvM,11272
 iris_devtester/containers/validation.py,sha256=SUOsEc2UPHJTYosSweSmF8pcDLYnrvXZNOaApTu7PQc,14564
 iris_devtester/containers/wait_strategies.py,sha256=cUJNU8eD8EWKSaQvEWqkCKkBPCotnT_NBrw2J70ZXVA,7754
-iris_devtester/fixtures/__init__.py,sha256=HwE6nEBqFXMpQNjFZ1EdTp7w8KpdChtLx5hkGzm6tzQ,3149
-iris_devtester/fixtures/creator.py,sha256=sA3y_SjF4XmMICQ2V2n1pHrfcYspMqa1SOb_koV1yLM,8019
-iris_devtester/fixtures/loader.py,sha256=2o15QC9lHmf7C3Ce9PrPuagQdqo1OKRvoyuN_pKUj3o,12493
-iris_devtester/fixtures/manifest.py,sha256=ulLcMw8cKDvQDndIj0izRKOgTNmWI70uNviZCbXeKsc,9962
+iris_devtester/fixtures/__init__.py,sha256=foqK_3CCjvIvEipiD_PmXKLclHXq2qPBbdRpewnxiLQ,3491
+iris_devtester/fixtures/creator.py,sha256=L3mQ_AFw2NumDOS9zoQnuv3t3z6MMAR9_5-nrNi99Kg,8716
+iris_devtester/fixtures/loader.py,sha256=oUQdlCX17Abr4muu8dj_sLVxumQ5-hDwxy7So6A0sw8,12646
+iris_devtester/fixtures/manifest.py,sha256=FZUjdzOZfkBJSncglPhD_Xc29cV1z7tjkQExA7Af8lY,10324
 iris_devtester/fixtures/obj_export.py,sha256=avJtCtLgs4DW5gFcLb6dzPEH_g5lhbYMnCVvpFW4T2Y,14753
-iris_devtester/fixtures/validator.py,sha256=Q4AcucnLX8DxICoS6n7p3Ogm1RB-Mp9IsHqtMXiUVto,11671
+iris_devtester/fixtures/validator.py,sha256=gnYAYVNfH2xaD4gFgbtfeZ4pQuV5x0MpQ4djt_VLOIQ,11911
 iris_devtester/integrations/__init__.py,sha256=wMduwyadsOOwZ8odfVNZkjeKg-u2APnvMz_jdvWaL0A,368
 iris_devtester/integrations/langchain.py,sha256=cIV8bq_wDKMOXLFQ1P-wdSFsJdxIV7o0-a5f6-ELbME,11310
 iris_devtester/ports/__init__.py,sha256=uLdbV7J7UJxJsoDqoyySTabIle72WltYDFKlN2-f7bI,506
@@ -58,9 +58,9 @@ iris_devtester/utils/iris_container_adapter.py,sha256=0Vc55gDsVAxHZzk4wvZySGUJKR
 iris_devtester/utils/password.py,sha256=OqS6LNXMDopSoYGiodM2V9clghD4qcbIzftH4TdrMSU,21968
 iris_devtester/utils/progress.py,sha256=5OmuntItqCgUFXSmaQjHwILrTnVLYECZ5glpSbvOTOU,7795
 iris_devtester/utils/test_connection.py,sha256=cyEzxSbvxBxz44xLb7Jbz8OhHT8UgCZLO0lT-qShPEo,6950
-iris_devtester-1.9.3.dist-info/licenses/LICENSE,sha256=dISbikDYS2uP710ZFzSzaSmKzIBRyi_6YwuwO97bT94,1083
-iris_devtester-1.9.3.dist-info/METADATA,sha256=It5jOKAoyNkbBiyaYQw3kO5TFRog3I9lKeQl2f0eTIo,7682
-iris_devtester-1.9.3.dist-info/WHEEL,sha256=wUyA8OaulRlbfwMtmQsvNngGrxQHAvkKcvRmdizlJi0,92
-iris_devtester-1.9.3.dist-info/entry_points.txt,sha256=svOltni3vX3ul_qxbWl8fOA6ZrJeFASuN29pON6ftqw,59
-iris_devtester-1.9.3.dist-info/top_level.txt,sha256=DnrLJ3laB5x_gTkmATDEg1v1lTOQxgmHgNd66bdXaoU,15
-iris_devtester-1.9.3.dist-info/RECORD,,
+iris_devtester-1.10.2.dist-info/licenses/LICENSE,sha256=dISbikDYS2uP710ZFzSzaSmKzIBRyi_6YwuwO97bT94,1083
+iris_devtester-1.10.2.dist-info/METADATA,sha256=sh5xjenarcua9puUzAl1Lpf3hEGpbHpp5npOUXeYPfE,8940
+iris_devtester-1.10.2.dist-info/WHEEL,sha256=wUyA8OaulRlbfwMtmQsvNngGrxQHAvkKcvRmdizlJi0,92
+iris_devtester-1.10.2.dist-info/entry_points.txt,sha256=svOltni3vX3ul_qxbWl8fOA6ZrJeFASuN29pON6ftqw,59
+iris_devtester-1.10.2.dist-info/top_level.txt,sha256=DnrLJ3laB5x_gTkmATDEg1v1lTOQxgmHgNd66bdXaoU,15
+iris_devtester-1.10.2.dist-info/RECORD,,