charts.format

Imports name this capability’s declared dependencies, which fune builds next to it in your project; each one links to its page.

import math

from .math_round_float import round_float  ← from math.round-float ^1.0.0 · built alongside by fune
from .text_format_decimal import format_decimal  ← from text.format-decimal ^1.0.0 · built alongside by fune


def places_for(x: float) -> int:
    """The fewest decimal places (0 to 12) that write x exactly; 12 if none do."""
    a = abs(float(x))
    for d in range(12):
        if round_float(a, d) == a:
            return d
    return 12


def format_tick(value: float, step: float) -> str:
    """A tick label with as many decimal places as the step needs, comma-grouped."""
    if isinstance(step, bool) or not isinstance(step, (int, float)) or not math.isfinite(step):
        raise ValueError("step must be a finite number, received %r" % (step,))
    places = places_for(value) if step == 0 else places_for(step)
    return format_decimal(value, places, False, ",")

Imports name this capability’s declared dependencies, which fune builds next to it in your project; each one links to its page.

import math
from typing import Tuple

from .math_round_float import round_float  ← from math.round-float ^1.0.0 · built alongside by fune
from .text_format_decimal import format_decimal  ← from text.format-decimal ^1.0.0 · built alongside by fune

# yocto to yotta, as d3-format writes them (micro is U+00B5).
_PREFIXES = ["y", "z", "a", "f", "p", "n", "µ", "m", "", "k", "M", "G", "T", "P", "E", "Z", "Y"]
_THOUSANDS = [1.0, 1e3, 1e6, 1e9, 1e12, 1e15, 1e18, 1e21, 1e24]
_TENS = [1.0, 10.0, 100.0]


def _scale_and_round(value: float, group: int, places: int) -> Tuple[float, int]:
    scaled = value / _THOUSANDS[group] if group >= 0 else value * _THOUSANDS[-group]
    if places < 0:
        unit = _TENS[-places]
        return round_float(scaled / unit, 0) * unit, 0
    p = 12 if places > 12 else places
    return round_float(scaled, p), p


def format_si(value: float, significant: int) -> str:
    """A number with an SI prefix and ``significant`` significant digits,
    trailing zeros dropped: 1200 is "1.2k", 0.0015 is "1.5m"."""
    if isinstance(significant, bool) or not isinstance(significant, int) or significant < 1 or significant > 15:
        raise ValueError("significant must be a whole number from 1 to 15, received %r" % (significant,))
    if isinstance(value, bool) or not isinstance(value, (int, float)) or not math.isfinite(value):
        raise ValueError("value must be a finite number, received %r" % (value,))
    value = float(value)
    if value == 0:
        return "0"
    a = abs(value)
    exponent = 0
    if a >= 1:
        p = 1.0
        while p * 10 <= a:
            p *= 10
            exponent += 1
    else:
        q = 1.0
        while a * q < 1:
            q *= 10
            exponent -= 1
    group = exponent // 3
    group = max(-8, min(8, group))
    rounded, places = _scale_and_round(value, group, significant - 1 - (exponent - 3 * group))
    if abs(rounded) >= 1000 and group < 8:
        group += 1
        rounded, places = _scale_and_round(value, group, significant - 1)
    return format_decimal(rounded, places, True, "") + _PREFIXES[group + 8]

Imports name this capability’s declared dependencies, which fune builds next to it in your project; each one links to its page.

import math

from .math_round_float import round_float  ← from math.round-float ^1.0.0 · built alongside by fune
from .text_format_decimal import format_decimal  ← from text.format-decimal ^1.0.0 · built alongside by fune


def format_percent(value: float, decimals: int) -> str:
    """A fraction as a percentage with fixed places; the product is cleaned of
    binary noise at 12 places first, so 0.145 is "15%", not "14%"."""
    if isinstance(value, bool) or not isinstance(value, (int, float)) or not math.isfinite(value):
        raise ValueError("value must be a finite number, received %r" % (value,))
    percent = round_float(float(value) * 100, 12)
    return format_decimal(percent, decimals, False, "") + "%"

Imports name this capability’s declared dependencies, which fune builds next to it in your project; each one links to its page.

from .charts_format_types import DateLabel
from .dates_add_days import parse_iso_date  ← from dates.add-days ^1.0.0 · built alongside by fune

_MONTHS = ["Jan", "Feb", "Mar", "Apr", "May", "Jun", "Jul", "Aug", "Sep", "Oct", "Nov", "Dec"]


def format_date(iso: str, label: DateLabel) -> str:
    """A date as a tick label for the interval it stands for."""
    date = parse_iso_date(iso)
    year = iso[0:4]
    month = _MONTHS[date.month - 1]
    if label in ("day", "week"):
        return "%d %s" % (date.day, month)
    if label == "month":
        return "%s %s" % (month, year)
    if label == "quarter":
        return "Q%d %s" % ((date.month - 1) // 3 + 1, year)
    if label == "year":
        return year
    raise ValueError('unknown date label "%s"; use day, week, month, quarter or year' % (label,))

Imports name this capability’s declared dependencies, which fune builds next to it in your project; each one links to its page.

import math

from .math_round_float import round_float  ← from math.round-float ^1.0.0 · built alongside by fune
from .money_amount import money  ← from money.amount ^1.0.0 · built alongside by fune
from .money_format import format_money  ← from money.format ^1.0.0 · built alongside by fune


def format_money_tick(minor: float, currency: str) -> str:
    """A money-axis tick: rounded half away from zero to a whole minor unit,
    then printed by money.format."""
    if isinstance(minor, bool) or not isinstance(minor, (int, float)) or not math.isfinite(minor):
        raise ValueError("minor must be a finite number, received %r" % (minor,))
    return format_money(money(int(round_float(minor, 0)), currency))