pinky-core 0.1.0.dev1__py3-none-any.whl

pinky_core/fmt.py

@@ -0,0 +1,729 @@
+"""
+pinky_core.fmt
+=================
+Pure formatting utility functions.
+
+No external dependencies — importable without a Snowflake connection.
+Safe to use in SP/UDF handlers, Streamlit apps, and local scripts.
+"""
+
+from __future__ import annotations
+
+import math
+import re
+from dataclasses import dataclass
+from datetime import date, datetime
+
+# =============================================================================
+# Dates
+# =============================================================================
+
+
+def format_date(d: date | datetime | None, fmt: str = "%d/%m/%Y") -> str:
+    """Format a date as a readable string.
+
+    Args:
+        d:   Date to format. Returns "" if None.
+        fmt: strftime format string. Defaults to dd/mm/yyyy.
+
+    Returns:
+        Formatted date string, or "" if d is None.
+    """
+    if d is None:
+        return ""
+    return d.strftime(fmt)
+
+
+def format_datetime(d: datetime | None, fmt: str = "%d/%m/%Y %H:%M") -> str:
+    """Format a datetime as a readable string with time.
+
+    Args:
+        d:   Datetime to format. Returns "" if None.
+        fmt: strftime format string. Defaults to dd/mm/yyyy HH:MM.
+
+    Returns:
+        Formatted datetime string, or "" if d is None.
+    """
+    if d is None:
+        return ""
+    return d.strftime(fmt)
+
+
+def format_period(period: str) -> str:
+    """Format a period string as MM/YYYY.
+
+    Accepts:
+        - "032026" (MMYYYY) → "03/2026"
+        - "2026-03" (YYYY-MM) → "03/2026"
+
+    Args:
+        period: Period string to format.
+
+    Returns:
+        Formatted period MM/YYYY, or the original string if format is unrecognised.
+    """
+    if len(period) == 6 and period.isdigit():
+        return f"{period[:2]}/{period[2:]}"
+    if len(period) == 7 and "-" in period:
+        y, m = period.split("-")
+        return f"{m}/{y}"
+    return period
+
+
+def period_to_date(period: str) -> date:
+    """Convert a period string to a date object (first day of the month).
+
+    Accepts:
+        - "032026" (MMYYYY) → date(2026, 3, 1)
+        - "2026-03" (YYYY-MM) → date(2026, 3, 1)
+
+    Args:
+        period: Period string to convert.
+
+    Returns:
+        Date of the first day of the month.
+
+    Raises:
+        ValueError: If the format is not recognised.
+    """
+    if len(period) == 6 and period.isdigit():
+        return date(int(period[2:]), int(period[:2]), 1)
+    if len(period) == 7 and "-" in period:
+        y, m = period.split("-")
+        return date(int(y), int(m), 1)
+    raise ValueError(f"Unrecognised period format: {period!r}")
+
+
+# =============================================================================
+# Numbers
+# =============================================================================
+
+
+def format_number(num: float | int | None, num_type: str = "count") -> str:
+    """Format a number using compact notation (K, M).
+
+    Args:
+        num:      Number to format. Returns "" if None.
+        num_type: One of:
+                  - "count"           → compact integer (K, M)
+                  - "amount"          → compact amount with € suffix
+                  - "percent"         → value already in % (25.0 → "25.0 %")
+                  - "percent_decimal" → decimal value x 100 (0.25 → "25.0 %")
+
+    Returns:
+        Formatted string with appropriate suffix.
+    """
+    if num is None or (isinstance(num, float) and math.isnan(num)):
+        return ""
+    if num_type == "percent_decimal":
+        return f"{num * 100:.1f} %"
+    if num_type == "percent":
+        return f"{num:.1f} %"
+    suffix = " €" if num_type == "amount" else ""
+    sign = "-" if num < 0 else ""
+    abs_num = abs(num)
+    if abs_num >= 1_000_000:
+        val = abs_num / 1_000_000
+        return (
+            f"{sign}{val:.1f} M{suffix}" if val % 1 else f"{sign}{int(val)} M{suffix}"
+        )
+    if abs_num >= 1_000:
+        val = abs_num / 1_000
+        return (
+            f"{sign}{val:.1f} K{suffix}" if val % 1 else f"{sign}{int(val)} K{suffix}"
+        )
+    return f"{sign}{round(abs_num)}{suffix}"
+
+
+def format_duration(seconds: float | int | None) -> str:
+    """Format a duration in seconds as a human-readable string.
+
+    Examples:
+        45    → "45s"
+        125   → "2min 05s"
+        3661  → "1h 01min"
+        90000 → "1d 1h"
+
+    Args:
+        seconds: Duration in seconds. Returns "" if None.
+
+    Returns:
+        Formatted duration string.
+    """
+    if seconds is None or (isinstance(seconds, float) and math.isnan(seconds)):
+        return ""
+    s = int(abs(seconds))
+    sign = "-" if seconds < 0 else ""
+    if s < 60:
+        return f"{sign}{s}s"
+    if s < 3600:
+        return f"{sign}{s // 60}min {s % 60:02d}s"
+    if s < 86400:
+        return f"{sign}{s // 3600}h {(s % 3600) // 60:02d}min"
+    days = s // 86400
+    hours = (s % 86400) // 3600
+    return f"{sign}{days}d {hours}h"
+
+
+def format_fraction(
+    numerator: float | None,
+    denominator: float | None,
+) -> str:
+    """Format a ratio as a readable fraction with percentage.
+
+    Args:
+        numerator:   Numerator. Returns "" if None.
+        denominator: Denominator. Returns "" if None or zero.
+
+    Returns:
+        String "X / Y (Z.Z%)", or "" if inputs are invalid.
+    """
+    if (
+        numerator is None
+        or denominator is None
+        or denominator == 0
+        or (isinstance(numerator, float) and math.isnan(numerator))
+        or (isinstance(denominator, float) and math.isnan(denominator))
+    ):
+        return ""
+    pct = numerator / denominator * 100
+    return f"{round(numerator)} / {round(denominator)} ({pct:.1f}%)"
+
+
+def format_trend(current: float | None, previous: float | None) -> str:
+    """Format a trend with a directional arrow.
+
+    Examples:
+        (120, 100) → "↑ +20.0%"
+        (80, 100)  → "↓ -20.0%"
+        (100, 100) → "→ 0.0%"
+
+    Args:
+        current:  Current value. Returns "" if None.
+        previous: Previous value. Returns "" if None or zero.
+
+    Returns:
+        Trend string with arrow and percentage change.
+    """
+    if (
+        current is None
+        or previous is None
+        or previous == 0
+        or (isinstance(current, float) and math.isnan(current))
+        or (isinstance(previous, float) and math.isnan(previous))
+    ):
+        return ""
+    delta_pct = (current - previous) / abs(previous) * 100
+    if delta_pct > 0:
+        return f"↑ +{delta_pct:.1f}%"
+    if delta_pct < 0:
+        return f"↓ {delta_pct:.1f}%"
+    return "→ 0.0%"
+
+
+def format_stars(value: float | int | None, max_stars: int = 5) -> str:
+    """Format a rating as unicode stars.
+
+    Examples:
+        3.5 → "★★★☆☆"
+        5   → "★★★★★"
+
+    Args:
+        value:     Rating value. Returns "" if None.
+        max_stars: Maximum number of stars. Defaults to 5.
+
+    Returns:
+        String of filled and empty stars.
+    """
+    if value is None:
+        return ""
+    filled = min(round(value), max_stars)
+    return "★" * filled + "☆" * (max_stars - filled)
+
+
+def format_boolean(value: bool | None, style: str = "check") -> str:
+    """Format a boolean as a readable icon (tri-state: True / False / None).
+
+    Args:
+        value: Boolean value. None = indeterminate.
+        style: Rendering style, one of:
+               - "check" → ✅ / ❌ / ☑️
+               - "yesno" → Yes / No / —
+               - "onoff" → ON / OFF / —
+               - "dot"   → 🟢 / 🔴 / ⚪
+
+    Returns:
+        Formatted string for the given style.
+    """
+    styles: dict[str, tuple[str, str, str]] = {
+        "check": ("✅", "❌", "☑️"),
+        "yesno": ("Yes", "No", "—"),
+        "onoff": ("ON", "OFF", "—"),
+        "dot": ("🟢", "🔴", "⚪"),
+    }
+    true_val, false_val, none_val = styles.get(style, styles["check"])
+    if value is None:
+        return none_val
+    return true_val if value else false_val
+
+
+# =============================================================================
+# Strings
+# =============================================================================
+
+
+def to_upper_snake_case(name: str) -> str:
+    """Convert a string to UPPER_SNAKE_CASE for Snowflake identifiers.
+
+    Uses ``unidecode`` to transliterate accented and non-ASCII characters,
+    then collapses any run of non-alphanumeric characters to a single ``_``.
+
+    Examples:
+        "NAF 2025\\nsous-classes" → "NAF_2025_SOUS_CLASSES"
+        "Intitulés"               → "INTITULES"
+        "first name"              → "FIRST_NAME"
+        "Ñoño"                    → "NONO"
+
+    Args:
+        name: String to convert.
+
+    Returns:
+        UPPER_SNAKE_CASE string safe for use as a Snowflake identifier.
+    """
+    from unidecode import unidecode
+
+    name = unidecode(name)
+    name = re.sub(r"[^a-zA-Z0-9]+", "_", name)
+    return name.strip("_").upper()
+
+
+def to_camel_case(name: str) -> str:
+    """Convert UPPER_SNAKE_CASE or snake_case to camelCase.
+
+    Useful for building Snowflake OBJECT keys that follow JSON/camelCase
+    conventions (e.g. UDF return dicts consumed by downstream SQL).
+
+    Examples:
+        "is_valid_email" → "isValidEmail"
+        "COUNTRY_CODE"   → "countryCode"
+        "phone"          → "phone"
+
+    Args:
+        name: Snake-case or upper-snake-case string to convert.
+
+    Returns:
+        camelCase string.
+    """
+    parts = name.lower().split("_")
+    return parts[0] + "".join(p.capitalize() for p in parts[1:])
+
+
+def normalize_text(text: str | None) -> str | None:
+    """Normalize a string for postal/administrative use.
+
+    Applies unidecode transliteration, uppercases, then replaces any run of
+    non-alphanumeric characters with a single space.  Returns ``None`` for
+    blank input.
+
+    Equivalent to the ``udf_standardize`` pattern used in ADP/Workday flows.
+
+    Examples:
+        "Résidence de l'Étoile" → "RESIDENCE DE L ETOILE"
+        "Saint-Étienne"          → "SAINT ETIENNE"
+
+    Args:
+        text: Raw string to normalize.
+
+    Returns:
+        Normalized string, or ``None`` if input is ``None`` or blank.
+    """
+    from unidecode import unidecode
+
+    if not text or not text.strip():
+        return None
+    normalized = re.sub(r"[^A-Z0-9 ]+", " ", unidecode(text).upper())
+    return re.sub(r" +", " ", normalized).strip() or None
+
+
+def normalize_city_fr(city: str | None) -> str | None:
+    """Normalize a French city name to its ADP/AFNOR abbreviated form.
+
+    Applies :func:`normalize_text` then substitutes ``SAINT`` → ``ST`` and
+    ``SAINTE`` → ``STE`` (whole words only, not inside longer words).
+
+    Examples:
+        "Saint-Étienne"   → "ST ETIENNE"
+        "Sainte-Marie"    → "STE MARIE"
+        "Villesaint"      → "VILLESAINT"  (not a whole word, unchanged)
+
+    Args:
+        city: Raw city name.
+
+    Returns:
+        Normalized city string, or ``None`` if input is ``None`` or blank.
+    """
+    normalized = normalize_text(city)
+    if not normalized:
+        return None
+    normalized = re.sub(r"\bSAINTE\b", "STE", normalized)
+    normalized = re.sub(r"\bSAINT\b", "ST", normalized)
+    return normalized
+
+
+def iso3_to_iso2(code: str) -> str:
+    """Convert an ISO 3166-1 alpha-3 country code to alpha-2.
+
+    Returns the input unchanged if it is already alpha-2 or unknown.
+
+    Examples:
+        "FRA" → "FR"
+        "USA" → "US"
+        "FR"  → "FR"
+
+    Args:
+        code: ISO 3166-1 alpha-2 or alpha-3 country code (case-insensitive).
+
+    Returns:
+        ISO 3166-1 alpha-2 country code.
+    """
+    upper = code.strip().upper()
+    return _ISO3_TO_ISO2.get(upper, upper)
+
+
+def deduplicate_headers(headers: list[str]) -> list[str]:
+    """Deduplicate a list of column headers by appending a counter suffix.
+
+    Example:
+        ["A", "B", "A", "A"] → ["A", "B", "A_1", "A_2"]
+
+    Args:
+        headers: List of header strings (already normalised).
+
+    Returns:
+        List with duplicates resolved by appending _1, _2, etc.
+    """
+    seen: dict[str, int] = {}
+    result: list[str] = []
+    for h in headers:
+        if h in seen:
+            seen[h] += 1
+            result.append(f"{h}_{seen[h]}")
+        else:
+            seen[h] = 0
+            result.append(h)
+    return result
+
+
+# =============================================================================
+# Address parsing
+# =============================================================================
+
+# ISO 3166-1 alpha-3 → alpha-2 for common countries
+_ISO3_TO_ISO2: dict[str, str] = {
+    "FRA": "FR",
+    "USA": "US",
+    "DEU": "DE",
+    "BEL": "BE",
+    "CHE": "CH",
+    "GBR": "GB",
+    "ITA": "IT",
+    "ESP": "ES",
+    "NLD": "NL",
+    "LUX": "LU",
+    "PRT": "PT",
+    "AUT": "AT",
+    "POL": "PL",
+    "SWE": "SE",
+    "DNK": "DK",
+    "NOR": "NO",
+    "FIN": "FI",
+    "CAN": "CA",
+    "AUS": "AU",
+    "NZL": "NZ",
+    "JPN": "JP",
+    "CHN": "CN",
+    "IND": "IN",
+    "BRA": "BR",
+    "MEX": "MX",
+    "MAR": "MA",
+    "DZA": "DZ",
+    "TUN": "TN",
+    "SEN": "SN",
+    "ZAF": "ZA",
+}
+
+
+@dataclass
+class AfnorAddress:
+    """AFNOR NF Z10-011 normalised address components (FR only).
+
+    All string fields are unidecode + uppercase.  Analogous to ``e164_format``
+    on phone numbers — use these fields when the target system (ADP, La Poste…)
+    requires the normalised form.
+
+    Attributes:
+        number:           Street number (``"12"``).
+        repetition_index: Abbreviated suffix — ``"B"`` (BIS), ``"T"`` (TER),
+                          ``"Q"`` (QUATER).
+        street_type:      Uppercase street type — ``"RUE"``, ``"AVENUE"``…
+        street_name:      Uppercase street name — ``"DES LILAS"``.
+        zip_code:         Postal code (unchanged).
+        city:             Uppercase city — ``"PARIS"``.
+    """
+
+    number: str | None = None
+    repetition_index: str | None = None
+    street_type: str | None = None
+    street_name: str | None = None
+    zip_code: str | None = None
+    city: str | None = None
+
+
+@dataclass
+class AddressComponents:
+    """Parsed components of a postal address.
+
+    Raw fields preserve the original casing of the input.
+    ``afnor`` contains the same fields normalised per NF Z10-011 (FR only).
+
+    Attributes:
+        number:           Street number (``"12"``).
+        repetition_index: Repetition suffix, normalised — ``"BIS"``, ``"TER"``,
+                          ``"QUATER"`` (FR) or occupancy identifier (US).
+        street_type:      Street type in original casing (``"Rue"``, ``"avenue"``…).
+        street_name:      Street name in original casing (``"des Lilas"``).
+        zip_code:         Postal code — provided or extracted from the address string.
+        city:             City name in original casing.
+        afnor:            AFNOR-normalised fields (FR only) — see ``AfnorAddress``.
+        raw:              Original input; always set.
+    """
+
+    number: str | None = None
+    repetition_index: str | None = None
+    street_type: str | None = None
+    street_name: str | None = None
+    zip_code: str | None = None
+    city: str | None = None
+    afnor: AfnorAddress | None = None
+    raw: str | None = None
+
+
+# ── FR ────────────────────────────────────────────────────────────────────────
+
+_FR_SOURCE_INDICE = ["B", "BI", "BIS", "T", "TE", "TER", "C", "Q", "QUATER", "D"]
+_FR_CIBLE_INDICE = [
+    "BIS",
+    "BIS",
+    "BIS",
+    "TER",
+    "TER",
+    "TER",
+    "TER",
+    "QUATER",
+    "QUATER",
+    "QUATER",
+]
+_FR_AFNOR_INDICE = {"BIS": "B", "TER": "T", "QUATER": "Q"}
+_FR_RE_NUMBER = re.compile(
+    r"^((\d+)( ?(B|b|bis|BIS|t|T|ter|TER|quater|QUATER|C|D|E|c|d|e|f|F) )?) ?(.+)?"
+)
+_FR_RE_ZIP_CITY = re.compile(r"^(.*?)\s+(\d{5})\s+(.+)$")
+_FR_STREET_TYPES = [
+    "avenue",
+    "boulevard",
+    "chemin",
+    "cité",
+    "cite",
+    "impasse",
+    "lieu-dit",
+    "lieu dit",
+    "passage",
+    "place",
+    "promenade",
+    "quai",
+    "résidence",
+    "residence",
+    "rond-point",
+    "rond point",
+    "route",
+    "ruelle",
+    "rue",
+    "traverse",
+    "voie",
+    "allée",
+    "allee",
+    "cour",
+    "gr",
+    "hameau",
+]
+
+
+def _afnor_norm(s: str | None) -> str | None:
+    """Unidecode + uppercase + collapse non-alphanumeric to spaces."""
+    from unidecode import unidecode
+
+    if not s:
+        return None
+    return (
+        re.sub(r" +", " ", re.sub(r"[^A-Z0-9 ]", " ", unidecode(s).upper())).strip()
+        or None
+    )
+
+
+def _parse_fr(
+    address: str,
+    zip_code: str | None = None,
+    city: str | None = None,
+) -> AddressComponents:
+    bloc = address.strip()
+    street_line = bloc
+
+    # Extract zip_code / city from full address when not supplied
+    if not zip_code and not city:
+        m_full = _FR_RE_ZIP_CITY.match(bloc)
+        if m_full:
+            street_line = m_full.group(1).strip()
+            zip_code = m_full.group(2)
+            city = m_full.group(3).strip()
+
+    # Number + repetition index (normalised to BIS/TER/QUATER, not abbreviated yet)
+    number: str | None = None
+    repetition_index: str | None = None
+    m = _FR_RE_NUMBER.match(street_line)
+    if m:
+        tmp = str(m.group(1)).replace(" ", "").lower()
+        num_str = re.sub(r"[^0-9\-]", "", tmp)
+        number = num_str or None
+        raw_indice = re.sub(r"[0-9\-]", "", tmp).upper()
+        if raw_indice:
+            try:
+                repetition_index = _FR_CIBLE_INDICE[_FR_SOURCE_INDICE.index(raw_indice)]
+            except ValueError:
+                repetition_index = raw_indice
+
+    # Street type — original casing, earliest position
+    street_type: str | None = None
+    lower = street_line.lower()
+    earliest = len(lower)
+    type_end = 0
+    for t in _FR_STREET_TYPES:
+        pos = lower.find(t + " ")
+        if pos != -1 and pos < earliest:
+            earliest = pos
+            type_end = pos + len(t)
+            street_type = street_line[pos:type_end]  # original casing
+
+    # Street name — everything after the type in original casing
+    street_name: str | None = (
+        street_line[type_end:].strip() or None if street_type else None
+    )
+
+    # AfnorAddress — normalised per NF Z10-011
+    afnor = AfnorAddress(
+        number=number,
+        repetition_index=_FR_AFNOR_INDICE.get(repetition_index, repetition_index)
+        if repetition_index
+        else None,
+        street_type=_afnor_norm(street_type),
+        street_name=_afnor_norm(street_name),
+        zip_code=zip_code,
+        city=_afnor_norm(city),
+    )
+
+    return AddressComponents(
+        number=number,
+        repetition_index=repetition_index,
+        street_type=street_type,
+        street_name=street_name,
+        zip_code=zip_code,
+        city=city,
+        afnor=afnor,
+        raw=address,
+    )
+
+
+# ── US ────────────────────────────────────────────────────────────────────────
+
+
+def _parse_us(
+    address: str,
+    zip_code: str | None = None,
+    city: str | None = None,
+) -> AddressComponents:
+    try:
+        import usaddress
+
+        tagged, _ = usaddress.tag(address)
+        post_type = (tagged.get("StreetNamePostType") or "").upper() or None
+        pre_type = (tagged.get("StreetNamePreType") or "").upper() or None
+        return AddressComponents(
+            number=tagged.get("AddressNumber"),
+            repetition_index=tagged.get("OccupancyIdentifier"),
+            street_type=post_type or pre_type,
+            street_name=tagged.get("StreetName"),
+            zip_code=zip_code or tagged.get("ZipCode"),
+            city=city or tagged.get("PlaceName"),
+            raw=address,
+        )
+    except ImportError:
+        return AddressComponents(zip_code=zip_code, city=city, raw=address)
+    except Exception:
+        return AddressComponents(zip_code=zip_code, city=city, raw=address)
+
+
+# ── Dispatch ──────────────────────────────────────────────────────────────────
+
+_COUNTRY_PARSERS = {
+    "FR": _parse_fr,
+    "US": _parse_us,
+}
+
+
+def parse_address(
+    address: str,
+    country_code: str = "FR",
+    zip_code: str | None = None,
+    city: str | None = None,
+) -> AddressComponents:
+    """Parse a postal address into structured components.
+
+    Args:
+        address:      Raw address string.  Can be the street line only
+                      (``"12 BIS RUE DES LILAS"``) or a full address including
+                      postal code and city (``"12 BIS RUE DES LILAS 75019 PARIS"``).
+                      When the full address is passed and ``zip_code`` / ``city``
+                      are omitted, they are extracted automatically (FR only).
+        country_code: ISO 3166-1 alpha-2 (``"FR"``, ``"US"``) or alpha-3
+                      (``"FRA"``, ``"USA"``). Case-insensitive.
+                      Countries without a dedicated parser return
+                      ``AddressComponents(raw=address)``.
+        zip_code:     Postal code from the source data.  Overrides extraction
+                      from ``address``.
+        city:         City name from the source data.  Overrides extraction
+                      from ``address``.
+
+    Returns:
+        ``AddressComponents`` with parsed fields.  ``raw`` is always set to
+        the original input.  ``afnor`` contains the NF Z10-011 normalised
+        street line for FR addresses.
+
+    Note:
+        US parsing requires the optional ``usaddress`` package::
+
+            pip install pinky-core[address]
+    """
+    if not address or not address.strip():
+        return AddressComponents(zip_code=zip_code, city=city, raw=address or None)
+
+    code = country_code.strip().upper()
+    if len(code) == 3:
+        code = _ISO3_TO_ISO2.get(code, code)
+
+    parser = _COUNTRY_PARSERS.get(code)
+    if parser:
+        try:
+            return parser(address, zip_code=zip_code, city=city)
+        except Exception:
+            return AddressComponents(zip_code=zip_code, city=city, raw=address)
+
+    return AddressComponents(zip_code=zip_code, city=city, raw=address)