feat(compose): add structured container inspect information

Author: VictorCavichioli

core/testcontainers/compose/compose.py

@@ -33,6 +33,122 @@ def _ignore_properties(cls: type[_IPT], dict_: Any) -> _IPT:
     return cast("_IPT", cls(**filtered))
 
 
+@dataclass
+class ContainerState:
+    """Container state from docker inspect."""
+
+    Status: Optional[str] = None
+    Running: Optional[bool] = None
+    Paused: Optional[bool] = None
+    Restarting: Optional[bool] = None
+    OOMKilled: Optional[bool] = None
+    Dead: Optional[bool] = None
+    Pid: Optional[int] = None
+    ExitCode: Optional[int] = None
+    Error: Optional[str] = None
+    StartedAt: Optional[str] = None
+    FinishedAt: Optional[str] = None
+
+
+@dataclass
+class ContainerConfig:
+    """Container config from docker inspect."""
+
+    Hostname: Optional[str] = None
+    User: Optional[str] = None
+    Env: Optional[list[str]] = None
+    Cmd: Optional[list[str]] = None
+    Image: Optional[str] = None
+    WorkingDir: Optional[str] = None
+    Entrypoint: Optional[list[str]] = None
+    ExposedPorts: Optional[dict[str, Any]] = None
+    Labels: Optional[dict[str, str]] = None
+
+
+@dataclass
+class Network:
+    """Individual network from docker inspect."""
+
+    IPAddress: Optional[str] = None
+    Gateway: Optional[str] = None
+    NetworkID: Optional[str] = None
+    EndpointID: Optional[str] = None
+    MacAddress: Optional[str] = None
+    Aliases: Optional[list[str]] = None
+
+
+@dataclass
+class NetworkSettings:
+    """Network settings from docker inspect."""
+
+    Bridge: Optional[str] = None
+    IPAddress: Optional[str] = None
+    Gateway: Optional[str] = None
+    Ports: Optional[dict[str, Any]] = None
+    Networks: Optional[dict[str, Network]] = None
+
+    def get_networks(self) -> Optional[dict[str, Network]]:
+        """Get networks for the container."""
+        return self.Networks
+
+
+@dataclass
+class ContainerInspectInfo:
+    """Container information from docker inspect."""
+
+    Id: Optional[str] = None
+    Name: Optional[str] = None
+    Created: Optional[str] = None
+    Path: Optional[str] = None
+    Args: Optional[list[str]] = None
+    Image: Optional[str] = None
+    State: Optional[ContainerState] = None
+    Config: Optional[ContainerConfig] = None
+    network_settings: Optional[NetworkSettings] = None
+    Mounts: Optional[list[dict[str, Any]]] = None
+
+    @classmethod
+    def from_dict(cls, data: dict[str, Any]) -> "ContainerInspectInfo":
+        """Create from docker inspect JSON."""
+        return cls(
+            Id=data.get("Id"),
+            Name=data.get("Name"),
+            Created=data.get("Created"),
+            Path=data.get("Path"),
+            Args=data.get("Args"),
+            Image=data.get("Image"),
+            State=_ignore_properties(ContainerState, data.get("State", {})) if data.get("State") else None,
+            Config=_ignore_properties(ContainerConfig, data.get("Config", {})) if data.get("Config") else None,
+            network_settings=cls._parse_network_settings(data.get("NetworkSettings", {}))
+            if data.get("NetworkSettings")
+            else None,
+            Mounts=data.get("Mounts"),
+        )
+
+    @classmethod
+    def _parse_network_settings(cls, data: dict[str, Any]) -> Optional[NetworkSettings]:
+        """Parse NetworkSettings with Networks as Network objects."""
+        if not data:
+            return None
+
+        networks_data = data.get("Networks", {})
+        networks = {}
+        for name, net_data in networks_data.items():
+            networks[name] = _ignore_properties(Network, net_data)
+
+        return NetworkSettings(
+            Bridge=data.get("Bridge"),
+            IPAddress=data.get("IPAddress"),
+            Gateway=data.get("Gateway"),
+            Ports=data.get("Ports"),
+            Networks=networks,
+        )
+
+    def get_network_settings(self) -> Optional[NetworkSettings]:
+        """Get network settings for the container."""
+        return self.network_settings
+
+
 @dataclass
 class PublishedPortModel:
     """
@@ -81,6 +197,7 @@ class ComposeContainer:
     ExitCode: Optional[int] = None
     Publishers: list[PublishedPortModel] = field(default_factory=list)
     _docker_compose: Optional["DockerCompose"] = field(default=None, init=False, repr=False)
+    _cached_container_info: Optional[ContainerInspectInfo] = field(default=None, init=False, repr=False)
 
     def __post_init__(self) -> None:
         if self.Publishers:
@@ -147,6 +264,31 @@ def reload(self) -> None:
         # each time through get_container(), but we need this method for compatibility
         pass
 
+    def get_container_info(self) -> Optional[ContainerInspectInfo]:
+        """Get container information via docker inspect (lazy loaded)."""
+        if self._cached_container_info is not None:
+            return self._cached_container_info
+
+        if not self._docker_compose or not self.ID:
+            return None
+
+        try:
+            inspect_command = ["docker", "inspect", self.ID]
+            result = self._docker_compose._run_command(cmd=inspect_command)
+            inspect_output = result.stdout.decode("utf-8").strip()
+
+            if inspect_output:
+                raw_data = loads(inspect_output)[0]
+                self._cached_container_info = ContainerInspectInfo.from_dict(raw_data)
+            else:
+                self._cached_container_info = None
+
+        except Exception as e:
+            logger.warning(f"Failed to get container info for {self.ID}: {e}")
+            self._cached_container_info = None
+
+        return self._cached_container_info
+
     @property
     def status(self) -> str:
         """Get container status for compatibility with wait strategies."""

core/tests/test_compose.py

@@ -378,3 +378,60 @@ def test_compose_profile_support(profiles: Optional[list[str]], running: list[st
         for service in not_running:
             with pytest.raises(ContainerIsNotRunning):
                 compose.get_container(service)
+
+
+def test_container_info():
+    """Test get_container_info functionality"""
+    basic = DockerCompose(context=FIXTURES / "basic")
+    with basic:
+        container = basic.get_container("alpine")
+
+        info = container.get_container_info()
+        assert info is not None
+        assert info.Id is not None
+        assert info.Name is not None
+        assert info.Image is not None
+
+        assert info.State is not None
+        assert info.State.Status == "running"
+        assert info.State.Running is True
+        assert info.State.Pid is not None
+
+        assert info.Config is not None
+        assert info.Config.Image is not None
+        assert info.Config.Hostname is not None
+
+        network_settings = info.get_network_settings()
+        assert network_settings is not None
+        assert network_settings.Networks is not None
+
+        info2 = container.get_container_info()
+        assert info is info2
+
+
+def test_container_info_network_details():
+    """Test network details in container info"""
+    single = DockerCompose(context=FIXTURES / "port_single")
+    with single:
+        container = single.get_container()
+        info = container.get_container_info()
+        assert info is not None
+
+        network_settings = info.get_network_settings()
+        assert network_settings is not None
+
+        if network_settings.Networks:
+            # Test first network
+            network_name, network = next(iter(network_settings.Networks.items()))
+            assert network.IPAddress is not None
+            assert network.Gateway is not None
+            assert network.NetworkID is not None
+
+
+def test_container_info_none_when_no_docker_compose():
+    """Test get_container_info returns None when docker_compose reference is missing"""
+    from testcontainers.compose.compose import ComposeContainer
+
+    container = ComposeContainer()
+    info = container.get_container_info()
+    assert info is None