#046 gdtest_kitchen_sink

"""
Kitchen Sink — a comprehensive test package.

This package exercises every major Great Docs feature in a single
codebase.
"""

__version__ = "1.0.0"
__all__ = [
    "Pipeline",
    "Config",
    "Status",
    "Result",
    "run_pipeline",
    "validate_config",
    "format_output",
    "parse_input",
    "helper_a",
    "helper_b",
]

from dataclasses import dataclass, field
from enum import Enum


# ── Big class (>5 methods → separate method section) ──────────

class Pipeline:
    """
    A data processing pipeline with many operations.

    Parameters
    ----------
    name
        Pipeline name.
    """

    def __init__(self, name: str):
        self.name = name
        self._steps = []

    def add_step(self, step) -> "Pipeline":
        """
        Add a processing step.

        Parameters
        ----------
        step
            The step to add.

        Returns
        -------
        Pipeline
            Self, for chaining.
        """
        self._steps.append(step)
        return self

    def remove_step(self, index: int) -> "Pipeline":
        """
        Remove a step by index.

        Parameters
        ----------
        index
            The step index to remove.

        Returns
        -------
        Pipeline
            Self, for chaining.
        """
        self._steps.pop(index)
        return self

    def run(self) -> "Result":
        """
        Execute the pipeline.

        Returns
        -------
        Result
            The pipeline result.
        """
        return Result(status=Status.SUCCESS, message="done")

    def validate(self) -> bool:
        """
        Check that the pipeline is correctly configured.

        Returns
        -------
        bool
            True if valid.
        """
        return len(self._steps) > 0

    def reset(self) -> None:
        """Clear all steps from the pipeline."""
        self._steps.clear()

    def summary(self) -> dict:
        """
        Return a summary of the pipeline.

        Returns
        -------
        dict
            Summary with name, step count, etc.
        """
        return {"name": self.name, "steps": len(self._steps)}


# ── Small class (≤5 methods → inline docs) ────────────────────

class Config:
    """
    Configuration container for a pipeline.

    Parameters
    ----------
    settings
        A dictionary of settings.
    """

    def __init__(self, settings: dict | None = None):
        self._settings = settings or {}

    def get(self, key: str, default=None):
        """
        Get a config value.

        Parameters
        ----------
        key
            Setting key.
        default
            Default if key not found.

        Returns
        -------
        object
            The setting value.
        """
        return self._settings.get(key, default)

    def set(self, key: str, value) -> None:
        """
        Set a config value.

        Parameters
        ----------
        key
            Setting key.
        value
            New value.
        """
        self._settings[key] = value


# ── Enum ──────────────────────────────────────────────────────

class Status(Enum):
    """
    Pipeline execution status.
    """
    SUCCESS = "success"
    FAILURE = "failure"
    PENDING = "pending"
    SKIPPED = "skipped"


# ── Dataclass ─────────────────────────────────────────────────

@dataclass
class Result:
    """
    The result of a pipeline execution.

    Parameters
    ----------
    status
        Execution status.
    message
        Human-readable message.
    errors
        List of error strings, if any.
    """
    status: Status
    message: str = ""
    errors: list[str] = field(default_factory=list)


# ── Functions ─────────────────────────────────────────────────

def run_pipeline(name: str, **kwargs) -> Result:
    """
    High-level function to create and run a pipeline.

    Parameters
    ----------
    name
        Pipeline name.
    **kwargs
        Passed to Pipeline constructor.

    Returns
    -------
    Result
        The execution result.
    """
    return Pipeline(name).run()


def validate_config(config: Config) -> bool:
    """
    Validate a configuration object.

    Parameters
    ----------
    config
        The config to validate.

    Returns
    -------
    bool
        True if valid.
    """
    return True


def format_output(result: Result, fmt: str = "text") -> str:
    """
    Format a result for display.

    Parameters
    ----------
    result
        The result to format.
    fmt
        Output format (text, json, html).

    Returns
    -------
    str
        Formatted output.
    """
    return str(result)


def parse_input(raw: str) -> dict:
    """
    Parse raw input into a structured dict.

    Parameters
    ----------
    raw
        Raw input string.

    Returns
    -------
    dict
        Parsed data.
    """
    return {"raw": raw}


def helper_a() -> None:
    """
    A general-purpose helper function.

    Returns
    -------
    None
    """
    pass


def helper_b() -> None:
    """
    Another general-purpose helper.

    Returns
    -------
    None
    """
    pass