Dragonfly Container

High-performance, unified Docker and Podman container management library.

中文文档：see README.zh-CN.md

Links

• GitHub: https://github.com/10000ms/dragonfly_container
• Issues: https://github.com/10000ms/dragonfly_container/issues
• Changelog: https://github.com/10000ms/dragonfly_container/blob/master/CHANGELOG.md

Why this library

If your runtime environment may have Docker or Podman (or both), you often end up maintaining two code paths:

• A Python SDK-based path for fast, structured operations (list/inspect/stats/logs)
• A CLI-based compose path for orchestration (up/down/start/stop/restart/scale)

Dragonfly Container provides a unified executor that exposes both layers behind one interface.

Features

• Unified engine detection (Docker first, then Podman)
• Dual architecture: API executors (SDK) + Compose executors (CLI)
• Security hardening: argument validation + command sanitization to reduce injection risk
• Compatibility helpers: normalize differences between Docker and Podman commands
• Async-first API calls
• Typed models (Pydantic) and py.typed for type checkers

Installation

# Core library
pip install dragonfly-container

# With Docker SDK support
pip install dragonfly-container[docker]

# With Podman SDK support
pip install dragonfly-container[podman]

# Everything
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",
    )

    # API layer (fast, structured)
    containers = await executor.list_containers(all=True)
    for c in containers:
        print(f"{c.name}: {c.status}")

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

    await executor.cleanup()


asyncio.run(main())

Concepts

1) API executors (SDK)

Use this when you need structured data and low-latency operations:

• list/inspect containers and images
• logs and stats
• basic lifecycle (start/stop/restart)

2) Compose executors (CLI)

Use this when you need orchestration via docker compose / podman compose:

• start/stop/restart a stack
• rebuild images
• scale services
• follow logs

3) UnifiedExecutor

UnifiedExecutor exposes both capabilities so that your business code doesn't need to know which engine is available.

Typical use cases

• Local development environments with mixed Docker/Podman setups
• CI jobs that need to bring up a compose stack and then run API-level assertions
• DevOps automation for health checks, stats collection, and restart workflows

Security notes

• Compose commands are returned as an argument list (for subprocess.run([...])) to avoid shell injection.
• Inputs are validated and sanitized where commands are constructed.

Project layout

• dragonfly_container/: library code
• tests/: test suite
• docs/index.html: GitHub Pages landing page

Versioning

The package version is sourced from dragonfly_container/__version__.py.

License

MIT License. See LICENSE.

Made with ❤️ by Victor Lai