Dragonfly Container

What it provides

它提供什么

Unified engine detection (Docker first, then Podman)
API layer (SDK): structured list/inspect/stats/logs operations
Compose layer (CLI): orchestration via docker compose / podman compose
Security hardening: returns argv lists for subprocess execution
Typed models: Pydantic + py.typed

统一引擎检测（优先 Docker，其次 Podman）
API 层（SDK）：结构化 list/inspect/stats/logs
Compose 层（CLI）：通过 docker compose / podman compose 进行编排
安全加固：返回 argv 参数列表，便于安全地用 subprocess 执行
类型支持：Pydantic + py.typed

链接

GitHub README (EN) README (中文) Issues

Language preference is saved locally in your browser.

语言选择会保存在浏览器本地。

Install

安装

pip install dragonfly-container

# Optional
pip install dragonfly-container[docker]
pip install dragonfly-container[podman]
pip install dragonfly-container[all]

Quick start

快速开始

import asyncio
import subprocess

from dragonfly_container import ExecutorFactory


async def main() -> None:
    executor = ExecutorFactory.create_unified_executor(
        compose_file="/path/to/docker-compose.yml",
        project_name="myproject",
    )

    containers = await executor.list_containers(all=True)
    for c in containers:
        print(f"{c.name}: {c.status}")

    cmd = executor.get_start_command(service_names=["web", "db"], build=True)
    subprocess.run(cmd, check=True)

    await executor.cleanup()


asyncio.run(main())

How to use

如何使用

Use the API layer when you need low-latency, structured data for monitoring, automation, or assertions. Use the Compose layer when you need orchestration for a service stack.

The UnifiedExecutor exposes both so your business logic stays engine-agnostic.

需要监控/自动化/断言这类“结构化数据”的场景，优先用 API 层；需要编排服务栈（up/down/scale/rebuild）时，使用 Compose 层。

UnifiedExecutor 同时暴露两种能力，业务逻辑无需关心宿主机上实际可用的是 Docker 还是 Podman。

Security note

安全说明

Compose commands are returned as an argument list (argv). Prefer:

subprocess.run(cmd, check=True)

Avoid building a shell string and using shell=True for untrusted inputs.

Compose 命令以 argv 参数列表返回，建议直接：

subprocess.run(cmd, check=True)

避免把不可信输入拼成 shell 字符串并使用 shell=True。