Source code for satorbis_kit.pgstac.uploader.filename

"""Helpers for building STAC-compliant filenames."""

from __future__ import annotations

from datetime import date, datetime
from typing import Optional, Union

from ...storage import StorageError

DateInput = Union[str, date, datetime]




def build_stac_filename(acquisition_date: DateInput, tile: Optional[str] = None) -> str:
    """Build the canonical STAC filename (YYYYMMDD[_TILE].tif)."""
    date_str = normalize_date(acquisition_date)
    tile_part = ""
    if tile:
        tile_part = f"_{normalize_tile(tile)}"
    return f"{date_str}{tile_part}.tif"





def normalize_date(acquisition_date: DateInput) -> str:
    """Return YYYYMMDD string from supported date inputs."""
    if isinstance(acquisition_date, datetime):
        value = acquisition_date.strftime("%Y%m%d")
    elif isinstance(acquisition_date, date):
        value = acquisition_date.strftime("%Y%m%d")
    elif isinstance(acquisition_date, str):
        digits = acquisition_date.replace("-", "").replace("/", "")
        if len(digits) != 8 or not digits.isdigit():
            raise StorageError("acquisition_date must be YYYYMMDD (optionally with '-' or '/')")
        value = digits
    else:
        raise StorageError("acquisition_date must be a str, date, or datetime")

    year = int(value[0:4])
    month = int(value[4:6])
    day = int(value[6:8])
    if year < 1900 or year > 2100:
        raise StorageError("acquisition_date year must be between 1900 and 2100")
    if month < 1 or month > 12:
        raise StorageError("acquisition_date month must be between 01 and 12")
    if day < 1 or day > 31:
        raise StorageError("acquisition_date day must be between 01 and 31")
    return value





def normalize_tile(tile: str) -> str:
    """Sanitize tile identifiers while preserving delimiters."""
    formatted = tile.strip().upper()
    if not formatted:
        raise StorageError("tile cannot be an empty string")

    sanitized = formatted.replace("-", "").replace("_", "")
    if not sanitized.isalnum():
        raise StorageError("tile must be alphanumeric (hyphen/underscore allowed)")
    return formatted