Skip to content

Duration

duration

Short human rendering of millisecond durations.

Canonical stdlib-only formatter so a duration like 1500 renders uniformly as '1.5s' across AXM surfaces, instead of drifting between '1500ms' and datetime.timedelta's '0:00:01.500000'.

format_duration(millis)

Render a millisecond duration as a short human string.

Rendering bands are milliseconds for 0 <= millis < 1000, seconds for 1000 <= millis < 60000, minutes for 60000 <= millis < 3600000, and hours for millis >= 3600000.

450 → '450ms', 1500 → '1.5s', 90000 → '1.5min', 5400000 → '1.5h'. Bands round to at most one decimal (rounded, not truncated). Negative, non-numeric or non-finite input returns 'n/a' without raising.

Source code in packages/axm-ingot/src/axm_ingot/duration.py
Python
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
def format_duration(millis: float) -> str:
    """Render a millisecond duration as a short human string.

    Rendering bands are milliseconds for ``0 <= millis < 1000``, seconds for
    ``1000 <= millis < 60000``, minutes for
    ``60000 <= millis < 3600000``, and hours for ``millis >= 3600000``.

    ``450`` → ``'450ms'``, ``1500`` → ``'1.5s'``, ``90000`` → ``'1.5min'``,
    ``5400000`` → ``'1.5h'``. Bands round to at most one decimal (rounded,
    not truncated). Negative, non-numeric or non-finite input returns
    ``'n/a'`` without raising.
    """
    try:
        value = float(millis)
    except (TypeError, ValueError):
        return _FALLBACK
    if not math.isfinite(value) or value < 0:
        return _FALLBACK
    if value < _SECOND:
        return f"{int(value)}ms"
    if value < _MINUTE:
        return f"{round(value / _SECOND, 1)}s"
    if value < _HOUR:
        return f"{round(value / _MINUTE, 1)}min"
    return f"{round(value / _HOUR, 1)}h"