dataface 0.1.2__py3-none-any.whl

d3_format/__init__.py

@@ -0,0 +1,14 @@
+"""d3-format — Python implementation of d3-format spec parsing and formatting.
+
+Public API:
+    format(spec_str)(value) -> str
+    format(spec_str, value) -> str
+    parse(spec_str) -> FormatSpec
+    D3FormatError
+"""
+
+from d3_format.errors import D3FormatError
+from d3_format.format import format
+from d3_format.spec import FormatSpec, parse
+
+__all__ = ["D3FormatError", "FormatSpec", "format", "parse"]

d3_format/errors.py

@@ -0,0 +1,19 @@
+"""D3FormatError — raised for unsupported or invalid format specs."""
+
+
+class D3FormatError(ValueError):
+    """Raised when a format spec is invalid or uses an unsupported feature.
+
+    Attributes:
+        spec: The full format spec string that failed.
+        position: 0-based position in spec where the problem was detected.
+        reason: Human-readable explanation of the problem.
+    """
+
+    def __init__(self, spec: str, position: int, reason: str) -> None:
+        self.spec = spec
+        self.position = position
+        self.reason = reason
+        super().__init__(
+            f"d3-format parse error at position {position} in {spec!r}: {reason}"
+        )

d3_format/format.py

@@ -0,0 +1,551 @@
+"""d3-format Python implementation.
+
+Implements the d3-format spec with byte-for-byte parity to d3.js.
+Key deviations from Python's standard number formatting:
+- Negative sign is U+2212 MINUS SIGN, not U+002D HYPHEN-MINUS.
+- Rounding uses round-half-up (JavaScript Math.round), not banker's rounding.
+- SI type uses significant-digit precision (not decimal-place precision).
+- `d` type rounds to nearest integer using round-half-up.
+- `n` type is locale-aware `g` with grouping.
+"""
+
+from __future__ import annotations
+
+import math
+from collections.abc import Callable
+from decimal import ROUND_HALF_UP, Decimal
+
+from d3_format.spec import FormatSpec, parse
+
+# U+2212 MINUS SIGN — d3 uses this, not hyphen-minus.
+_MINUS = "−"
+# U+221E INFINITY SYMBOL — d3's d/,d use this for infinite values.
+_INF_SYMBOL = "∞"
+
+# SI prefixes: index 8 = '' (10^0), 9 = 'k' (10^3), etc.
+_SI_PREFIXES = [
+    "y",
+    "z",
+    "a",
+    "f",
+    "p",
+    "n",
+    "µ",
+    "m",
+    "",
+    "k",
+    "M",
+    "G",
+    "T",
+    "P",
+    "E",
+    "Z",
+    "Y",
+]
+_SI_PREFIX_OFFSET = 8  # index of the '' (10^0) entry
+
+
+def _round_half_up(x: float, decimals: int) -> float:
+    """Round x to `decimals` decimal places using round-half-up (like JS Math.round).
+
+    Python's built-in round() uses banker's rounding; d3/JS always rounds 0.5 up.
+    We use Decimal for exact midpoint detection.
+    """
+    if not math.isfinite(x) or math.isnan(x):
+        return x
+    quant = Decimal(
+        "1e-" + str(decimals)
+    )  # works for any int, including 0 and negative
+    # Use Decimal(x) — the exact IEEE-754 binary value — so rounding matches d3/JS.
+    # Decimal(repr(x)) would round "2.55" up to "2.6", but d3 rounds it down to "2.5"
+    # because the binary value is 2.5499..., not 2.55.
+    return float(Decimal(x).quantize(quant, rounding=ROUND_HALF_UP))
+
+
+def _fmt_fixed(abs_val: float, decimals: int) -> str:
+    """Format abs_val to `decimals` decimal places with round-half-up."""
+    rounded = _round_half_up(abs_val, decimals)
+    return f"{rounded:.{decimals}f}"
+
+
+def _format_group(digits: str, separator: str) -> str:
+    """Apply thousands grouping (groups of 3) to a digit string."""
+    n = len(digits)
+    first = n % 3 or 3
+    parts = [digits[:first]]
+    i = first
+    while i < n:
+        parts.append(digits[i : i + 3])
+        i += 3
+    return separator.join(parts)
+
+
+def _apply_grouping(body: str, separator: str, decimal_pt: str) -> str:
+    """Apply thousands grouping to the integer part of a formatted number.
+
+    Handles plain integers, decimals, and exponential notation.
+    """
+    if "e" in body:
+        mantissa, exp_part = body.split("e", 1)
+        if decimal_pt in mantissa:
+            int_part, frac = mantissa.split(decimal_pt, 1)
+            return (
+                _format_group(int_part, separator) + decimal_pt + frac + "e" + exp_part
+            )
+        return _format_group(mantissa, separator) + "e" + exp_part
+    if decimal_pt in body:
+        int_part, frac = body.split(decimal_pt, 1)
+        return _format_group(int_part, separator) + decimal_pt + frac
+    return _format_group(body, separator)
+
+
+def _apply_trim(body: str) -> str:
+    """Remove trailing zeros (and trailing decimal point) from a formatted number."""
+    if "e" in body:
+        mantissa, exp_part = body.split("e", 1)
+        if "." in mantissa:
+            mantissa = mantissa.rstrip("0").rstrip(".")
+        return mantissa + "e" + exp_part
+    if "." in body:
+        return body.rstrip("0").rstrip(".")
+    return body
+
+
+def _format_decimal_parts(x: float, precision: int) -> tuple[str, int] | None:
+    """Replicate d3's formatDecimalParts(x, p).
+
+    x must be positive and finite (non-zero).
+    Returns (coefficient_digits, exponent) where:
+    - coefficient_digits: the p significant-figure string (may be longer if carry)
+    - exponent: position of the leading digit (i.e. value ≈ 0.coefficient × 10^(exp+1))
+
+    e.g. formatDecimalParts(1.23, 3) → ("123", 0)
+         formatDecimalParts(1234.5, 3) → ("123", 3) (rounded to 3 sig figs)
+
+    Uses Decimal(x) — the exact IEEE-754 binary value — with ROUND_HALF_UP so that
+    rounding matches JavaScript's toExponential (d3 rounds the binary, not repr).
+    """
+    if not math.isfinite(x) or x == 0:
+        return None
+    p = max(1, precision)
+    d = Decimal(x)  # exact binary value — matches JS's toExponential rounding
+    adj = d.adjusted()  # exponent of leading digit = floor(log10(|d|))
+    # Scale so rounding to nearest integer gives p significant figures.
+    scale_exp = p - 1 - adj
+    scaled = d * (Decimal(10) ** scale_exp)
+    rounded_int = scaled.quantize(Decimal("1"), rounding=ROUND_HALF_UP)
+    coefficient = str(abs(int(rounded_int)))
+    # If rounding caused a carry (e.g. 9.5 → 10 at p=1), exp_out increases.
+    exp_out = adj + (len(coefficient) - p)
+    # d3's toExponential(p-1) always returns exactly p significant-digit chars.
+    # When a carry adds a digit (e.g. '100' from p=2), truncate to match d3's shape.
+    if len(coefficient) > p:
+        coefficient = coefficient[:p]
+    return coefficient, exp_out
+
+
+def _format_si(abs_val: float, precision: int) -> tuple[str, str]:
+    """Format abs_val with SI prefix to `precision` significant digits.
+
+    Replicates d3's formatPrefixAuto(x, p) algorithm exactly:
+    1. Round to p significant digits using exponential notation.
+    2. Determine SI prefix exponent from the rounded exponent.
+    3. Build body string from coefficient positioned relative to prefix.
+
+    Returns (number_body, prefix_char).
+    """
+    if abs_val == 0.0:
+        # d3 calls x.toPrecision(p) for zero (formatDecimalParts returns null).
+        # JS toPrecision(p) on 0 = "0." + "0"*(p-1) for p>=2, "0" for p<=1.
+        body = ("0." + "0" * (precision - 1)) if precision > 1 else "0"
+        return body, ""
+
+    coefficient, exponent = _format_decimal_parts(abs_val, precision)  # type: ignore[misc]
+
+    # Clamp the level (not the product) to [-8, 8] matching d3-format formatPrefixAuto.js.
+    # Clamping the product (-24..24) instead of the level (-8..8) would allow exponents
+    # beyond ±24 that exceed the _SI_PREFIXES array bounds → IndexError.
+    prefix_exp = max(-8, min(8, math.floor(exponent / 3))) * 3
+    prefix = _SI_PREFIXES[prefix_exp // 3 + _SI_PREFIX_OFFSET]
+
+    # Position the decimal point in coefficient.
+    # i = exponent - prefix_exp + 1 = number of digits before the decimal point.
+    i = exponent - prefix_exp + 1
+    n = len(coefficient)
+
+    if i == n:
+        body = coefficient
+    elif i > n:
+        body = coefficient + "0" * (i - n)
+    elif i > 0:
+        body = coefficient[:i] + "." + coefficient[i:]
+    else:
+        # i <= 0: value is smaller than 1 in the chosen prefix unit.
+        # d3: "0." + new Array(1-i).join("0") + formatDecimalParts(x, max(0,p+i-1))[0]
+        # new Array(k).join("0") produces k-1 zeros, so (1-i)-1 = -i zeros.
+        new_prec = max(1, precision + i - 1)
+        d2 = _format_decimal_parts(abs_val, new_prec)
+        coeff2 = d2[0] if d2 else "0"
+        body = "0." + "0" * (-i) + coeff2
+
+    return body, prefix
+
+
+def _js_to_precision(abs_val: float, precision: int) -> str:
+    """Replicate JavaScript's Number.prototype.toPrecision(p).
+
+    Uses exponential notation when exponent >= precision or exponent < -6.
+    Otherwise uses fixed notation. Rounds using round-half-up.
+
+    This is the core of d3's 'g' and 'n' type formatting.
+    """
+    # d3 treats toPrecision(0) as toPrecision(1) — g/n types use max(1, p).
+    p = max(1, precision)
+    if abs_val == 0.0:
+        # JS: (0).toPrecision(p) = "0." + "0"*(p-1) for p>=2, "0" for p=1
+        return ("0." + "0" * (p - 1)) if p > 1 else "0"
+
+    coefficient, exponent = _format_decimal_parts(abs_val, p)  # type: ignore[misc]
+
+    # JS uses e notation if exponent >= p or exponent < -6.
+    if exponent >= p or exponent < -6:
+        # Exponential form: coefficient[0].coefficient[1:]e+exponent
+        if len(coefficient) > 1:
+            mantissa = coefficient[0] + "." + coefficient[1:]
+        else:
+            mantissa = coefficient[0]
+        exp_sign = "+" if exponent >= 0 else "-"
+        exp_str = str(abs(exponent))
+        return f"{mantissa}e{exp_sign}{exp_str}"
+    else:
+        # Fixed form: position decimal based on exponent.
+        i = exponent + 1  # digits before decimal point
+        n = len(coefficient)
+        if i >= n:
+            # All digits before decimal, may need trailing zeros.
+            return coefficient + "0" * (i - n)
+        elif i > 0:
+            return coefficient[:i] + "." + coefficient[i:]
+        else:
+            # 0 < abs_val < 1: prepend "0." and leading zeros.
+            return "0." + "0" * (-i) + coefficient
+
+
+def _format_rounded(abs_val: float, precision: int) -> str:
+    """Replicate d3's formatRounded(x, p) for 'r' type.
+
+    Always uses fixed notation (no e), rounds to p significant digits.
+    """
+    if abs_val == 0.0:
+        return "0"
+
+    coefficient, exponent = _format_decimal_parts(abs_val, precision)  # type: ignore[misc]
+
+    i = exponent + 1  # digits before decimal
+    n = len(coefficient)
+    if i <= 0:
+        return "0." + "0" * (-i) + coefficient
+    elif n > i:
+        return coefficient[:i] + "." + coefficient[i:]
+    else:
+        return coefficient + "0" * (i - n)
+
+
+def _format_general(abs_val: float, precision: int) -> str:
+    """Format abs_val using d3's 'g' rule (x.toPrecision(p))."""
+    return _js_to_precision(abs_val, precision)
+
+
+def _body_is_zero(body: str) -> bool:
+    """True if `body` contains no nonzero digit (e.g. '0', '0.0', '0.00e+0')."""
+    return not any(c.isdigit() and c != "0" for c in body)
+
+
+def _format_number(spec: FormatSpec, v: float) -> tuple[str, str, str]:
+    """Format a finite, non-NaN float (v may be negative).
+
+    Returns (sign_char, body, suffix) where:
+    - sign_char: "−" | "+" | " " | ""
+    - body: formatted digit string
+    - suffix: SI prefix char, "%" or ""
+    """
+    is_neg = math.copysign(1.0, v) < 0
+    abs_val = abs(v)
+
+    # d3: negative values get minus; but -0 loses its minus unless sign is "+".
+    # (equivalent to d3's "if valueNegative && +formattedValue === 0 && sign !== '+'" logic)
+    # We handle this after formatting for non-zero; for zero it's always suppressed unless sign="+".
+    is_neg_zero = is_neg and abs_val == 0.0
+    if is_neg_zero and spec.sign != "+":
+        is_neg = False
+
+    if is_neg:
+        sign_char = _MINUS
+    elif spec.sign == "+":
+        sign_char = "+"
+    elif spec.sign == " ":
+        sign_char = " "
+    else:
+        sign_char = ""
+
+    t = spec.type
+    precision = spec.precision
+
+    if t == "f":
+        prec = precision if precision is not None else 6
+        # JS Number.prototype.toFixed() falls back to toString() for |x| >= 10^21.
+        body = str(abs_val) if abs_val >= 1e21 else _fmt_fixed(abs_val, prec)
+        suffix = ""
+
+    elif t == "%":
+        prec = precision if precision is not None else 6
+        scaled = abs_val * 100.0
+        # toFixed fallback: |x * 100| >= 10^21 → toString(x * 100)
+        body = str(scaled) if scaled >= 1e21 else _fmt_fixed(scaled, prec)
+        suffix = "%"
+
+    elif t == "e":
+        prec = precision if precision is not None else 6
+        if abs_val == 0.0:
+            body = ("0." + "0" * prec if prec > 0 else "0") + "e+0"
+        else:
+            d = _format_decimal_parts(abs_val, prec + 1)
+            coefficient, exponent = d  # type: ignore[misc]
+            # Pad to prec+1 digits in case trailing zeros were stripped
+            coefficient = coefficient.ljust(prec + 1, "0")
+            if prec > 0:
+                mantissa = coefficient[0] + "." + coefficient[1 : prec + 1]
+            else:
+                mantissa = coefficient[0]
+            exp_sign = "+" if exponent >= 0 else "-"
+            body = f"{mantissa}e{exp_sign}{abs(exponent)}"
+        suffix = ""
+
+    elif t in ("g", ""):
+        # d3's formatDefault (empty type) uses toPrecision(12) as the default precision.
+        # 'g' type uses the spec precision (default 6).
+        prec = precision if precision is not None else (12 if t == "" else 6)
+        body = _format_general(abs_val, prec)
+        suffix = ""
+
+    elif t == "r":
+        prec = precision if precision is not None else 6
+        body = _format_rounded(abs_val, prec)
+        suffix = ""
+
+    elif t == "s":
+        prec = precision if precision is not None else 6
+        body, si_suffix = _format_si(abs_val, prec)
+        suffix = si_suffix
+
+    elif t == "d":
+        if abs_val >= 1e21:
+            # JS formatDecimal uses x.toLocaleString("en") for |x| >= 1e21.
+            # str(x) gives the shortest round-trip repr; Decimal(str()) expands
+            # exponential form to the "clean" integer string matching JS.
+            s = str(abs_val)
+            body = str(int(Decimal(s))) if ("e" in s or "E" in s) else str(int(abs_val))
+        else:
+            body = str(int(_round_half_up(abs_val, 0)))
+        suffix = ""
+
+    else:  # t == "n"
+        # n type: alias for ",g" — locale-aware g (grouping handled later).
+        prec = precision if precision is not None else 6
+        body = _js_to_precision(abs_val, prec)
+        suffix = ""
+
+    # d3: "if (valueNegative && +formattedValue === 0 && sign !== '+') valueNegative = false"
+    # Drop the minus sign when the formatted body rounds to zero.
+    if is_neg and spec.sign != "+" and _body_is_zero(body):
+        is_neg = False
+        sign_char = " " if spec.sign == " " else ""
+
+    return sign_char, body, suffix
+
+
+def _assemble(
+    spec: FormatSpec,
+    sign_char: str,
+    body: str,
+    suffix: str,
+) -> str:
+    """Assemble sign + symbol + body + suffix, apply width/fill/align."""
+    currency = "$" if spec.symbol == "$" else ""
+
+    # Parens sign mode.
+    if spec.sign == "(" and sign_char == _MINUS:
+        paren_open = "("
+        paren_close = ")"
+        sign_char = ""
+    else:
+        paren_open = ""
+        paren_close = ""
+
+    # Assemble the non-padded string.
+    if paren_open:
+        full = paren_open + currency + body + suffix + paren_close
+    else:
+        full = sign_char + currency + body + suffix
+
+    if spec.width is None:
+        return full
+
+    w = spec.width
+    current = len(full)
+    if current >= w:
+        return full
+    needed = w - current
+
+    if spec.zero:
+        # Zero-pad: sign+currency, then zeros, then body+suffix.
+        # parens+zero is rejected at parse time, so paren_open is never set here.
+        prefix = sign_char + currency
+        rest = body + suffix
+        return prefix + "0" * needed + rest
+
+    if spec.align == "=":
+        prefix_str = (paren_open + currency) if paren_open else (sign_char + currency)
+        rest = body + suffix + paren_close
+        return prefix_str + spec.fill * needed + rest
+
+    if spec.align == "<":
+        return full + spec.fill * needed
+    elif spec.align == ">":
+        return spec.fill * needed + full
+    else:  # "^"
+        left = needed // 2
+        right = needed - left
+        return spec.fill * left + full + spec.fill * right
+
+
+def _assemble_special(
+    spec: FormatSpec,
+    text: str,
+    is_neg: bool,
+) -> str:
+    """Assemble NaN or Infinity string with sign/currency/width.
+
+    NaN: sign chars from spec apply (+ shows +, space shows space).
+    Infinity: actual sign from is_neg.
+    """
+    if is_neg:
+        sign_char = _MINUS
+    elif spec.sign == "+":
+        sign_char = "+"
+    elif spec.sign == " ":
+        sign_char = " "
+    else:
+        sign_char = ""
+
+    currency = "$" if spec.symbol == "$" else ""
+
+    # Parens mode for negative infinity.
+    if spec.sign == "(" and is_neg:
+        full = "(" + currency + text + ")"
+        sign_char = ""
+    else:
+        full = sign_char + currency + text
+
+    if spec.width is None:
+        return full
+
+    w = spec.width
+    current = len(full)
+    if current >= w:
+        return full
+    needed = w - current
+
+    # For special values, zero-pad uses "0" as fill char.
+    if spec.zero:
+        prefix = sign_char + currency
+        return prefix + "0" * needed + text
+
+    if spec.align == "<":
+        return full + spec.fill * needed
+    elif spec.align in (">", "="):
+        return spec.fill * needed + full
+    else:  # "^"
+        left = needed // 2
+        right = needed - left
+        return spec.fill * left + full + spec.fill * right
+
+
+def _apply_spec(spec: FormatSpec, v: float | int | Decimal) -> str:
+    """Apply a parsed FormatSpec to a numeric value."""
+    v = float(v)  # coerce int, Decimal, etc.; preserves -0 sign via IEEE 754
+
+    # d and ,d type: use ∞ symbol for infinite values.
+    use_inf_symbol = spec.type in ("d",)
+
+    # The % type appends "%" even to NaN/Infinity.
+    type_suffix = "%" if spec.type == "%" else ""
+
+    # NaN.
+    if math.isnan(v):
+        return _assemble_special(spec, "NaN" + type_suffix, is_neg=False)
+
+    # Infinity.
+    if math.isinf(v):
+        is_neg = v < 0
+        text = (_INF_SYMBOL if use_inf_symbol else "Infinity") + type_suffix
+        return _assemble_special(spec, text, is_neg=is_neg)
+
+    # Normal number.
+    sign_char, body, suffix = _format_number(spec, v)
+
+    # Trim trailing zeros: explicit ~ flag, or unconditionally for empty type.
+    # d3's formatDefault (empty type) always strips trailing zeros regardless of ~.
+    if spec.trim or spec.type == "":
+        body = _apply_trim(body)
+
+    # Comma grouping: for 'n' type always group; for all others respect spec.comma.
+    # For 's' type, comma is applied to the mantissa (matters for very large SI bodies).
+    use_comma = spec.comma or spec.type == "n"
+    if use_comma:
+        if spec.zero and spec.width is not None:
+            # d3 applies comma grouping to the zero-padded digits.
+            # Pre-pad body to the largest digit count that fits the target width.
+            sign_len = len(sign_char) + (1 if spec.symbol == "$" else 0)
+            available = spec.width - sign_len - len(suffix)
+            d = len(body)
+            while True:
+                nd = d + 1
+                if nd + (nd - 1) // 3 > available:
+                    break
+                d = nd
+            body = body.zfill(d)
+        body = _apply_grouping(body, ",", ".")
+
+    return _assemble(spec, sign_char, body, suffix)
+
+
+def format(  # noqa: A001
+    spec_str: str,
+    value: float | int | Decimal | None = None,
+) -> Callable[[float | int | Decimal], str] | str:
+    """Parse spec and return a formatter, or apply immediately.
+
+    Two calling conventions::
+
+        d3_format(",.2f")(1234.56)   →  "1,234.56"
+        d3_format(",.2f", 1234.56)   →  "1,234.56"
+
+    Args:
+        spec_str: d3-format spec string.
+        value: Optional value to format immediately.
+
+    Returns:
+        A ``Callable[[float], str]`` if value is None, else the formatted string.
+
+    Raises:
+        D3FormatError: If spec_str is invalid or uses unsupported features.
+    """
+    spec = parse(spec_str)
+
+    def _fmt(v: float | int | Decimal) -> str:
+        return _apply_spec(spec, v)
+
+    if value is None:
+        return _fmt
+    return _fmt(value)