Document WCX processing scripts

scripts/parse_ocr.py

@@ -0,0 +1,109 @@
+#!/usr/bin/env python3
+
+"""
+Parse raw OCR text extracted from a WCX thumbnail.
+
+The script reads OCR text from standard input and expects four non-empty lines:
+
+    1. Performer name
+    2. Nationality
+    3. WCX branding text, ignored by the parser
+    4. Shoot location and date
+
+The final line is expected to use the following format:
+
+    Budapest (Hungary), March 9, 2014
+
+It is split on the first comma so that the comma inside the date is preserved.
+The date is normalized to ISO format, for example 2014-03-09.
+
+On success, the script writes key/value pairs to standard output:
+
+    ocr_name=...
+    nationality=...
+    shoot_location=...
+    shoot_date=...
+
+Invalid or unexpected OCR output is reported on standard error and causes a
+non-zero exit status.
+"""
+
+
+import sys
+from datetime import datetime
+
+
+def parse_ocr_text(raw_text: str) -> tuple[str, str, str, str]:
+    lines = [
+        line.strip()
+        for line in raw_text.splitlines()
+        if line.strip()
+    ]
+
+    if len(lines) != 4:
+        raise ValueError(
+            f"Förväntade 4 icke-tomma rader, fick {len(lines)}."
+        )
+
+    ocr_name = lines[0]
+    nationality = lines[1]
+    ignored_text = lines[2]
+    location_and_date = lines[3]
+
+    if not ocr_name:
+        raise ValueError("Namn saknas.")
+
+    if not nationality:
+        raise ValueError("Nationalitet saknas.")
+
+    if not ignored_text:
+        raise ValueError("Förväntad tredje rad saknas.")
+
+    if "," not in location_and_date:
+        raise ValueError(
+            "Sista raden saknar kommatecken mellan plats och datum."
+        )
+
+    shoot_location, date_text = location_and_date.split(",", 1)
+
+    shoot_location = shoot_location.strip()
+    date_text = date_text.strip()
+
+    if not shoot_location:
+        raise ValueError("Inspelningsplats saknas.")
+
+    try:
+        shoot_date = datetime.strptime(
+            date_text,
+            "%B %d, %Y",
+        ).date().isoformat()
+    except ValueError as error:
+        raise ValueError(
+            f"Kunde inte tolka datumet: {date_text!r}"
+        ) from error
+
+    return ocr_name, nationality, shoot_location, shoot_date
+
+
+def main() -> None:
+    raw_text = sys.stdin.read()
+
+    if not raw_text.strip():
+        raise ValueError("Ingen OCR-text mottogs på standard input.")
+
+    ocr_name, nationality, shoot_location, shoot_date = parse_ocr_text(
+        raw_text
+    )
+
+    print(f"ocr_name={ocr_name}")
+    print(f"nationality={nationality}")
+    print(f"shoot_location={shoot_location}")
+    print(f"shoot_date={shoot_date}")
+
+
+if __name__ == "__main__":
+    try:
+        main()
+    except ValueError as error:
+        print(f"Fel: {error}", file=sys.stderr)
+        sys.exit(1)