imaged 2026.7.2__py3-none-any.whl

imaged/__init__.py

@@ -0,0 +1,51 @@
+"""
+One interface to docker, podman and Apple's container.
+
+Start a container, speak to its standard streams, and get told what went
+wrong in terms you can actually branch on -- with the same code and the
+same answers whichever engine is installed.
+
+Each engine is driven via its command line interface, which is the only
+mechanism all three have in common, and which conveniently leaves the
+engine to demultiplex container stdio onto real pipes for us.
+
+`anyio` is the only async dependency, so this runs unmodified on both
+asyncio and trio.
+"""
+
+from imaged._dialects import (
+    CONTAINER,
+    DOCKER,
+    KNOWN,
+    PODMAN,
+    Dialect,
+)
+from imaged._errors import (
+    EngineError,
+    EngineFailed,
+    EngineNotRunning,
+    NoSuchContainer,
+    NoSuchEngine,
+    NoSuchImage,
+    SessionClosed,
+    Unsupported,
+)
+from imaged._subprocess import Engine, Session
+
+__all__ = [
+    "CONTAINER",
+    "DOCKER",
+    "KNOWN",
+    "PODMAN",
+    "Dialect",
+    "Engine",
+    "EngineError",
+    "EngineFailed",
+    "EngineNotRunning",
+    "NoSuchContainer",
+    "NoSuchEngine",
+    "NoSuchImage",
+    "Session",
+    "SessionClosed",
+    "Unsupported",
+]

imaged/_dialects.py

@@ -0,0 +1,166 @@
+"""
+The (few) ways the container engines we support differ from each other.
+
+Pleasantly, they agree on nearly all of the spelling we need --
+`create --interactive`, `start --attach --interactive`, `build --tag`
+and `rm --force` are common to all three -- so what's left below is
+quite small, and mostly concerns how each reports failure.
+"""
+
+from __future__ import annotations
+
+from attrs import frozen
+
+from imaged._errors import (
+    EngineFailed,
+    EngineNotRunning,
+    NoSuchContainer,
+    NoSuchImage,
+)
+
+
+@frozen
+class Dialect:
+    """
+    One container engine, and how its CLI differs from the others.
+    """
+
+    name: str
+
+    #: How the engine spells fetching an image.
+    #: Apple's container hides it under its image subcommand.
+    pull: tuple[str, ...] = ("pull",)
+
+    #: Flags silencing whatever progress output a pull would otherwise
+    #: emit.
+    #: This matters more than it may look, as a caller cannot tell
+    #: something the engine wrote to standard error apart from something
+    #: the container wrote there.
+    quiet_pull: tuple[str, ...] = ("--quiet",)
+
+    #: How the engine spells showing a *container's* configuration.
+    #: docker and podman also have a bare `inspect` which will happily
+    #: look at images and networks too, and which says "no such object"
+    #: rather than naming what it couldn't find.
+    inspect: tuple[str, ...] = ("container", "inspect")
+
+    #: Flags which disable networking entirely for a container.
+    no_network: tuple[str, ...] = ("--network", "none")
+
+    #: How the engine spells deleting an image.
+    remove_image: tuple[str, ...] = ("rmi", "--force")
+
+    #: Whether the engine can reattach to a running container's stdio.
+    #: Apple's container has no attach subcommand, and its exec starts a
+    #: new process rather than reattaching to the existing one.
+    attaches: bool = True
+
+    #: Substrings indicating the engine's daemon or service is down.
+    not_running: tuple[str, ...] = ()
+
+    #: Substrings indicating an image does not exist.
+    no_such_image: tuple[str, ...] = ()
+
+    #: Substrings indicating a container does not exist.
+    no_such_container: tuple[str, ...] = ()
+
+    #: The argv prefix to invoke, where it isn't simply the engine's
+    #: name -- an absolute path, or something like
+    #: `('docker', '--context', 'somewhere')`.
+    executable: tuple[str, ...] | None = None
+
+    @property
+    def command(self) -> tuple[str, ...]:
+        """
+        The argv prefix which invokes this engine.
+        """
+        return self.executable or (self.name,)
+
+    def classify(
+        self,
+        argv: tuple[str, ...],
+        returncode: int,
+        stderr: str,
+        subject: str,
+    ) -> Exception:
+        """
+        Work out what an engine was trying to tell us when it failed.
+
+        `subject` is whatever the command was operating on -- an image
+        or a container -- as the engines are inconsistent about whether
+        they mention it themselves.
+        """
+        message = stderr.casefold()
+
+        # Check this first, as an engine which isn't running will happily
+        # claim an image doesn't exist rather than admitting as much.
+        if any(each in message for each in self.not_running):
+            return EngineNotRunning(engine=self.name)
+        if any(each in message for each in self.no_such_image):
+            return NoSuchImage(image=subject)
+        if any(each in message for each in self.no_such_container):
+            return NoSuchContainer(id=subject)
+        return EngineFailed(
+            argv=argv,
+            returncode=returncode,
+            stderr=stderr,
+        )
+
+
+DOCKER = Dialect(
+    name="docker",
+    not_running=(
+        "cannot connect to the docker daemon",
+        "is the docker daemon running",
+    ),
+    no_such_image=(
+        "manifest unknown",
+        "pull access denied",
+        "repository does not exist",
+        # Registries (including ghcr.io) decline to distinguish "no such
+        # image" from "you may not look at this image", so we treat the
+        # two alike.
+        ": denied",
+        "403 (forbidden)",
+    ),
+    no_such_container=("no such container",),
+)
+
+PODMAN = Dialect(
+    name="podman",
+    not_running=(
+        "cannot connect to podman",
+        "unable to connect to podman socket",
+    ),
+    no_such_image=(
+        "manifest unknown",
+        "unable to find a name and tag match",
+        ": denied",
+        "403 (forbidden)",
+    ),
+    no_such_container=(
+        "no such container",
+        "no container with name or id",
+    ),
+)
+
+CONTAINER = Dialect(
+    name="container",
+    pull=("image", "pull"),
+    quiet_pull=("--disable-progress-updates",),
+    inspect=("inspect",),
+    remove_image=("image", "rm"),
+    attaches=False,
+    not_running=(
+        "xpc connection error",
+        "container system service has been started",
+    ),
+    # FIXME: Unverified. Apple's container refuses to say anything at all
+    #        until its service is running, so these need filling in from
+    #        a machine where it is.
+    no_such_image=(),
+    no_such_container=(),
+)
+
+#: Every engine we know how to drive, in the order we look for them.
+KNOWN = (DOCKER, PODMAN, CONTAINER)

imaged/_errors.py

@@ -0,0 +1,112 @@
+"""
+Errors which can happen whilst speaking to a container engine.
+
+Every engine reports the same failure in its own way, and none of them do
+so machine readably -- not even over their HTTP APIs, which is why the
+code this layer replaces was reduced to matching on substrings of prose.
+Turning that mess into something a caller can branch on is most of the
+reason this layer exists at all.
+"""
+
+from __future__ import annotations
+
+from attrs import frozen
+
+
+class EngineError(Exception):
+    """
+    Something went wrong whilst speaking to a container engine.
+    """
+
+
+@frozen
+class NoSuchEngine(EngineError):
+    """
+    None of the container engines we know how to drive are installed.
+    """
+
+    tried: tuple[str, ...]
+
+    def __str__(self):
+        return f"No container engine found (tried {', '.join(self.tried)})."
+
+
+@frozen
+class EngineNotRunning(EngineError):
+    """
+    The engine is installed, but whatever it speaks to isn't running.
+
+    For docker and podman that's a daemon (and on macOS, a VM housing it).
+    For Apple's container it's a launchd-managed service.
+    """
+
+    engine: str
+
+    def __str__(self):
+        return f"The {self.engine} engine isn't running."
+
+
+@frozen
+class NoSuchImage(EngineError):
+    """
+    The image doesn't exist, locally nor in the registry it came from.
+    """
+
+    image: str
+
+    def __str__(self):
+        return f"No image named {self.image!r}."
+
+
+@frozen
+class NoSuchContainer(EngineError):
+    """
+    No container with the given ID exists.
+    """
+
+    id: str
+
+    def __str__(self):
+        return f"No container with ID {self.id!r}."
+
+
+@frozen
+class Unsupported(EngineError):
+    """
+    The engine cannot do what was asked of it.
+
+    This is a capability gap rather than a failure -- Apple's container,
+    for instance, has no way to reattach to a running container's stdio.
+    """
+
+    engine: str
+    operation: str
+
+    def __str__(self):
+        return f"{self.engine} cannot {self.operation}."
+
+
+@frozen
+class SessionClosed(EngineError):
+    """
+    The container's standard streams are closed, but we tried to use them.
+    """
+
+    stderr: bytes = b""
+
+
+@frozen
+class EngineFailed(EngineError):
+    """
+    The engine failed in some way we do not specifically recognize.
+    """
+
+    argv: tuple[str, ...]
+    returncode: int
+    stderr: str
+
+    def __str__(self):
+        return (
+            f"`{' '.join(self.argv)}` exited with {self.returncode}:\n"
+            f"{self.stderr}"
+        )

imaged/_subprocess.py

@@ -0,0 +1,370 @@
+"""
+Driving a container engine by running its command line interface.
+
+This is the only mechanism all the engines have in common.
+Apple's container has no HTTP API at all, and speaking to it over XPC
+instead would cover it alone whilst leaving docker and podman needing a
+second mechanism anyhow.
+
+Doing so also means the engine demultiplexes container stdio onto real
+pipes for us, rather than leaving us to unpick its framing by hand.
+"""
+
+from __future__ import annotations
+
+from contextlib import asynccontextmanager, contextmanager, suppress
+from pathlib import Path
+from shutil import which
+from tempfile import TemporaryDirectory
+from typing import TYPE_CHECKING, cast
+import sys
+
+from anyio.streams.buffered import BufferedByteReceiveStream
+from attrs import field, frozen
+import anyio
+
+from imaged._dialects import KNOWN
+from imaged._errors import (
+    NoSuchContainer,
+    NoSuchEngine,
+    NoSuchImage,
+    SessionClosed,
+    Unsupported,
+)
+
+if TYPE_CHECKING:
+    from collections.abc import AsyncGenerator, Generator
+
+    from anyio.abc import ByteReceiveStream, Process
+
+    from imaged._dialects import Dialect
+
+
+#: The longest line we will buffer from a container before giving up.
+#: Responses carrying large schemas are entirely normal, so this is less
+#: a protocol limit than a way to stay bounded if a harness never emits
+#: a newline at all.
+_MAX_LINE = 32 * 1024 * 1024
+
+
+@contextmanager
+def _prepared(context: Path) -> Generator[Path]:
+    """
+    A build context in a state an engine can be handed.
+
+    On most platforms that's simply the directory we were given.
+    Windows needs a normalized copy of it, as git's autocrlf will have
+    rewritten LF to CRLF on checkout -- which breaks shebang lines
+    inside a Linux container -- and its filesystem has no executable bit
+    for the engine to preserve.
+    """
+    # A context which isn't there is handed over as-is, so that the
+    # engine says so rather than us quietly building from an empty
+    # directory we just made.
+    if sys.platform != "win32" or not context.is_dir():
+        yield context
+        return
+
+    with TemporaryDirectory() as temporary:
+        prepared = Path(temporary)
+        for path in sorted(context.rglob("*")):
+            if path.is_dir():
+                continue
+            data = path.read_bytes().replace(b"\r\n", b"\n")
+            copy = prepared / path.relative_to(context)
+            copy.parent.mkdir(parents=True, exist_ok=True)
+            copy.write_bytes(data)
+            copy.chmod(0o755 if data.startswith(b"#!") else 0o644)
+        yield prepared
+
+
+@frozen
+class Session:
+    """
+    A live bidirectional connection to a container's standard streams.
+
+    Standard error is collected into a file rather than a pipe.
+    A container which says a great deal there therefore cannot deadlock
+    by filling a pipe nobody is draining, and reading it needs no
+    background task -- which in turn keeps this free of any cancel scope
+    spanning a yield, and so portable to trio.
+    """
+
+    _process: Process = field(alias="process", repr=False)
+    _stdout: BufferedByteReceiveStream = field(alias="stdout", repr=False)
+    _stderr: Path = field(alias="stderr", repr=False)
+
+    @property
+    def alive(self) -> bool:
+        """
+        Is the container still running?
+        """
+        return self._process.returncode is None
+
+    def stderr(self) -> bytes:
+        """
+        Whatever the container has written to standard error so far.
+        """
+        try:
+            return self._stderr.read_bytes()
+        except FileNotFoundError:  # the session is long over
+            return b""
+
+    async def send(self, line: str) -> None:
+        """
+        Write a single line to the container's standard input.
+        """
+        stdin = self._process.stdin
+        if stdin is None:
+            raise SessionClosed(stderr=self.stderr())
+        try:
+            await stdin.send(f"{line}\n".encode())
+        except (anyio.BrokenResourceError, anyio.ClosedResourceError):
+            raise SessionClosed(stderr=self.stderr()) from None
+
+    async def receive(self) -> str:
+        """
+        Read a single line from the container's standard output.
+
+        Raises `SessionClosed` if the container has gone away.
+        Callers wanting to wait only so long should wrap this in an
+        `anyio.fail_after` scope, which is safe to abandon and retry --
+        anything already read stays buffered for the next attempt.
+        """
+        try:
+            line = await self._stdout.receive_until(b"\n", _MAX_LINE)
+        except (
+            anyio.BrokenResourceError,
+            anyio.ClosedResourceError,
+            anyio.EndOfStream,
+            anyio.IncompleteRead,
+        ):
+            raise SessionClosed(stderr=self.stderr()) from None
+        except anyio.DelimiterNotFound:
+            # A harness which has said this much without a newline is
+            # never going to send one.
+            raise SessionClosed(stderr=self.stderr()) from None
+        # Tolerate CRLF, as line oriented protocols generally do.
+        return line.decode().removesuffix("\r")
+
+
+@frozen
+class Engine:
+    """
+    A container engine, driven via its command line interface.
+    """
+
+    _dialect: Dialect = field(alias="dialect")
+
+    @classmethod
+    def detect(cls, *dialects: Dialect) -> Engine:
+        """
+        Use the first engine we know about which is actually installed.
+        """
+        candidates = dialects or KNOWN
+        for dialect in candidates:
+            if which(dialect.command[0]) is not None:
+                return cls(dialect=dialect)
+        raise NoSuchEngine(tried=tuple(each.name for each in candidates))
+
+    @classmethod
+    def named(cls, name: str) -> Engine:
+        """
+        Use one specific engine, by name.
+        """
+        for dialect in KNOWN:
+            if dialect.name == name:
+                return cls(dialect=dialect)
+        raise NoSuchEngine(tried=(name,))
+
+    @property
+    def name(self) -> str:
+        """
+        Which engine this is.
+        """
+        return self._dialect.name
+
+    @property
+    def attaches(self) -> bool:
+        """
+        Can this engine reattach to a running container's stdio?
+        """
+        return self._dialect.attaches
+
+    async def pull(self, image: str) -> None:
+        """
+        Fetch an image from wherever it lives.
+        """
+        await self._engine(
+            *self._dialect.pull,
+            *self._dialect.quiet_pull,
+            image,
+            subject=image,
+        )
+
+    async def create(
+        self,
+        image: str,
+        *command: str,
+        network: bool = True,
+    ) -> str:
+        """
+        Create (but do not start) a container, returning its ID.
+
+        Any `command` given replaces whatever the image would otherwise
+        run.
+
+        Networking is whatever the engine does by default, unless it's
+        switched off here, in which case the container gets none at all.
+        How an engine provides networking is its own business, and they
+        do differ; having none is the part they agree on.
+        """
+        args = ["create", "--interactive"]
+        if not network:
+            args.extend(self._dialect.no_network)
+        args.append(image)
+        args.extend(command)
+        return (await self._engine(*args, subject=image)).strip()
+
+    async def create_pulling_if_needed(
+        self,
+        image: str,
+        *command: str,
+        network: bool = True,
+    ) -> str:
+        """
+        Create a container, fetching its image first if we lack it.
+
+        Engines differ on whether creating pulls implicitly, so we ask
+        for it explicitly rather than relying on either behavior.
+        """
+        try:
+            return await self.create(image, *command, network=network)
+        except NoSuchImage:
+            await self.pull(image)
+            return await self.create(image, *command, network=network)
+
+    async def remove(self, id: str) -> None:
+        """
+        Delete a container, running or not.
+        """
+        await self._engine("rm", "--force", id, subject=id)
+
+    async def start_detached(self, id: str) -> None:
+        """
+        Start a container without speaking to it.
+        """
+        await self._engine("start", id, subject=id)
+
+    async def build(self, tag: str, context: Path) -> None:
+        """
+        Build an image from a directory holding its build context.
+
+        A directory is the one form every engine accepts -- Apple's
+        container takes nothing else, and whilst docker will read a tar
+        archive from standard input, podman reserves that for reading a
+        Containerfile.
+        """
+        with _prepared(context) as prepared:
+            await self._engine(
+                "build",
+                "--tag",
+                tag,
+                str(prepared),
+                subject=tag,
+            )
+
+    async def remove_image(self, tag: str) -> None:
+        """
+        Delete an image.
+        """
+        await self._engine(*self._dialect.remove_image, tag, subject=tag)
+
+    async def exists(self, id: str) -> bool:
+        """
+        Is there a container with the given ID?
+        """
+        try:
+            await self._engine(*self._dialect.inspect, id, subject=id)
+        except NoSuchContainer:
+            return False
+        return True
+
+    @asynccontextmanager
+    async def start(self, id: str) -> AsyncGenerator[Session]:
+        """
+        Start a created container and speak to its standard streams.
+        """
+        args = ("start", "--attach", "--interactive", id)
+        async with self._session(*args) as session:
+            yield session
+
+    @asynccontextmanager
+    async def attach(self, id: str) -> AsyncGenerator[Session]:
+        """
+        Speak to the standard streams of an already running container.
+        """
+        if not self._dialect.attaches:
+            raise Unsupported(
+                engine=self._dialect.name,
+                operation="attach to a running container",
+            )
+        # Confirm it exists up front, as otherwise a bad ID shows up only
+        # as a session which closes immediately for no stated reason.
+        await self._engine(*self._dialect.inspect, id, subject=id)
+        async with self._session("attach", id) as session:
+            yield session
+
+    async def _engine(self, *args: str, subject: str) -> str:
+        """
+        Run an engine command to completion, returning its stdout.
+        """
+        argv = (*self._dialect.command, *args)
+        try:
+            completed = await anyio.run_process(argv, check=False)
+        except FileNotFoundError:
+            raise NoSuchEngine(tried=(self._dialect.name,)) from None
+
+        if completed.returncode:
+            raise self._dialect.classify(
+                argv=argv,
+                returncode=completed.returncode,
+                stderr=completed.stderr.decode(),
+                subject=subject,
+            )
+        return completed.stdout.decode()
+
+    @asynccontextmanager
+    async def _session(self, *args: str) -> AsyncGenerator[Session]:
+        """
+        Speak to whatever container the given command connects us to.
+        """
+        argv = (*self._dialect.command, *args)
+        with TemporaryDirectory() as directory:
+            # We hand the container a file to write standard error to,
+            # and read it back via a second, independent handle.
+            # Sharing the one handle would mean sharing a file offset
+            # with the container, so our seeking in order to read could
+            # land its next write somewhere it doesn't belong.
+            path = Path(directory) / "stderr"
+            with path.open("wb") as stderr:
+                try:
+                    process = await anyio.open_process(argv, stderr=stderr)
+                except FileNotFoundError:
+                    raise NoSuchEngine(
+                        tried=(self._dialect.name,),
+                    ) from None
+
+                try:
+                    yield Session(
+                        process=process,
+                        stdout=BufferedByteReceiveStream(
+                            cast("ByteReceiveStream", process.stdout),
+                        ),
+                        stderr=path,
+                    )
+                finally:
+                    if process.returncode is None:
+                        with suppress(ProcessLookupError):  # may beat us
+                            process.kill()
+                    await process.wait()

imaged/tests/test_engines.py

@@ -0,0 +1,376 @@
+"""
+Tests for the container engine layer.
+
+These deliberately drive a stand-in engine rather than a real one, as
+what's worth testing here is the plumbing -- argv construction, stdio
+round trips, how sessions end and how failures are classified -- none of
+which needs a container to exercise.
+Whether each real engine actually speaks the dialect described in
+`imaged._dialects` is what the against-a-real-engine tests are for.
+"""
+
+from __future__ import annotations
+
+import sys
+
+import pytest
+
+from imaged import (
+    CONTAINER,
+    DOCKER,
+    PODMAN,
+    Dialect,
+    Engine,
+    EngineFailed,
+    EngineNotRunning,
+    NoSuchContainer,
+    NoSuchEngine,
+    NoSuchImage,
+    SessionClosed,
+    Unsupported,
+    _subprocess,
+)
+
+pytestmark = pytest.mark.anyio
+
+
+#: An "engine" which knows just enough to be driven like a real one.
+#: Starting a container gets you an echo server standing in for a
+#: harness, which dies on request so that closure is testable.
+FAKE_ENGINE = """\
+import pathlib, sys
+
+# A real container is Linux, so don't let Windows translate ours.
+sys.stdout.reconfigure(newline=chr(10))
+
+args = sys.argv[1:]
+pathlib.Path(__file__).with_name("argv").open("a").write(f"{args}\\n")
+
+match args:
+    case ["create", *rest]:
+        if "nonexistent" in rest[-1]:
+            print("Error: manifest unknown", file=sys.stderr)
+            sys.exit(1)
+        print("fake-container-id")
+    case ["start", *rest]:
+        while True:
+            line = sys.stdin.readline()
+            if not line:
+                break
+            if line.strip() == "die":
+                sys.exit(0)
+            if line.strip() == "complain":
+                print("something went wrong", file=sys.stderr, flush=True)
+                continue
+            if line.strip() == "crlf":
+                sys.stdout.write("fine" + chr(13) + chr(10))
+                sys.stdout.flush()
+                continue
+            if line.strip() == "flood":
+                sys.stdout.write("x" * 1000)  # ... and never a newline
+                sys.stdout.flush()
+                continue
+            print(line.strip()[::-1], flush=True)
+    case ["container", "inspect", *rest]:
+        if "nonexistent" in rest[-1]:
+            print("Error: no such container", file=sys.stderr)
+            sys.exit(1)
+    case ["build", *rest]:
+        context = pathlib.Path(rest[-1])
+        if not context.is_dir():
+            print(f"not a context directory: {rest[-1]}", file=sys.stderr)
+            sys.exit(1)
+        names = sorted(each.name for each in context.iterdir())
+        pathlib.Path(__file__).with_name("contents").write_text(str(names))
+    case ["pull", *rest] | ["rm", *rest]:
+        pass
+    case _:
+        print(f"unknown invocation: {args}", file=sys.stderr)
+        sys.exit(2)
+"""
+
+
+@pytest.fixture(params=["asyncio", "trio"])
+def anyio_backend(request):
+    """
+    Everything here should hold on either event loop.
+    """
+    return request.param
+
+
+@pytest.fixture
+def engine(tmp_path):
+    script = tmp_path / "fake-engine.py"
+    script.write_text(FAKE_ENGINE)
+    return Engine(
+        dialect=Dialect(
+            name="fake",
+            executable=(sys.executable, str(script)),
+            no_such_image=("manifest unknown",),
+            no_such_container=("no such container",),
+        ),
+    )
+
+
+@pytest.fixture
+def argv(tmp_path):
+    def _argv():
+        path = tmp_path / "argv"
+        return path.read_text().splitlines() if path.exists() else []
+
+    return _argv
+
+
+class TestSessions:
+    async def test_round_trip(self, engine):
+        id = await engine.create("some-image")
+        async with engine.start(id) as session:
+            await session.send("hello")
+            assert await session.receive() == "olleh"
+            await session.send("goodbye")
+            assert await session.receive() == "eybdoog"
+
+    async def test_receiving_from_a_dead_container(self, engine):
+        id = await engine.create("some-image")
+        async with engine.start(id) as session:
+            await session.send("die")
+            with pytest.raises(SessionClosed):
+                await session.receive()
+
+    async def test_stderr_is_collected_without_ending_the_session(
+        self,
+        engine,
+    ):
+        id = await engine.create("some-image")
+        async with engine.start(id) as session:
+            await session.send("complain")
+            await session.send("hello")
+            assert await session.receive() == "olleh"
+            assert b"something went wrong" in session.stderr()
+
+    async def test_stderr_survives_closure(self, engine):
+        id = await engine.create("some-image")
+        async with engine.start(id) as session:
+            await session.send("complain")
+            await session.send("die")
+            with pytest.raises(SessionClosed):
+                await session.receive()
+            assert b"something went wrong" in session.stderr()
+
+    async def test_the_container_is_gone_afterwards(self, engine):
+        id = await engine.create("some-image")
+        async with engine.start(id) as session:
+            assert session.alive
+        assert not session.alive
+
+    async def test_a_container_speaking_crlf(self, engine):
+        id = await engine.create("some-image")
+        async with engine.start(id) as session:
+            await session.send("crlf")
+            assert await session.receive() == "fine"
+
+    async def test_a_container_which_never_sends_a_newline(
+        self,
+        engine,
+        monkeypatch,
+    ):
+        monkeypatch.setattr(_subprocess, "_MAX_LINE", 100)
+        id = await engine.create("some-image")
+        async with engine.start(id) as session:
+            await session.send("flood")
+            with pytest.raises(SessionClosed):
+                await session.receive()
+
+
+class TestCreating:
+    async def test_networking_is_the_engine_default(self, engine, argv):
+        """
+        We say nothing at all, rather than second-guessing the engine.
+        """
+        await engine.create("some-image")
+        assert "--network" not in argv()[0]
+
+    async def test_networking_can_be_switched_off(self, engine, argv):
+        await engine.create("some-image", network=False)
+        assert "'--network', 'none'" in argv()[0]
+
+    async def test_stdin_is_always_open(self, engine, argv):
+        await engine.create("some-image")
+        assert "--interactive" in argv()[0]
+
+    async def test_nonexistent_image(self, engine):
+        with pytest.raises(NoSuchImage) as excinfo:
+            await engine.create("nonexistent-image")
+        assert excinfo.value.image == "nonexistent-image"
+
+    async def test_pulls_only_when_needed(self, engine, argv):
+        await engine.create_pulling_if_needed("some-image")
+        assert not any(each.startswith("['pull'") for each in argv())
+
+    async def test_pulls_when_missing(self, engine, argv):
+        # The stand-in never starts existing, so this ends up back where
+        # it started -- but only after having tried a pull.
+        with pytest.raises(NoSuchImage):
+            await engine.create_pulling_if_needed("nonexistent-image")
+        assert any(each.startswith("['pull'") for each in argv())
+
+
+class TestBuilding:
+    """
+    A directory is the one form of build context every engine takes.
+    """
+
+    async def test_from_a_directory(self, engine, tmp_path):
+        """
+        Whatever reaches the engine holds the context we were given.
+
+        It isn't always the very directory we passed -- on Windows it's
+        a normalized copy -- so the contents are what's worth asserting.
+        """
+        context = tmp_path / "ctx"
+        context.mkdir()
+        context.joinpath("Dockerfile").write_text("FROM scratch\n")
+        await engine.build(tag="some-image", context=context)
+        assert tmp_path.joinpath("contents").read_text() == "['Dockerfile']"
+
+    async def test_a_context_which_isnt_there(self, engine, tmp_path):
+        with pytest.raises(EngineFailed):
+            await engine.build(tag="x", context=tmp_path / "nope")
+
+
+class TestAttaching:
+    async def test_nonexistent_container(self, engine):
+        with pytest.raises(NoSuchContainer):
+            async with engine.attach("nonexistent-container"):
+                pass
+
+    async def test_unsupported(self):
+        engine = Engine(dialect=CONTAINER)
+        with pytest.raises(Unsupported) as excinfo:
+            async with engine.attach("whatever"):
+                pass
+        assert excinfo.value.engine == "container"
+
+
+class TestDetection:
+    def test_no_engine_at_all(self):
+        nowhere = Dialect(name="definitely-not-installed-anywhere")
+        with pytest.raises(NoSuchEngine):
+            Engine.detect(nowhere)
+
+    def test_by_name(self):
+        assert Engine.named("podman").name == "podman"
+
+    def test_by_unknown_name(self):
+        with pytest.raises(NoSuchEngine):
+            Engine.named("kubernetes-lol")
+
+
+class TestClassification:
+    """
+    Each engine says the same things differently, and none of them
+    usefully.
+    """
+
+    @pytest.mark.parametrize(
+        "dialect, stderr",
+        [
+            (DOCKER, "Cannot connect to the Docker daemon at unix://x.sock"),
+            (DOCKER, "Is the docker daemon running?"),
+            (PODMAN, "Cannot connect to Podman. Please verify your conn"),
+            (PODMAN, "Error: unable to connect to Podman socket"),
+            (CONTAINER, 'interrupted: "XPC connection error: Connection'),
+            (
+                CONTAINER,
+                (
+                    "Ensure container system service has been started "
+                    "with `container system start`."
+                ),
+            ),
+        ],
+    )
+    def test_not_running(self, dialect, stderr):
+        error = dialect.classify(
+            argv=("x",),
+            returncode=1,
+            stderr=stderr,
+            subject="whatever",
+        )
+        assert isinstance(error, EngineNotRunning)
+
+    @pytest.mark.parametrize(
+        "dialect, stderr",
+        [
+            (
+                DOCKER,
+                (
+                    "Error response from daemon: manifest for foo:latest "
+                    "not found: manifest unknown"
+                ),
+            ),
+            (DOCKER, "Error response from daemon: pull access denied for x"),
+            (DOCKER, 'Head "https://ghcr.io/v2/x/manifests/latest": denied'),
+            (PODMAN, "Error: unable to find a name and tag match for x"),
+            (
+                PODMAN,
+                (
+                    "Error: initializing source docker://ghcr.io/x:nope: "
+                    "Requesting bearer token: invalid status code from "
+                    "registry 403 (Forbidden)"
+                ),
+            ),
+            (PODMAN, 'Head "https://ghcr.io/v2/x/manifests/latest": denied'),
+        ],
+    )
+    def test_no_such_image(self, dialect, stderr):
+        error = dialect.classify(
+            argv=("x",),
+            returncode=1,
+            stderr=stderr,
+            subject="some-image",
+        )
+        assert isinstance(error, NoSuchImage)
+        assert error.image == "some-image"
+
+    @pytest.mark.parametrize(
+        "dialect, stderr",
+        [
+            (DOCKER, "Error response from daemon: No such container: abcd"),
+            (PODMAN, 'Error: no container with name or ID "abcd" found'),
+        ],
+    )
+    def test_no_such_container(self, dialect, stderr):
+        error = dialect.classify(
+            argv=("x",),
+            returncode=1,
+            stderr=stderr,
+            subject="abcd",
+        )
+        assert isinstance(error, NoSuchContainer)
+        assert error.id == "abcd"
+
+    def test_a_downed_engine_beats_a_missing_image(self):
+        """
+        An engine which isn't running will cheerfully tell you an image
+        doesn't exist, which is true but unhelpful.
+        """
+        error = DOCKER.classify(
+            argv=("x",),
+            returncode=1,
+            stderr=(
+                "Cannot connect to the Docker daemon. "
+                "manifest unknown"  # both, and the daemon is the story
+            ),
+            subject="some-image",
+        )
+        assert isinstance(error, EngineNotRunning)
+
+    def test_anything_else(self):
+        error = DOCKER.classify(
+            argv=("docker", "create", "x"),
+            returncode=125,
+            stderr="something nobody has ever seen before",
+            subject="x",
+        )
+        assert isinstance(error, EngineFailed)
+        assert "something nobody has ever seen before" in str(error)

imaged/tests/test_engines_for_real.py

@@ -0,0 +1,163 @@
+"""
+The same behavior, asserted against an actual container engine.
+
+`imaged` exists so that three engines answer identically, which is a
+claim only an actual engine can settle.
+So these run one set of assertions against whichever engine
+`IMAGED_ENGINE` names, and CI runs them once per engine.
+
+They are the only tests here needing a container runtime, and skip
+themselves when there isn't one.
+"""
+
+from __future__ import annotations
+
+from os import environ
+
+import pytest
+
+from imaged import (
+    Engine,
+    NoSuchEngine,
+    NoSuchImage,
+    SessionClosed,
+    Unsupported,
+)
+
+pytestmark = [pytest.mark.anyio, pytest.mark.real]
+
+#: Something tiny, ubiquitous, and able to hold a conversation.
+IMAGE = "docker.io/library/alpine:3.22"
+
+
+@pytest.fixture(params=["asyncio", "trio"])
+def anyio_backend(request):
+    return request.param
+
+
+@pytest.fixture(scope="module")
+def engine():
+    named = environ.get("IMAGED_ENGINE")
+    try:
+        return Engine.named(named) if named else Engine.detect()
+    except NoSuchEngine as error:  # pragma: no cover
+        pytest.skip(str(error))
+
+
+@pytest.fixture
+async def container(engine):
+    """
+    Containers running the given command, cleaned up afterwards.
+    """
+    created: list[str] = []
+
+    async def _container(*command: str) -> str:
+        id = await engine.create_pulling_if_needed(IMAGE, *command)
+        created.append(id)
+        return id
+
+    yield _container
+
+    for id in created:
+        await engine.remove(id)
+
+
+async def test_round_trip(engine, container):
+    id = await container("cat")
+    async with engine.start(id) as session:
+        await session.send("hello")
+        assert await session.receive() == "hello"
+        await session.send("goodbye")
+        assert await session.receive() == "goodbye"
+
+
+async def test_a_container_which_exits(engine, container):
+    id = await container("true")
+    async with engine.start(id) as session:
+        with pytest.raises(SessionClosed):
+            await session.receive()
+
+
+async def test_stderr_is_kept_separate(engine, container):
+    id = await container("sh", "-c", "echo trouble >&2; exec cat")
+    async with engine.start(id) as session:
+        await session.send("hello")
+        assert await session.receive() == "hello"
+        assert b"trouble" in session.stderr()
+
+
+async def test_stderr_survives_the_container(engine, container):
+    id = await container("sh", "-c", "echo very wrong >&2; exit 1")
+    async with engine.start(id) as session:
+        with pytest.raises(SessionClosed):
+            await session.receive()
+        assert b"very wrong" in session.stderr()
+
+
+async def test_networking_can_be_switched_off(engine):
+    """
+    Engines differ in how they *give* a container networking -- rootless
+    podman is not bridged the way docker is -- so what's worth asserting
+    is the part they agree on, which is having none at all.
+    """
+    id = await engine.create_pulling_if_needed(
+        IMAGE,
+        "sh",
+        "-c",
+        "ls /sys/class/net",
+        network=False,
+    )
+    try:
+        async with engine.start(id) as session:
+            assert await session.receive() == "lo"
+    finally:
+        await engine.remove(id)
+
+
+async def test_nonexistent_image(engine):
+    with pytest.raises(NoSuchImage):
+        await engine.create_pulling_if_needed(
+            "ghcr.io/julian/imaged-definitely-not-a-real-image:nope",
+        )
+
+
+async def test_exists(engine, container):
+    id = await container("cat")
+    assert await engine.exists(id)
+
+
+async def test_doesnt_exist(engine):
+    assert not await engine.exists("imaged-definitely-not-a-container")
+
+
+async def test_attaching_to_a_running_container(engine, container):
+    id = await container("cat")
+    if not engine.attaches:
+        with pytest.raises(Unsupported):
+            async with engine.attach(id):
+                pass
+        return
+
+    await engine.start_detached(id)
+    async with engine.attach(id) as session:
+        await session.send("hello")
+        assert await session.receive() == "hello"
+
+
+async def test_building(engine, tmp_path):
+    context = tmp_path / "context"
+    context.mkdir()
+    context.joinpath("Dockerfile").write_text(
+        f"FROM {IMAGE}\nRUN echo built > /built\n",
+    )
+    tag = "imaged-test-build:latest"
+    await engine.build(tag=tag, context=context)
+    try:
+        id = await engine.create(tag, "cat", "/built")
+        try:
+            async with engine.start(id) as session:
+                assert await session.receive() == "built"
+        finally:
+            await engine.remove(id)
+    finally:
+        await engine.remove_image(tag)

imaged-2026.7.2.dist-info/METADATA

@@ -0,0 +1,86 @@
+Metadata-Version: 2.4
+Name: imaged
+Version: 2026.7.2
+Summary: One interface to docker, podman and Apple's container.
+Project-URL: Documentation, https://imaged.readthedocs.io/
+Project-URL: Homepage, https://github.com/Julian/imaged
+Project-URL: Issues, https://github.com/Julian/imaged/issues/
+Project-URL: Funding, https://github.com/sponsors/Julian
+Project-URL: Source, https://github.com/Julian/imaged
+Author-email: Julian Berman <Julian+imaged@GrayVines.com>
+License-Expression: MIT
+License-File: COPYING
+Keywords: anyio,containers,docker,oci,podman
+Classifier: Development Status :: 3 - Alpha
+Classifier: Operating System :: OS Independent
+Classifier: Programming Language :: Python
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3.13
+Classifier: Programming Language :: Python :: 3.14
+Classifier: Programming Language :: Python :: Implementation :: CPython
+Requires-Python: >=3.13
+Requires-Dist: anyio>=4
+Requires-Dist: attrs>=22.2.0
+Description-Content-Type: text/x-rst
+
+==========
+``imaged``
+==========
+
+|PyPI| |Pythons| |CI| |ReadTheDocs|
+
+.. |PyPI| image:: https://img.shields.io/pypi/v/imaged.svg
+  :alt: PyPI version
+  :target: https://pypi.org/project/imaged/
+
+.. |Pythons| image:: https://img.shields.io/pypi/pyversions/imaged.svg
+  :alt: Supported Python versions
+  :target: https://pypi.org/project/imaged/
+
+.. |CI| image:: https://github.com/Julian/imaged/workflows/CI/badge.svg
+  :alt: Build status
+  :target: https://github.com/Julian/imaged/actions?query=workflow%3ACI
+
+
+.. |ReadTheDocs| image:: https://readthedocs.org/projects/imaged/badge/?version=stable&style=flat
+  :alt: ReadTheDocs status
+  :target: https://imaged.readthedocs.io/en/stable/
+
+``imaged`` gives you one interface to `docker <https://www.docker.com/>`_,
+`podman <https://podman.io/>`_ and `Apple's container
+<https://github.com/apple/container>`_.
+Start a container, speak to its standard streams, and be told what went wrong
+in terms you can branch on.
+
+.. code-block:: python
+
+    from imaged import Engine
+
+    engine = Engine.detect()
+
+    id = await engine.create_pulling_if_needed("alpine", "cat")
+    async with engine.start(id) as session:
+        await session.send("hello")
+        assert await session.receive() == "hello"
+
+Why
+---
+
+Every engine reports the same failure differently, and none of them do so
+machine readably -- not even over their HTTP APIs.
+Working out that an image simply doesn't exist otherwise means matching on
+substrings of prose, separately for each engine.
+``imaged`` does that once, and raises ``NoSuchImage``.
+
+Each engine is driven via its command line interface, which is the only
+mechanism all three have in common, as Apple's container has no HTTP API at
+all.
+Doing so also leaves the engine to demultiplex container stdio onto real
+pipes, rather than leaving you to unpick its framing.
+
+Containers get no networking unless you ask for it, on the theory that
+something you are running should have to say so before it can phone home.
+
+`anyio <https://anyio.readthedocs.io/>`_ is the only async dependency, so
+this runs unmodified on both asyncio and trio.
+Its own test suite runs on both, against all three engines.

imaged-2026.7.2.dist-info/RECORD

@@ -0,0 +1,11 @@
+imaged/__init__.py,sha256=OjnLR0dEoFxw6QDk1vP5wZvAwYybxKLIXhvdlEsRi-Y,1153
+imaged/_dialects.py,sha256=Vtzt8a6QeKNEdaaXyWk639nzSlf19gtBuA_sJoAz5rg,5218
+imaged/_errors.py,sha256=L7gIDBsQ2ahyZRUI86cA_xKTpRPRFuaqBG2OnSmdeWU,2475
+imaged/_subprocess.py,sha256=lehg2haNYM0WZGHbXA-y5vtnfBFHggvFE1TxVfG0rTY,12547
+imaged/tests/__init__.py,sha256=47DEQpj8HBSa-_TImW-5JCeuQeRkm5NMpJWZG3hSuFU,0
+imaged/tests/test_engines.py,sha256=D0HaUbrC7cQRyXllPFSB-NnxzkwQw_eocfaw7ywkBUU,12554
+imaged/tests/test_engines_for_real.py,sha256=_PNvRK5-xUMxQPjnLe7NS0DWmnCaiU59BLP42NtgqyY,4622
+imaged-2026.7.2.dist-info/METADATA,sha256=L92dw7eIjAyj3gE08jNgp5NaX874YWufhSns-oYZCyE,3194
+imaged-2026.7.2.dist-info/WHEEL,sha256=lCkmxWfQsSc9CfIClYeavTdQeEX2toPqufh9gI35EQA,87
+imaged-2026.7.2.dist-info/licenses/COPYING,sha256=duktQE6d1JF-H9wu6teJU9N75pt5RjnoMCAsT6pavPo,1057
+imaged-2026.7.2.dist-info/RECORD,,

imaged-2026.7.2.dist-info/WHEEL

@@ -0,0 +1,4 @@
+Wheel-Version: 1.0
+Generator: hatchling 1.31.0
+Root-Is-Purelib: true
+Tag: py3-none-any

imaged-2026.7.2.dist-info/licenses/COPYING

@@ -0,0 +1,19 @@
+Copyright (c) 2026 Julian Berman
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in
+all copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN
+THE SOFTWARE.