imaged 2026.7.2__tar.gz

imaged-2026.7.2/.gitattributes

@@ -0,0 +1 @@
+* text=auto eol=lf

imaged-2026.7.2/.github/FUNDING.yml

@@ -0,0 +1,3 @@
+# These are supported funding model platforms
+
+github: "Julian"

imaged-2026.7.2/.github/SECURITY.md

@@ -0,0 +1,15 @@
+# Security Policy
+
+## Supported Versions
+
+In general, only the latest released `imaged` version is supported and will receive updates.
+
+## Reporting a Vulnerability
+
+To report a security vulnerability, please send an email to `Julian+Security` at `GrayVines.com` with subject line `SECURITY (imaged)`.
+
+I will do my best to respond within 48 hours to acknowledge the message and discuss further steps.
+
+If the vulnerability is accepted, an advisory will be sent out via GitHub's security advisory functionality.
+
+For non-sensitive discussion related to this policy itself, feel free to open an issue on the issue tracker.

imaged-2026.7.2/.github/dependabot.yml

@@ -0,0 +1,8 @@
+version: 2
+updates:
+  - package-ecosystem: "github-actions"
+    directory: "/"
+    schedule:
+      interval: "weekly"
+    cooldown:
+      default-days: 7

imaged-2026.7.2/.github/workflows/ci.yml

@@ -0,0 +1,154 @@
+name: CI
+
+on:
+  push:
+    branches-ignore:
+      - "wip*"
+    tags:
+      - "v*"
+  pull_request:
+  schedule:
+    # Daily at 7:47
+    - cron: "47 7 * * *"
+  workflow_dispatch:
+
+permissions: {}
+
+concurrency:
+  group: ${{ github.workflow }}-${{ github.ref }}
+  cancel-in-progress: true
+
+jobs:
+  list:
+    name: Identify nox sessions
+    runs-on: ubuntu-latest
+    outputs:
+      noxenvs: ${{ steps.noxenvs-matrix.outputs.noxenvs }}
+    steps:
+      - uses: actions/checkout@3d3c42e5aac5ba805825da76410c181273ba90b1  # v7.0.1
+        with:
+          persist-credentials: false
+      - name: Set up uv
+        uses: astral-sh/setup-uv@c771a70e6277c0a99b617c7a806ffedaca235ff9  # v9.0.0
+        with:
+          enable-cache: ${{ github.ref_type != 'tag' }} # zizmor: ignore[cache-poisoning]
+      - id: noxenvs-matrix
+        run: |
+          echo >>$GITHUB_OUTPUT noxenvs=$(
+            uvx nox --list-sessions --json | jq '[.[].session]'
+          )
+
+  ci:
+    name: ${{ matrix.noxenv }} (${{ matrix.os }})
+    needs: list
+    runs-on: ${{ matrix.os }}
+
+    strategy:
+      fail-fast: false
+      matrix:
+        os: [macos-latest, ubuntu-latest, windows-latest]
+        noxenv: ${{ fromJson(needs.list.outputs.noxenvs) }}
+        posargs: [""]
+        include:
+          - os: ubuntu-latest
+            noxenv: "tests-3.14"
+            posargs: coverage github
+
+    steps:
+      - uses: actions/checkout@3d3c42e5aac5ba805825da76410c181273ba90b1  # v7.0.1
+        with:
+          persist-credentials: false
+      - name: Install dependencies
+        run: sudo apt-get update && sudo apt-get install -y libenchant-2-dev
+        if: runner.os == 'Linux' && startsWith(matrix.noxenv, 'docs')
+      - name: Install dependencies
+        run: brew install enchant
+        if: runner.os == 'macOS' && startsWith(matrix.noxenv, 'docs')
+
+      - name: Set up uv
+        uses: astral-sh/setup-uv@c771a70e6277c0a99b617c7a806ffedaca235ff9  # v9.0.0
+        with:
+          enable-cache: ${{ github.ref_type != 'tag' }} # zizmor: ignore[cache-poisoning]
+      - name: Run nox
+        run: uvx nox -s "${{ matrix.noxenv }}" -- ${{ matrix.posargs }} # zizmor: ignore[template-injection]
+
+  engines:
+    # The tests above drive a stand-in engine, which is what makes them
+    # runnable everywhere.  These drive the real thing, once per engine,
+    # because the entire promise of this package is that all of them
+    # answer identically.
+    name: ${{ matrix.engine }}
+    runs-on: ${{ matrix.os }}
+
+    strategy:
+      fail-fast: false
+      matrix:
+        include:
+          - engine: docker
+            os: ubuntu-latest
+          - engine: podman
+            os: ubuntu-latest
+          # No engine can run on GitHub's hosted macOS runners.  Every
+          # one of them needs a Linux VM there, and those runners are
+          # themselves VMs without nested virtualization
+          # (actions/runner-images#13505), so podman's vfkit and
+          # colima's lima both fail to start one -- as would Apple's
+          # container, which wants Virtualization.framework directly.
+          # Covering macOS at all needs a self-hosted Apple silicon
+          # runner, at which point this becomes:
+          #
+          #   - engine: container
+          #     os: [self-hosted, macOS, ARM64]
+
+    steps:
+      - uses: actions/checkout@3d3c42e5aac5ba805825da76410c181273ba90b1  # v7.0.1
+        with:
+          persist-credentials: false
+
+      - name: Install podman
+        run: sudo apt-get update && sudo apt-get install -y podman
+        if: matrix.engine == 'podman'
+
+
+      - name: Set up uv
+        uses: astral-sh/setup-uv@c771a70e6277c0a99b617c7a806ffedaca235ff9  # v9.0.0
+        with:
+          enable-cache: ${{ github.ref_type != 'tag' }} # zizmor: ignore[cache-poisoning]
+
+      - name: Run the tests against ${{ matrix.engine }}
+        env:
+          IMAGED_ENGINE: ${{ matrix.engine }}
+        run: uvx nox -s tests-3.14 -- -m real
+
+  packaging:
+    name: Build and publish
+    needs: [ci, engines]
+    runs-on: ubuntu-latest
+    environment:
+      name: PyPI
+      url: https://pypi.org/p/imaged
+
+    permissions:
+      contents: write  # for creating releases
+      id-token: write  # for trusted publishing to PyPI
+
+    steps:
+      - uses: actions/checkout@3d3c42e5aac5ba805825da76410c181273ba90b1  # v7.0.1
+        with:
+          persist-credentials: false
+      - name: Set up uv
+        uses: astral-sh/setup-uv@c771a70e6277c0a99b617c7a806ffedaca235ff9  # v9.0.0
+        with:
+          enable-cache: ${{ github.ref_type != 'tag' }} # zizmor: ignore[cache-poisoning]
+
+      - name: Build our distributions
+        run: uv run --frozen --with 'build[uv]' -m build --installer=uv
+
+      - name: Publish to PyPI
+        if: github.event_name == 'push' && startsWith(github.event.ref, 'refs/tags')
+        uses: pypa/gh-action-pypi-publish@ba38be9e461d3875417946c167d0b5f3d385a247  # v1.14.1
+      - name: Create a Release
+        if: github.event_name == 'push' && startsWith(github.event.ref, 'refs/tags')
+        run: gh release create ${{ github.ref_name }} dist/* --generate-notes # zizmor: ignore[template-injection]
+        env:
+          GH_TOKEN: ${{ github.token }}

imaged-2026.7.2/.pre-commit-config.yaml

@@ -0,0 +1,25 @@
+repos:
+  - repo: https://github.com/pre-commit/pre-commit-hooks
+    rev: v6.0.0
+    hooks:
+      - id: check-added-large-files
+      - id: check-ast
+      - id: check-toml
+      - id: check-vcs-permalinks
+      - id: check-yaml
+      - id: debug-statements
+      - id: end-of-file-fixer
+      - id: mixed-line-ending
+        args: [--fix, lf]
+      - id: trailing-whitespace
+  - repo: https://github.com/astral-sh/ruff-pre-commit
+    rev: "v0.15.10"
+    hooks:
+      - id: ruff-check
+        args: [--fix, --exit-non-zero-on-fix]
+      - id: ruff-format
+  - repo: https://github.com/zizmorcore/zizmor-pre-commit
+    rev: v1.23.1
+    hooks:
+      - id: zizmor
+        args: [--pedantic]

imaged-2026.7.2/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.

imaged-2026.7.2/PKG-INFO

@@ -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/README.rst

@@ -0,0 +1,61 @@
+==========
+``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/docs/.readthedocs.yaml

@@ -0,0 +1,19 @@
+version: 2
+
+build:
+  os: ubuntu-24.04
+  tools:
+    python: "3.13"
+
+  jobs:
+    post_create_environment:
+      - pip install uv
+    post_install:
+      - VIRTUAL_ENV=$READTHEDOCS_VIRTUALENV_PATH uv sync --group=docs
+
+sphinx:
+  builder: dirhtml
+  configuration: docs/conf.py
+  fail_on_warning: true
+
+formats: all

imaged-2026.7.2/docs/conf.py

@@ -0,0 +1,58 @@
+import importlib.metadata
+import re
+
+project = "imaged"
+author = "Julian Berman"
+copyright = f"2026, {author}"
+
+release = importlib.metadata.version("imaged")
+version, _, _ = release.rpartition(".")
+
+language = "en"
+default_role = "any"
+
+extensions = [
+    "sphinx.ext.autodoc",
+    "sphinx.ext.autosectionlabel",
+    "sphinx.ext.coverage",
+    "sphinx.ext.doctest",
+    "sphinx.ext.intersphinx",
+    "sphinx.ext.napoleon",
+    "sphinx.ext.viewcode",
+    "sphinxcontrib.spelling",
+    "sphinxext.opengraph",
+]
+
+pygments_style = "lovelace"
+pygments_dark_style = "one-dark"
+
+html_theme = "furo"
+
+
+def entire_domain(host):
+    return r"http.?://" + re.escape(host) + r"($|/.*)"
+
+
+linkcheck_ignore = [
+    entire_domain("img.shields.io"),
+    "https://github.com/Julian/imaged/actions",
+    "https://github.com/Julian/imaged/workflows/CI/badge.svg",
+    # Links which only exist once we exist as a package.
+    # Read the Docs has no stable version until something is released,
+    # and a release can't happen while this is what fails the build.
+    # TODO: remove both once the first release has been built.
+    "https://pypi.org/project/imaged/",
+    entire_domain("imaged.readthedocs.io"),
+]
+
+
+# = Extensions =
+
+# -- autosectionlabel --
+
+autosectionlabel_prefix_document = True
+
+# -- sphinxcontrib-spelling --
+
+spelling_word_list_filename = "spelling-wordlist.txt"
+spelling_show_suggestions = True

imaged-2026.7.2/docs/index.rst

@@ -0,0 +1,9 @@
+.. include:: ../README.rst
+
+
+Contents
+--------
+
+.. toctree::
+    :glob:
+    :maxdepth: 2

imaged-2026.7.2/docs/spelling-wordlist.txt

@@ -0,0 +1,10 @@
+anyio
+async
+asyncio
+demultiplex
+podman
+readably
+runtime
+stdio
+substrings
+trio

imaged-2026.7.2/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",
+]