dockercomposefile 0.1.0__py3-none-any.whl

dockercomposefile/__init__.py

@@ -0,0 +1,13 @@
+"""dockercomposefile - Pydantic models for Docker Compose files."""
+
+from __future__ import annotations
+
+from .builder import ComposeBuilder
+from .exporter import ComposeExporter
+from .models.compose import DockerComposeFile
+
+__all__ = [
+    "DockerComposeFile",
+    "ComposeBuilder",
+    "ComposeExporter",
+]

dockercomposefile/builder.py

@@ -0,0 +1,58 @@
+"""Builder module for parsing YAML into Pydantic models."""
+
+from __future__ import annotations
+
+from pathlib import Path
+from typing import Any
+
+import yaml
+
+from .models.compose import DockerComposeFile
+
+
+class ComposeBuilder:
+    """Build Pydantic DockerComposeFile models from YAML sources."""
+
+    @staticmethod
+    def from_file(path: str | Path) -> DockerComposeFile:
+        """Load a Compose file from a filesystem path.
+
+        Args:
+            path: Path to the YAML file.
+
+        Returns:
+            Parsed DockerComposeFile model.
+        """
+        path = Path(path)
+        with path.open("r", encoding="utf-8") as fh:
+            data = yaml.safe_load(fh)
+        if data is None:
+            data = {}
+        return ComposeBuilder.from_dict(data)
+
+    @staticmethod
+    def from_string(yaml_str: str) -> DockerComposeFile:
+        """Parse a Compose file from a YAML string.
+
+        Args:
+            yaml_str: YAML content as a string.
+
+        Returns:
+            Parsed DockerComposeFile model.
+        """
+        data = yaml.safe_load(yaml_str)
+        if data is None:
+            data = {}
+        return ComposeBuilder.from_dict(data)
+
+    @staticmethod
+    def from_dict(data: dict[str, Any]) -> DockerComposeFile:
+        """Build a DockerComposeFile model from a plain dictionary.
+
+        Args:
+            data: Dictionary representing the compose file structure.
+
+        Returns:
+            Parsed DockerComposeFile model.
+        """
+        return DockerComposeFile.model_validate(data)

dockercomposefile/exporter.py

@@ -0,0 +1,83 @@
+"""Exporter module for serializing Pydantic models to YAML."""
+
+from __future__ import annotations
+
+from pathlib import Path
+from typing import Any
+
+import yaml
+
+from .models.compose import DockerComposeFile
+
+
+class _CustomRepresenter(yaml.SafeDumper):
+    """Custom YAML representer that preserves empty dicts and ordering."""
+
+    def represent_none(self, data):
+        return self.represent_scalar("tag:yaml.org,2002:null", "")
+
+    def represent_empty_dict(self, data):
+        return self.represent_mapping("tag:yaml.org,2002:map", {})
+
+
+_CustomRepresenter.add_representer(type(None), _CustomRepresenter.represent_none)
+
+
+def _custom_dump(data: Any, stream: Any = None, **kwargs: Any) -> Any:
+    """Dump data to YAML with custom formatting."""
+    return yaml.dump(
+        data,
+        stream,
+        Dumper=_CustomRepresenter,
+        default_flow_style=False,
+        allow_unicode=True,
+        sort_keys=False,
+        width=float("inf"),
+        **kwargs,
+    )
+
+
+class ComposeExporter:
+    """Export Pydantic DockerComposeFile models to YAML."""
+
+    @staticmethod
+    def to_file(compose: DockerComposeFile, path: str | Path) -> None:
+        """Serialize a DockerComposeFile to a YAML file.
+
+        Args:
+            compose: The DockerComposeFile model to export.
+            path: Destination file path.
+        """
+        path = Path(path)
+        yaml_str = ComposeExporter.to_string(compose)
+        with path.open("w", encoding="utf-8") as fh:
+            fh.write(yaml_str)
+
+    @staticmethod
+    def to_string(compose: DockerComposeFile) -> str:
+        """Serialize a DockerComposeFile to a YAML string.
+
+        Args:
+            compose: The DockerComposeFile model to export.
+
+        Returns:
+            YAML string representation.
+        """
+        data = ComposeExporter.to_dict(compose)
+        return _custom_dump(data)
+
+    @staticmethod
+    def to_dict(compose: DockerComposeFile) -> dict[str, Any]:
+        """Serialize a DockerComposeFile to a plain dictionary.
+
+        Args:
+            compose: The DockerComposeFile model to export.
+
+        Returns:
+            Dictionary representation suitable for YAML serialization.
+        """
+        return compose.model_dump(
+            mode="json",
+            exclude_none=True,
+            by_alias=True,
+        )

dockercomposefile/models/__init__.py

@@ -0,0 +1,97 @@
+"""Pydantic models for Docker Compose files."""
+
+from .build import BuildConfig, BuildSecret
+from .common import ComposeBaseModel
+from .compose import DockerComposeFile, Include
+from .config import Config, ServiceConfig
+from .deploy import (
+    DeployConfig,
+    Placement,
+    PlacementPreference,
+    Resources,
+    ResourceLimits,
+    ResourceReservations,
+    RestartPolicy,
+    RollbackConfig,
+    UpdateConfig,
+)
+from .develop import DevelopConfig, WatchExec, WatchRule
+from .model import Model, ServiceModelConfig
+from .network import IPAM, IPAMConfig, Network, ServiceNetworkConfig
+from .secret import Secret, ServiceSecret
+from .service import (
+    BlkioConfig,
+    BlkioLimit,
+    BlkioWeight,
+    CredentialSpec,
+    DependsOnConfig,
+    EnvFileEntry,
+    ExtendsConfig,
+    GpuConfig,
+    Healthcheck,
+    Logging,
+    PortConfig,
+    PostStartHook,
+    ProviderConfig,
+    Service,
+    Ulimit,
+)
+from .volume import (
+    BindConfig,
+    ImageMountConfig,
+    TmpfsConfig,
+    Volume,
+    VolumeMount,
+    VolumeOptions,
+)
+
+__all__ = [
+    "BindConfig",
+    "BlkioConfig",
+    "BlkioLimit",
+    "BlkioWeight",
+    "BuildConfig",
+    "BuildSecret",
+    "ComposeBaseModel",
+    "DockerComposeFile",
+    "Config",
+    "CredentialSpec",
+    "DeployConfig",
+    "DependsOnConfig",
+    "DevelopConfig",
+    "EnvFileEntry",
+    "ExtendsConfig",
+    "GpuConfig",
+    "Healthcheck",
+    "IPAM",
+    "IPAMConfig",
+    "ImageMountConfig",
+    "Include",
+    "Logging",
+    "Model",
+    "Network",
+    "Placement",
+    "PlacementPreference",
+    "PortConfig",
+    "PostStartHook",
+    "ProviderConfig",
+    "ResourceLimits",
+    "ResourceReservations",
+    "Resources",
+    "RestartPolicy",
+    "RollbackConfig",
+    "Secret",
+    "Service",
+    "ServiceConfig",
+    "ServiceModelConfig",
+    "ServiceNetworkConfig",
+    "ServiceSecret",
+    "TmpfsConfig",
+    "Ulimit",
+    "UpdateConfig",
+    "Volume",
+    "VolumeMount",
+    "VolumeOptions",
+    "WatchExec",
+    "WatchRule",
+]

dockercomposefile/models/build.py

@@ -0,0 +1,123 @@
+"""Build configuration models."""
+
+from __future__ import annotations
+
+from typing import Any
+
+from pydantic import BaseModel, Field, field_validator
+
+from .common import (
+    ComposeBaseModel,
+    _parse_additional_contexts,
+    _parse_list_or_dict,
+    validate_byte_value,
+)
+
+
+class BuildSecret(BaseModel):
+    """Secret reference for build."""
+
+    source: str
+    target: str | None = None
+    uid: str | None = None
+    gid: str | None = None
+    mode: str | None = None
+
+
+class BuildConfig(ComposeBaseModel):
+    """Build configuration for a service."""
+
+    context: str | None = None
+    dockerfile: str | None = None
+    dockerfile_inline: str | None = None
+    args: dict[str, str | None] | list[str] | None = Field(
+        default=None, validate_default=True
+    )
+    ssh: str | list[str] | None = Field(default=None, validate_default=True)
+    labels: dict[str, str] | list[str] | None = Field(
+        default=None, validate_default=True
+    )
+    cache_from: list[str] | None = None
+    cache_to: list[str] | None = None
+    entitlements: list[str] | None = None
+    additional_contexts: dict[str, str] | list[str] | None = Field(
+        default=None, validate_default=True
+    )
+    isolation: str | None = None
+    network: str | None = None
+    shm_size: str | int | None = Field(default=None, validate_default=True)
+    target: str | None = None
+    platforms: list[str] | None = None
+    tags: list[str] | None = None
+    pull: bool | None = None
+    no_cache: bool | None = None
+    privileged: bool | None = None
+    secrets: list[str | BuildSecret] | None = Field(
+        default=None, validate_default=True
+    )
+    provenance: bool | str | None = None
+    sbom: bool | str | None = None
+    ulimits: dict[str, Any] | None = None
+    extra_hosts: dict[str, str] | list[str] | None = Field(
+        default=None, validate_default=True
+    )
+
+    @classmethod
+    def model_validate(cls, obj: Any) -> "BuildConfig":
+        if isinstance(obj, str):
+            obj = {"context": obj}
+        return super().model_validate(obj)
+
+    # -- validators ----------------------------------------------------------
+
+    @field_validator("args", mode="before")
+    @staticmethod
+    def _args(v: Any) -> dict[str, str | None] | list[str] | None:
+        return _parse_list_or_dict(v) if v is not None else None
+
+    @field_validator("ssh", mode="before")
+    @staticmethod
+    def _ssh(v: Any) -> str | list[str] | None:
+        return v if isinstance(v, (str, list)) or v is None else None
+
+    @field_validator("labels", mode="before")
+    @staticmethod
+    def _labels(v: Any) -> dict[str, str] | list[str] | None:
+        return _parse_list_or_dict(v) if v is not None else None
+
+    @field_validator("additional_contexts", mode="before")
+    @staticmethod
+    def _additional_contexts(v: Any) -> dict[str, str] | list[str] | None:
+        return _parse_additional_contexts(v) if v is not None else None
+
+    @field_validator("shm_size", mode="before")
+    @staticmethod
+    def _shm_size(v: Any) -> str | int | None:
+        return validate_byte_value(v)
+
+    @field_validator("secrets", mode="before")
+    @staticmethod
+    def _secrets(v: Any) -> list[str | BuildSecret] | None:
+        if v is None:
+            return None
+        if isinstance(v, list):
+            result: list[str | BuildSecret] = []
+            for item in v:
+                if isinstance(item, str):
+                    result.append(item)
+                elif isinstance(item, dict):
+                    result.append(BuildSecret.model_validate(item))
+            return result
+        return None
+
+    @field_validator("extra_hosts", mode="before")
+    @staticmethod
+    def _extra_hosts(v: Any) -> dict[str, str] | list[str] | None:
+        if v is None:
+            return None
+        if isinstance(v, dict):
+            return {str(k): str(val) for k, val in v.items()}
+        if isinstance(v, list):
+            return [str(item) for item in v]
+        return None
+