"""Path utilities.

Provides `create_path_with_todays_date` compatible with the legacy
integration_scripts.file_utils usage.
"""
from __future__ import annotations

from datetime import datetime
from pathlib import Path


def create_path_with_todays_date(
    base_dir: str | Path,
    subdir: bool = True,
    timestamp: bool = True,
) -> str:
    """Return a path under `base_dir` with today's date and optional timestamp.

    Creates a simple directory structure without year/month/day subfolders.
    If `timestamp` is True, an additional leaf directory with
    `%Y-%m-%d_%H_%M_%S` is appended.

    The returned path is a string to match legacy expectations.
    """
    base = Path(base_dir)
    today = datetime.today()

    parts: list[str] = []
    # No longer creating year/month/day subfolders
    if timestamp:
        parts.append(today.strftime("%Y-%m-%d_%H_%M_%S"))

    if parts:
        target = base.joinpath(*parts)
    else:
        target = base

    target.mkdir(parents=True, exist_ok=True)
    return str(target)