from __future__ import annotations
from datetime import datetime
from pathlib import Path, PurePosixPath

KINDS = frozenset({"raw_html", "articles_text", "attachments"})


def build_reldir(site: str, column: str, when: datetime, kind: str) -> PurePosixPath:
    """Return POSIX-style relative directory (not including filename).

    Example: raw_html/gdqy/szfwj/2026/04
    """
    if kind not in KINDS:
        raise ValueError(f"unknown kind: {kind!r}; expected one of {sorted(KINDS)}")
    return PurePosixPath(kind, site, column, f"{when:%Y}", f"{when:%m}")


def to_os_path(root: Path | str, rel: PurePosixPath) -> Path:
    """Convert (data_dir, posix-relpath) -> OS-native absolute Path."""
    return Path(root).joinpath(*rel.parts)