UTM Builder

from urllib.parse import urlencode, urlparse, parse_qs, urlunparse

def build_utm_url(base_url: str, source: str, medium: str, campaign: str,
                  term: str = "", content: str = "") -> str:
    """Append UTM parameters to a URL, preserving existing query params."""
    parsed = urlparse(base_url)
    existing_params = parse_qs(parsed.query, keep_blank_values=True)

    utm_params = {
        "utm_source":   source,
        "utm_medium":   medium,
        "utm_campaign": campaign,
    }
    if term:    utm_params["utm_term"]    = term
    if content: utm_params["utm_content"] = content

    # Merge (UTM params override existing ones with the same name)
    merged = {k: v[0] for k, v in existing_params.items()}
    merged.update(utm_params)

    new_query = urlencode(merged)
    return urlunparse(parsed._replace(query=new_query))

def parse_utm_url(url: str) -> dict:
    """Extract UTM parameters from a URL."""
    query = parse_qs(urlparse(url).query)
    keys = ["utm_source", "utm_medium", "utm_campaign", "utm_term", "utm_content"]
    return {k: query[k][0] for k in keys if k in query}

# Build a URL
url = build_utm_url(
    base_url  = "https://example.com/landing",
    source    = "newsletter",
    medium    = "email",
    campaign  = "spring-sale-2025",
    content   = "header-cta",
)
print("UTM URL:", url)

# Parse it back
print("Params: ", parse_utm_url(url))