dockercomposefile 0.1.1

Pydantic models for Docker Compose files with YAML builder and exporter

dockercomposefile

Pydantic2 models for Docker Compose files with YAML builder and exporter.

Installation

pip install dockercomposefile

Usage

Parse a Compose file

from dockercomposefile import ComposeBuilder

# From a YAML string
compose = ComposeBuilder.from_string("""
services:
  web:
    image: nginx:latest
    ports:
      - "80:80"
""")

# From a file
compose = ComposeBuilder.from_file("docker-compose.yml")

# From a dictionary
compose = ComposeBuilder.from_dict({"services": {"web": {"image": "nginx"}}})

Access model data

# Access services
web = compose.services["web"]
print(web.image)  # nginx:latest

# Access ports (normalized to long form)
for port in web.ports:
    print(f"{port.target} -> {port.published}")

# Access networks
for name, network in compose.networks.items():
    print(f"Network: {name}, driver: {network.driver}")

Export to YAML

from dockercomposefile import ComposeExporter

# To a string
yaml_str = ComposeExporter.to_string(compose)

# To a file
ComposeExporter.to_file(compose, "docker-compose.yml")

# To a dictionary
data = ComposeExporter.to_dict(compose)

Create programmatically

from dockercomposefile.models import DockerComposeFile, Service

compose = DockerComposeFile(
    services={
        "web": Service(
            image="nginx:latest",
            ports=[{"target": 80, "published": "8080"}],
        ),
    },
)

Supported Compose Specification

The library models the full Docker Compose specification, including:

• Services: image, build, command, entrypoint, environment, ports, volumes, networks, depends_on, healthcheck, logging, deploy, develop, and more
• Networks: driver, driver_opts, ipam, external, labels
• Volumes: driver, driver_opts, external, labels
• Configs/Secrets: file, environment, content, external
• Models (AI): model, context_size, runtime_flags
• Build: context, dockerfile, args, cache_from, secrets, ssh, platforms
• Deploy: replicas, resources, placement, restart_policy, update_config
• Develop: watch rules for file syncing and rebuilds

Short syntax (e.g., ports: ["80:80"]) is automatically normalized to long form (structured objects) on parse. On export, the long form is emitted.

x-* extension fields are preserved on both parse and export.

Development

# Install with dev dependencies
pip install -e ".[dev]"

# Run tests
pytest

# Run tests with coverage
pytest --cov=dockercomposefile --cov-report=term-missing

License

MIT