dockercomposefile 0.1.0__py3-none-any.whl

dockercomposefile/models/common.py

@@ -0,0 +1,412 @@
+"""Common types and validators shared across all compose models."""
+
+from __future__ import annotations
+
+from typing import Any
+
+from pydantic import BaseModel, ConfigDict
+from pydantic_core import PydanticCustomError
+
+
+def _parse_list_or_dict(value: Any) -> dict[str, str | None]:
+    """Parse a value that can be either a dict or a list of KEY=VALUE strings."""
+    if value is None:
+        return {}
+    if isinstance(value, dict):
+        return {str(k): str(v) if v is not None else None for k, v in value.items()}
+    if isinstance(value, list):
+        result: dict[str, str | None] = {}
+        for item in value:
+            if isinstance(item, str):
+                if "=" in item:
+                    k, v = item.split("=", 1)
+                    result[k] = v
+                else:
+                    result[item] = None
+        return result
+    raise PydanticCustomError("list_or_dict", "Value must be a dict or list of strings")
+
+
+def _parse_string_or_list(value: Any) -> list[str]:
+    """Parse a value that can be either a string or a list of strings."""
+    if value is None:
+        return []
+    if isinstance(value, str):
+        return [value]
+    if isinstance(value, list):
+        return [str(item) for item in value]
+    raise PydanticCustomError("string_or_list", "Value must be a string or list of strings")
+
+
+def _parse_command(value: Any) -> str | list[str] | None:
+    """Parse a command that can be a string, a list of strings, or None."""
+    if value is None:
+        return None
+    if isinstance(value, str):
+        return value
+    if isinstance(value, list):
+        return [str(item) for item in value]
+    raise PydanticCustomError("command", "Command must be a string or list of strings")
+
+
+def validate_duration(value: Any) -> str | None:
+    """Validate a duration string.
+
+    Accepts formats like ``10s``, ``1m30s``, ``1h5m30s20ms``,
+    or plain integers (microseconds).
+    """
+    if value is None:
+        return None
+    if not isinstance(value, str):
+        raise PydanticCustomError("duration", "Duration must be a string")
+    # Plain integers are treated as microseconds
+    if value.isdigit():
+        return value
+
+    import re
+
+    _DURATION_RE = re.compile(r"^(\d+(?:\.\d+)?)(us|ms|s|m|h)$")
+    remaining = value
+    while remaining:
+        m = _DURATION_RE.match(remaining)
+        if not m:
+            raise PydanticCustomError(
+                "duration",
+                f"Invalid duration format: {value!r}",
+            )
+        remaining = remaining[m.end() :]
+    return value
+
+
+def validate_byte_value(value: Any) -> str | int | None:
+    """Validate a byte value string or integer.
+
+    Accepts formats like ``1gb``, ``300m``, ``1024kb``,
+    or plain integers (bytes).
+    """
+    if value is None:
+        return None
+    if isinstance(value, int):
+        return value
+    if isinstance(value, str):
+        if value.isdigit():
+            return int(value)
+        import re
+
+        _BYTE_VALUE_RE = re.compile(
+            r"^(\d+(?:\.\d+)?)\s*([kmgt]?b)$", re.IGNORECASE
+        )
+        _BYTE_VALUE_RE_2 = re.compile(r"^(\d+(?:\.\d+)?)\s*([kmgt])$", re.IGNORECASE)
+        m = _BYTE_VALUE_RE.match(value)
+        if not m:
+            m = _BYTE_VALUE_RE_2.match(value)
+        if not m:
+            raise PydanticCustomError(
+                "byte_value",
+                f"Invalid byte value format: {value!r}",
+            )
+        return value
+    raise PydanticCustomError("byte_value", "Byte value must be a string or integer")
+
+
+def _parse_port(value: Any) -> dict[str, Any]:
+    """Parse a port specification from short or long form."""
+    if isinstance(value, dict):
+        return dict(value)
+    if not isinstance(value, str):
+        raise PydanticCustomError("port", "Port must be a string or dict")
+
+    s = value.strip()
+
+    # Extract protocol
+    protocol: str | None = None
+    if "/" in s:
+        s, protocol = s.split("/", 1)
+
+    # Handle bracketed IPv6: [::1]:6000:6000
+    if s.startswith("["):
+        bracket_end = s.find("]")
+        if bracket_end == -1:
+            raise PydanticCustomError("port", f"Invalid port format: {value!r}")
+        host_ip = s[1:bracket_end]
+        rest = s[bracket_end + 1 :]
+        if rest.startswith(":"):
+            rest = rest[1:]
+        parts = rest.split(":")
+        if len(parts) == 2 and parts[0] and parts[1]:
+            return {
+                "host_ip": host_ip,
+                "published": parts[0],
+                "target": int(parts[1]),
+                **({"protocol": protocol} if protocol else {}),
+            }
+        if len(parts) == 1 and parts[0]:
+            return {
+                "host_ip": host_ip,
+                "target": int(parts[0]),
+                **({"protocol": protocol} if protocol else {}),
+            }
+        raise PydanticCustomError("port", f"Invalid port format: {value!r}")
+
+    parts = s.split(":")
+
+    if len(parts) == 1:
+        # Just container port
+        return {
+            "target": int(parts[0]),
+            **({"protocol": protocol} if protocol else {}),
+        }
+
+    if len(parts) == 2:
+        # HOST:CONTAINER  or  IP:CONTAINER
+        first, second = parts[0], parts[1]
+        if "." in first:
+            # IPv4 address without host port
+            return {
+                "host_ip": first,
+                "target": int(second),
+                **({"protocol": protocol} if protocol else {}),
+            }
+        return {
+            "published": first,
+            "target": int(second),
+            **({"protocol": protocol} if protocol else {}),
+        }
+
+    if len(parts) == 3:
+        # IP:HOST:CONTAINER
+        return {
+            "host_ip": parts[0],
+            "published": parts[1],
+            "target": int(parts[2]),
+            **({"protocol": protocol} if protocol else {}),
+        }
+
+    raise PydanticCustomError("port", f"Invalid port format: {value!r}")
+
+
+# Volume mount parsing (short syntax)
+_VOLUME_MOUNT_RE = __import__("re").compile(
+    r"^(?P<source>[^:]+):(?P<target>[^:]+)(?::(?P<mode>[^:]*))?$"
+)
+
+
+def _parse_service_volume(value: Any) -> dict[str, Any]:
+    """Parse a service volume mount from short or long form."""
+    if isinstance(value, dict):
+        return dict(value)
+    if not isinstance(value, str):
+        raise PydanticCustomError("volume", "Volume mount must be a string or dict")
+    m = _VOLUME_MOUNT_RE.match(value)
+    if not m:
+        # Could be a named volume without source (just target)
+        return {"type": "volume", "target": value}
+    source = m.group("source")
+    target = m.group("target")
+    mode = m.group("mode")
+    result: dict[str, Any] = {"target": target}
+    if source.startswith(".") or source.startswith("/") or source.startswith("~"):
+        result["type"] = "bind"
+        result["source"] = source
+    elif source.startswith("\\"):
+        result["type"] = "npipe"
+        result["source"] = source
+    else:
+        result["type"] = "volume"
+        result["source"] = source
+    if mode:
+        modes = mode.split(",")
+        if "ro" in modes:
+            result["read_only"] = True
+        if "z" in modes:
+            result.setdefault("bind", {})
+            result["bind"]["selinux"] = "z"
+        if "Z" in modes:
+            result.setdefault("bind", {})
+            result["bind"]["selinux"] = "Z"
+    return result
+
+
+def _parse_env_file(value: Any) -> list[dict[str, Any]] | None:
+    """Parse env_file which can be a string, list of strings, or list of objects."""
+    if value is None:
+        return None
+    if isinstance(value, str):
+        return [{"path": value, "required": True}]
+    if isinstance(value, list):
+        result: list[dict[str, Any]] = []
+        for item in value:
+            if isinstance(item, str):
+                result.append({"path": item, "required": True})
+            elif isinstance(item, dict):
+                result.append(dict(item))
+        return result
+    raise PydanticCustomError("env_file", "env_file must be a string or list")
+
+
+def _parse_external(value: Any) -> dict[str, Any] | bool:
+    """Parse external which can be a boolean or a dict with a name."""
+    if isinstance(value, bool):
+        return value
+    if isinstance(value, dict):
+        return dict(value)
+    raise PydanticCustomError("external", "external must be a boolean or dict")
+
+
+def _parse_extra_hosts(value: Any) -> dict[str, str] | None:
+    """Parse extra_hosts which can be a dict or list of HOST=IP strings."""
+    if value is None:
+        return None
+    if isinstance(value, dict):
+        return {str(k): str(v) for k, v in value.items()}
+    if isinstance(value, list):
+        result: dict[str, str] = {}
+        for item in value:
+            if isinstance(item, str):
+                sep = "=" if "=" in item else ":"
+                parts = item.split(sep, 1)
+                if len(parts) == 2:
+                    result[parts[0]] = parts[1]
+        return result
+    raise PydanticCustomError("extra_hosts", "extra_hosts must be a dict or list")
+
+
+def _parse_ulimits(value: Any) -> dict[str, Any] | None:
+    """Parse ulimits which can be a dict of int or dict with soft/hard."""
+    if value is None:
+        return None
+    if isinstance(value, dict):
+        return dict(value)
+    raise PydanticCustomError("ulimits", "ulimits must be a dict")
+
+
+def _parse_blkio_config(value: Any) -> dict[str, Any] | None:
+    """Parse blkio_config from input."""
+    if value is None:
+        return None
+    if isinstance(value, dict):
+        return dict(value)
+    raise PydanticCustomError("blkio_config", "blkio_config must be a dict")
+
+
+def _parse_depends_on(value: Any) -> dict[str, Any] | list[str] | None:
+    """Parse depends_on which can be a list of strings or a dict."""
+    if value is None:
+        return None
+    if isinstance(value, list):
+        return [str(item) for item in value]
+    if isinstance(value, dict):
+        return dict(value)
+    raise PydanticCustomError("depends_on", "depends_on must be a list or dict")
+
+
+def _parse_tmpfs(value: Any) -> list[str] | None:
+    """Parse tmpfs which can be a string or list of strings."""
+    if value is None:
+        return None
+    if isinstance(value, str):
+        return [value]
+    if isinstance(value, list):
+        return [str(item) for item in value]
+    raise PydanticCustomError("tmpfs", "tmpfs must be a string or list")
+
+
+def _parse_volumes_from(value: Any) -> list[str] | None:
+    """Parse volumes_from which is a list of strings."""
+    if value is None:
+        return None
+    if isinstance(value, str):
+        return [value]
+    if isinstance(value, list):
+        return [str(item) for item in value]
+    raise PydanticCustomError("volumes_from", "volumes_from must be a string or list")
+
+
+def _parse_annotations(value: Any) -> dict[str, str] | None:
+    """Parse annotations which can be a dict or list of KEY=VALUE strings."""
+    if value is None:
+        return None
+    return _parse_list_or_dict(value)
+
+
+def _parse_labels(value: Any) -> dict[str, str] | None:
+    """Parse labels which can be a dict or list of KEY=VALUE strings."""
+    if value is None:
+        return None
+    return _parse_list_or_dict(value)
+
+
+def _parse_environment(value: Any) -> dict[str, str | None] | None:
+    """Parse environment which can be a dict or list of KEY=VALUE strings."""
+    if value is None:
+        return None
+    return _parse_list_or_dict(value)
+
+
+def _parse_devices(value: Any) -> list[str] | None:
+    """Parse devices which is a list of strings."""
+    if value is None:
+        return None
+    if isinstance(value, str):
+        return [value]
+    if isinstance(value, list):
+        return [str(item) for item in value]
+    raise PydanticCustomError("devices", "devices must be a string or list")
+
+
+def _parse_dns(value: Any) -> str | list[str] | None:
+    """Parse dns which can be a string or list of strings."""
+    if value is None:
+        return None
+    if isinstance(value, str):
+        return value
+    if isinstance(value, list):
+        return [str(item) for item in value]
+    raise PydanticCustomError("dns", "dns must be a string or list")
+
+
+def _parse_configs_or_secrets(value: Any) -> list[dict[str, Any]] | list[str] | None:
+    """Parse configs/secrets which can be a list of strings or list of dicts."""
+    if value is None:
+        return None
+    if isinstance(value, list):
+        result: list[dict[str, Any] | str] = []
+        for item in value:
+            if isinstance(item, str):
+                result.append(item)
+            elif isinstance(item, dict):
+                result.append(dict(item))
+        return result
+    raise PydanticCustomError("configs_secrets", "Must be a list")
+
+
+def _parse_additional_contexts(value: Any) -> dict[str, str] | list[str] | None:
+    """Parse additional_contexts which can be a dict or list of NAME=VALUE strings."""
+    if value is None:
+        return None
+    if isinstance(value, dict):
+        return {str(k): str(v) for k, v in value.items()}
+    if isinstance(value, list):
+        result: dict[str, str] = {}
+        for item in value:
+            if isinstance(item, str) and "=" in item:
+                k, v = item.split("=", 1)
+                result[k] = v
+        return result
+    raise PydanticCustomError("additional_contexts", "Must be a dict or list")
+
+
+# ---------------------------------------------------------------------------
+# Model base class shared by all compose models
+# ---------------------------------------------------------------------------
+
+class ComposeBaseModel(BaseModel):
+    """Base model for all compose file models.
+
+    Allows extra fields for ``x-*`` extensions and unknown fields.
+    """
+
+    model_config = ConfigDict(
+        extra="allow",
+        populate_by_name=True,
+    )

dockercomposefile/models/compose.py

@@ -0,0 +1,58 @@
+"""Top-level DockerComposeFile model."""
+
+from __future__ import annotations
+
+from typing import Any
+
+from pydantic import model_validator
+
+from .common import ComposeBaseModel
+from .config import Config
+from .model import Model
+from .network import Network
+from .secret import Secret
+from .service import Service
+from .volume import Volume
+
+
+class Include(ComposeBaseModel):
+    """Include configuration for composing multiple files."""
+
+    path: list[str] | str | None = None
+    project_directory: str | None = None
+    env_file: list[str] | str | None = None
+
+
+class DockerComposeFile(ComposeBaseModel):
+    """Top-level Docker Compose file model."""
+
+    version: str | None = None
+    name: str | None = None
+    include: list[Include] | None = None
+    services: dict[str, Service] | None = None
+    networks: dict[str, Network] | None = None
+    volumes: dict[str, Volume] | None = None
+    configs: dict[str, Config] | None = None
+    secrets: dict[str, Secret] | None = None
+    models: dict[str, Model] | None = None
+
+    @model_validator(mode="before")
+    @staticmethod
+    def _normalize_none_values(data: Any) -> Any:
+        """Replace None values in resource dicts with empty dicts.
+
+        Docker Compose allows declaring resources with no attributes
+        (e.g. ``volumes:\n  frontend_build:``), which YAML parses as
+        ``None``. Convert these to empty dicts for Pydantic validation.
+        """
+        if not isinstance(data, dict):
+            return data
+        for key in ("networks", "volumes", "configs", "secrets"):
+            if key not in data or data[key] is None:
+                continue
+            resource = data[key]
+            if isinstance(resource, dict):
+                for name, value in list(resource.items()):
+                    if value is None:
+                        resource[name] = {}
+        return data

dockercomposefile/models/config.py

@@ -0,0 +1,45 @@
+"""Config models."""
+
+from __future__ import annotations
+
+from pydantic import Field, field_validator
+
+from .common import ComposeBaseModel, _parse_external, _parse_list_or_dict
+
+
+class Config(ComposeBaseModel):
+    """Top-level config definition."""
+
+    file: str | None = None
+    environment: str | None = None
+    content: str | None = None
+    external: bool | dict[str, str] | None = Field(
+        default=None, validate_default=True
+    )
+    name: str | None = None
+    labels: dict[str, str] | list[str] | None = Field(
+        default=None, validate_default=True
+    )
+    driver: str | None = None
+    driver_opts: dict[str, str | int] | None = None
+    template_driver: str | None = None
+
+    @field_validator("labels", mode="before")
+    @staticmethod
+    def _labels(v):
+        return _parse_list_or_dict(v) if v is not None else None
+
+    @field_validator("external", mode="before")
+    @staticmethod
+    def _external(v):
+        return _parse_external(v) if v is not None else None
+
+
+class ServiceConfig(ComposeBaseModel):
+    """Service-level config reference."""
+
+    source: str
+    target: str | None = None
+    uid: str | None = None
+    gid: str | None = None
+    mode: str | None = None

dockercomposefile/models/deploy.py

@@ -0,0 +1,117 @@
+"""Deploy configuration models."""
+
+from __future__ import annotations
+
+from typing import Any
+
+from pydantic import BaseModel, Field, field_validator
+
+from .common import ComposeBaseModel, validate_byte_value, validate_duration
+
+
+class PlacementPreference(BaseModel):
+    """Placement preference."""
+
+    spread: str | None = None
+
+
+class Placement(ComposeBaseModel):
+    """Placement constraints and preferences."""
+
+    constraints: list[str] | None = None
+    preferences: list[PlacementPreference] | None = None
+    max_replicas_per_node: int | None = None
+
+
+class ResourceLimits(ComposeBaseModel):
+    """Resource limits."""
+
+    cpus: str | None = None
+    memory: str | None = Field(default=None, validate_default=True)
+    pids: int | None = None
+
+    @field_validator("memory", mode="before")
+    @staticmethod
+    def _memory(v: Any) -> str | None:
+        return validate_byte_value(v)
+
+
+class ResourceReservations(ComposeBaseModel):
+    """Resource reservations."""
+
+    cpus: str | None = None
+    memory: str | None = Field(default=None, validate_default=True)
+    pids: int | None = None
+    devices: list[dict[str, Any]] | None = None
+
+    @field_validator("memory", mode="before")
+    @staticmethod
+    def _memory(v: Any) -> str | None:
+        return validate_byte_value(v)
+
+
+class Resources(ComposeBaseModel):
+    """Resource configuration."""
+
+    limits: ResourceLimits | None = None
+    reservations: ResourceReservations | None = None
+
+
+class RestartPolicy(ComposeBaseModel):
+    """Restart policy for deploy."""
+
+    condition: str | None = None
+    delay: str | None = Field(default=None, validate_default=True)
+    max_attempts: int | None = None
+    window: str | None = Field(default=None, validate_default=True)
+
+    @field_validator("delay", "window", mode="before")
+    @staticmethod
+    def _duration(v: Any) -> str | None:
+        return validate_duration(v)
+
+
+class UpdateConfig(ComposeBaseModel):
+    """Update configuration."""
+
+    parallelism: int | None = None
+    delay: str | None = Field(default=None, validate_default=True)
+    failure_action: str | None = None
+    monitor: str | None = Field(default=None, validate_default=True)
+    max_failure_ratio: float | None = None
+    order: str | None = None
+
+    @field_validator("delay", "monitor", mode="before")
+    @staticmethod
+    def _duration(v: Any) -> str | None:
+        return validate_duration(v)
+
+
+class RollbackConfig(ComposeBaseModel):
+    """Rollback configuration."""
+
+    parallelism: int | None = None
+    delay: str | None = Field(default=None, validate_default=True)
+    failure_action: str | None = None
+    monitor: str | None = Field(default=None, validate_default=True)
+    max_failure_ratio: float | None = None
+    order: str | None = None
+
+    @field_validator("delay", "monitor", mode="before")
+    @staticmethod
+    def _duration(v: Any) -> str | None:
+        return validate_duration(v)
+
+
+class DeployConfig(ComposeBaseModel):
+    """Deploy configuration for a service."""
+
+    endpoint_mode: str | None = None
+    labels: dict[str, str] | list[str] | None = None
+    mode: str | None = None
+    replicas: int | None = None
+    resources: Resources | None = None
+    placement: Placement | None = None
+    restart_policy: RestartPolicy | None = None
+    rollback_config: RollbackConfig | None = None
+    update_config: UpdateConfig | None = None

dockercomposefile/models/develop.py

@@ -0,0 +1,33 @@
+"""Development configuration models."""
+
+from __future__ import annotations
+
+from .common import ComposeBaseModel
+
+
+class WatchExec(ComposeBaseModel):
+    """Exec configuration for watch sync+exec action."""
+
+    command: str | list[str]
+    user: str | None = None
+    privileged: bool | None = None
+    working_dir: str | None = None
+    environment: dict[str, str] | list[str] | None = None
+
+
+class WatchRule(ComposeBaseModel):
+    """Watch rule for development."""
+
+    path: str
+    action: str
+    target: str | None = None
+    ignore: list[str] | None = None
+    include: list[str] | None = None
+    initial_sync: bool | None = None
+    exec: WatchExec | None = None
+
+
+class DevelopConfig(ComposeBaseModel):
+    """Development configuration for a service."""
+
+    watch: list[WatchRule] | None = None

dockercomposefile/models/model.py

@@ -0,0 +1,20 @@
+"""AI model models."""
+
+from __future__ import annotations
+
+from .common import ComposeBaseModel
+
+
+class Model(ComposeBaseModel):
+    """Top-level AI model definition."""
+
+    model: str
+    context_size: int | None = None
+    runtime_flags: list[str] | None = None
+
+
+class ServiceModelConfig(ComposeBaseModel):
+    """Service-level model reference (long syntax)."""
+
+    endpoint_var: str | None = None
+    model_var: str | None = None