"""YamlPort - Port for YAML operations.

Contract: CNT-T1-PRT-003
Traceability: UC-001, UC-004, UC-005
"""

from pathlib import Path
from typing import Any, Protocol


class YamlPort(Protocol):
    """Port interface for YAML operations.

    This protocol defines the contract for YAML parsing and serialization.
    Implementations should handle encoding, formatting, and error handling.
    """

    def parse(self, content: str) -> dict[str, Any]:
        """Parse YAML string to dictionary.

        Args:
            content: YAML string

        Returns:
            Parsed dictionary

        Raises:
            ValueError: If parsing fails
        """
        ...

    def dump(self, data: dict[str, Any]) -> str:
        """Dump dictionary to YAML string.

        Args:
            data: Dictionary to dump

        Returns:
            YAML string
        """
        ...

    def parse_file(self, path: Path) -> dict[str, Any]:
        """Parse YAML file to dictionary.

        Args:
            path: Path to YAML file

        Returns:
            Parsed dictionary

        Raises:
            FileNotFoundError: If file does not exist
            ValueError: If parsing fails
        """
        ...

    def dump_file(self, path: Path, data: dict[str, Any]) -> None:
        """Dump dictionary to YAML file.

        Args:
            path: Path to output file
            data: Dictionary to dump
        """
        ...
