Metadata-Version: 2.4
Name: dragonfly-container
Version: 0.0.1
Summary: High-performance unified Docker and Podman container management library
Author-email: Victor Lai <victor.lai@foxmail.com>
Maintainer-email: Victor Lai <victor.lai@foxmail.com>
License-Expression: MIT
Project-URL: Homepage, https://github.com/10000ms/dragonfly_container
Project-URL: Documentation, https://dragonfly-container.readthedocs.io
Project-URL: Repository, https://github.com/10000ms/dragonfly_container
Project-URL: Bug Tracker, https://github.com/10000ms/dragonfly_container/issues
Project-URL: Changelog, https://github.com/10000ms/dragonfly_container/blob/master/CHANGELOG.md
Keywords: docker,podman,container,docker-compose,podman-compose,container-management,orchestration,devops,async,python3
Classifier: Development Status :: 4 - Beta
Classifier: Intended Audience :: Developers
Classifier: Operating System :: OS Independent
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3.10
Classifier: Programming Language :: Python :: 3.11
Classifier: Programming Language :: Python :: 3.12
Classifier: Programming Language :: Python :: 3 :: Only
Classifier: Topic :: Software Development :: Libraries :: Python Modules
Classifier: Topic :: System :: Systems Administration
Classifier: Typing :: Typed
Classifier: Framework :: AsyncIO
Requires-Python: >=3.10
Description-Content-Type: text/markdown
License-File: LICENSE
Requires-Dist: pydantic<3.0.0,>=2.0.0
Provides-Extra: docker
Requires-Dist: docker<8.0.0,>=7.0.0; extra == "docker"
Provides-Extra: podman
Requires-Dist: podman<6.0.0,>=5.0.0; extra == "podman"
Provides-Extra: all
Requires-Dist: docker<8.0.0,>=7.0.0; extra == "all"
Requires-Dist: podman<6.0.0,>=5.0.0; extra == "all"
Provides-Extra: dev
Requires-Dist: pytest>=8.0.0; extra == "dev"
Requires-Dist: pytest-asyncio>=0.23.0; extra == "dev"
Requires-Dist: pytest-cov>=4.1.0; extra == "dev"
Requires-Dist: pytest-mock>=3.12.0; extra == "dev"
Requires-Dist: black>=24.0.0; extra == "dev"
Requires-Dist: flake8>=7.0.0; extra == "dev"
Requires-Dist: isort>=5.13.0; extra == "dev"
Requires-Dist: mypy>=1.8.0; extra == "dev"
Requires-Dist: pre-commit>=3.6.0; extra == "dev"
Provides-Extra: docs
Requires-Dist: mkdocs>=1.5.0; extra == "docs"
Requires-Dist: mkdocs-material>=9.5.0; extra == "docs"
Requires-Dist: mkdocstrings[python]>=0.24.0; extra == "docs"
Dynamic: license-file

# Dragonfly Container

[![Python Version](https://img.shields.io/badge/python-3.10%2B-blue.svg)](https://www.python.org/downloads/)
[![License](https://img.shields.io/badge/license-MIT-green.svg)](LICENSE)
[![Code Style](https://img.shields.io/badge/code%20style-black-000000.svg)](https://github.com/psf/black)

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

中文文档：see [README.zh-CN.md](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

```bash
# 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

```python
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
