utils.py

from __future__ import annotations

import logging
import re
import shutil
import subprocess
from pathlib import Path
from typing import Iterable, Sequence, TypeVar

T = TypeVar("T")


class UserFacingError(Exception):
    """Error type shown directly to the user."""


class DependencyError(UserFacingError):
    """Raised when an external dependency is missing or unreachable."""


class ProcessingError(UserFacingError):
    """Raised when a processing stage fails."""


def setup_logging(log_level: int = logging.INFO) -> logging.Logger:
    logger = logging.getLogger("roman_urdu_srt_generator")
    if logger.handlers:
        return logger

    logger.setLevel(log_level)
    logger.propagate = False

    formatter = logging.Formatter("%(asctime)s | %(levelname)s | %(message)s")
    stream_handler = logging.StreamHandler()
    stream_handler.setFormatter(formatter)
    logger.addHandler(stream_handler)
    return logger


def ensure_directory(path: Path) -> Path:
    path.mkdir(parents=True, exist_ok=True)
    return path


def safe_filename(name: str) -> str:
    stem = Path(name).stem.strip() or "video"
    cleaned = re.sub(r"[^A-Za-z0-9._-]+", "_", stem)
    cleaned = re.sub(r"_+", "_", cleaned).strip("._-")
    return cleaned or "video"


def is_valid_video_name(name: str) -> bool:
    suffix = Path(name).suffix.lower().lstrip(".")
    return suffix in {"mp4", "mkv", "mov", "avi", "webm", "m4v", "flv", "mpeg", "mpg"}


def command_exists(command: str) -> bool:
    return shutil.which(command) is not None


def run_command(
    command: Sequence[str],
    *,
    timeout: int | None = None,
    cwd: Path | None = None,
) -> subprocess.CompletedProcess[str]:
    return subprocess.run(
        list(command),
        cwd=str(cwd) if cwd else None,
        capture_output=True,
        text=True,
        timeout=timeout,
        check=False,
        shell=False,
    )


def chunked(items: Sequence[T], size: int) -> Iterable[list[T]]:
    if size <= 0:
        raise ValueError("Chunk size must be greater than zero.")

    total = len(items)
    for start in range(0, total, size):
        yield list(items[start : start + size])


def strip_code_fences(text: str) -> str:
    stripped = text.strip()
    if stripped.startswith("```"):
        stripped = re.sub(r"^```[a-zA-Z0-9_-]*\s*", "", stripped)
        stripped = re.sub(r"\s*```$", "", stripped)
    return stripped.strip()


def normalize_whitespace(text: str) -> str:
    return re.sub(r"\s+", " ", text).strip()