"""
GLAMWalk -- Volume 3: Data at Scale
03_join_key_iiif_uuid.py

Extracting a stable IIIF UUID embedded in an image URL, for use as a reliable join key when reconciling new data against existing rows.

Source: Volume Three, Section 1.3 -- The Join-Key Problem
Targets Python 3.11.4 -- see Volume One, Chapter 1.5/1.6.
"""

import re

def extract_iiif_uuid(image_url):
    """
    Several museums' image URLs embed a stable UUID as part of an
    IIIF-compliant image path. Extracting it gives a reliable join
    key even when no other field lines up between two datasets.
    Example shape: https://.../iiif/2/a1b2c3d4-.../full/full/0/default.jpg
    """
    match = re.search(
        r'/([0-9a-f]{8}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{12})/',
        image_url,
    )
    return match.group(1) if match else None