A kind of initial commit

app/utils/text.py

@@ -0,0 +1,14 @@
+from __future__ import annotations
+
+import re
+
+
+_WS_RE = re.compile(r"\s+")
+_FEAT_RE = re.compile(r"\s*[\(\[\-–—]\s*(feat|ft)\.?.*$", re.IGNORECASE)
+
+
+def normalize_track_signature(name: str, artists: list[str]) -> str:
+    clean_name = _FEAT_RE.sub("", name).strip().lower()
+    clean_name = _WS_RE.sub(" ", clean_name)
+    clean_artists = ",".join(sorted(a.strip().lower() for a in artists if a.strip()))
+    return f"{clean_name}::{clean_artists}"

app/utils/time.py

@@ -0,0 +1,25 @@
+from __future__ import annotations
+
+from datetime import datetime, timezone
+
+
+def utcnow() -> datetime:
+    return datetime.now(timezone.utc)
+
+
+def ensure_utc(dt: datetime) -> datetime:
+    if dt.tzinfo is None or dt.tzinfo.utcoffset(dt) is None:
+        return dt.replace(tzinfo=timezone.utc)
+    return dt.astimezone(timezone.utc)
+
+
+def parse_spotify_datetime(value: str | None) -> datetime | None:
+    if not value:
+        return None
+    if value.endswith("Z"):
+        value = value.replace("Z", "+00:00")
+    return datetime.fromisoformat(value)
+
+
+def to_unix_ms(dt: datetime) -> int:
+    return int(dt.timestamp() * 1000)