human.py

#! /usr/bin/env python3
# -*- coding: utf-8; py-indent-offset: 4 -*-
#
# Author:  Linuxfabrik GmbH, Zurich, Switzerland
# Contact: info (at) linuxfabrik (dot) ch
#          https://www.linuxfabrik.ch/
# License: The Unlicense, see LICENSE file.

# https://github.com/Linuxfabrik/lib/blob/main/CONTRIBUTING.md

"""Functions to convert raw numbers, times etc. to a human readable representation (and sometimes
back).
"""

__author__ = 'Linuxfabrik GmbH, Zurich/Switzerland'
__version__ = '2026101201'

import math
import re

# Pre-computed thresholds for bits2human (descending order)
_BITS_THRESHOLDS = (
    ('YiB', 9671406556917033397649408),
    ('ZiB', 9444732965739290427392),
    ('EiB', 9223372036854775808),
    ('PiB', 9007199254740992),
    ('TiB', 8796093022208),
    ('GiB', 8589934592),
    ('MiB', 8388608),
    ('KiB', 8192),
    ('B', 8),
)

# Pre-computed thresholds for bps2human (descending order)
_BPS_THRESHOLDS = (
    ('Ybps', 1000000000000000000000000),
    ('Zbps', 1000000000000000000000),
    ('Ebps', 1000000000000000000),
    ('Pbps', 1000000000000000),
    ('Tbps', 1000000000000),
    ('Gbps', 1000000000),
    ('Mbps', 1000000),
    ('Kbps', 1000),
    ('bps', 1),
)

# Pre-computed thresholds for bytes2human (descending order)
_BYTES_THRESHOLDS = (
    ('YiB', 1208925819614629174706176),
    ('ZiB', 1180591620717411303424),
    ('EiB', 1152921504606846976),
    ('PiB', 1125899906842624),
    ('TiB', 1099511627776),
    ('GiB', 1073741824),
    ('MiB', 1048576),
    ('KiB', 1024),
    ('B', 1),
)

# Pre-computed multipliers for human2bytes (binary units always 1024-based)
_BINARY_MULTIPLIERS = (
    ('yib', 1208925819614629174706176),
    ('zib', 1180591620717411303424),
    ('eib', 1152921504606846976),
    ('pib', 1125899906842624),
    ('tib', 1099511627776),
    ('gib', 1073741824),
    ('mib', 1048576),
    ('kib', 1024),
)

# Pre-computed multipliers for human2bytes (decimal, base 1024)
_DECIMAL_1024_MULTIPLIERS = (
    ('yb', 1208925819614629174706176),
    ('y', 1208925819614629174706176),
    ('zb', 1180591620717411303424),
    ('z', 1180591620717411303424),
    ('eb', 1152921504606846976),
    ('e', 1152921504606846976),
    ('pb', 1125899906842624),
    ('p', 1125899906842624),
    ('tb', 1099511627776),
    ('t', 1099511627776),
    ('gb', 1073741824),
    ('g', 1073741824),
    ('mb', 1048576),
    ('m', 1048576),
    ('kb', 1024),
    ('k', 1024),
)

# Pre-computed multipliers for human2bytes (decimal, base 1000)
_DECIMAL_1000_MULTIPLIERS = (
    ('yb', 1000000000000000000000000),
    ('y', 1000000000000000000000000),
    ('zb', 1000000000000000000000),
    ('z', 1000000000000000000000),
    ('eb', 1000000000000000000),
    ('e', 1000000000000000000),
    ('pb', 1000000000000000),
    ('p', 1000000000000000),
    ('tb', 1000000000000),
    ('t', 1000000000000),
    ('gb', 1000000000),
    ('g', 1000000000),
    ('mb', 1000000),
    ('m', 1000000),
    ('kb', 1000),
    ('k', 1000),
)

# Pre-computed unit to seconds mapping for human2seconds.
# `D`/`W` are the canonical Linuxfabrik markers for day/week, and
# `d`/`w` are accepted as aliases so third-party tools that use the
# Unix convention (exim `mailq`, systemd timers, `sleep 3d`, etc.)
# can be parsed without a normalization wrapper in every caller.
_UNIT_TO_SECONDS = {
    's': 1,
    'm': 60,
    'h': 3600,
    'd': 86400,
    'D': 86400,
    'w': 604800,
    'W': 604800,
    'M': 2592000,
    'Y': 31536000,
}

# Pre-computed SI prefixes for number2human
_SI_PREFIXES = ('', 'K', 'M', 'G', 'T', 'P', 'E', 'Z', 'Y')
_SI_PREFIXES_MAX_IDX = 8  # len(_SI_PREFIXES) - 1

# Pre-computed time units for seconds2human (full names)
_TIME_UNITS_FULL = (
    ('years', 31536000),
    ('months', 2592000),
    ('weeks', 604800),
    ('days', 86400),
    ('hours', 3600),
    ('minutes', 60),
    ('seconds', 1),
    ('millisecs', 1e-3),
    ('microsecs', 1e-6),
    ('nanosecs', 1e-9),
    ('picosecs', 1e-12),
)

# Picoseconds per second, the resolution the sub-second units of the tables above
# are counted in so that seconds2human() can divide in whole numbers.
_PICOS_PER_SECOND = 10**12

# Pre-computed time units for seconds2human (short names)
_TIME_UNITS_SHORT = (
    ('Y', 31536000),
    ('M', 2592000),
    ('W', 604800),
    ('D', 86400),
    ('h', 3600),
    ('m', 60),
    ('s', 1),
    ('ms', 1e-3),
    ('us', 1e-6),
    ('ns', 1e-9),
    ('ps', 1e-12),
)


def _to_human(n, thresholds, fallback_unit, decimals=1, space=False):
    """Render `n` with the largest unit of `thresholds` that leaves a value >= 1.

    The shared body of `bytes2human()`, `number2human()` and `seconds2human()`:
    each passes its own thresholds and the unit to fall back to where no
    threshold is reached.
    """
    # compare against the absolute value so negative deltas (counter resets,
    # memory reclaimed, bandwidth swings) still get scaled to a unit that
    # matches their magnitude. e.g. -1048576 bytes reads as '-1.0MiB'.
    sep = ' ' if space else ''
    if not math.isfinite(n):
        # no unit scales infinity, and nan has no magnitude to pick one by
        return f'{float(n)}{sep}{fallback_unit}'
    abs_n = abs(n)
    units = (*thresholds, (fallback_unit, 1))
    # the largest unit the value reaches, the fallback unit (size 1) for anything less
    index = next(
        (i for i, (_, threshold) in enumerate(units) if abs_n >= threshold),
        len(units) - 1,
    )
    symbol, threshold = units[index]
    # A value that rounds up to the size of the next larger unit moves into it:
    # 1048575 bytes is 1023.999KiB and would read 1024.0KiB, which is 1.0MiB.
    if index and round(abs_n / threshold, decimals) * threshold >= units[index - 1][1]:
        symbol, threshold = units[index - 1]
    return f'{float(n) / threshold:.{decimals}f}{sep}{symbol}'


def bits2human(n, decimals=1, space=False):
    """
    Converts a given number of bits to a human-readable string.

    Parameters
    ----------
    n : int or float
        The number of bits to convert.
    decimals : int, optional
        Number of decimal places.
        Defaults to 1.
    space : bool, optional
        If True, adds a space between
        the value and unit. Defaults to False.

    Returns
    -------
    str
        A string like '1.0KiB' or '1.0 KiB'.

    Examples
    --------
    >>> bits2human(8192)
    '1.0KiB'

    >>> bits2human(8192, decimals=2)
    '1.00KiB'

    >>> bits2human(8192, space=True)
    '1.0 KiB'

    >>> bits2human(8192, decimals=3, space=True)
    '1.000 KiB'
    """
    return _to_human(n, _BITS_THRESHOLDS, 'B', decimals, space)


def bps2human(n, decimals=1, space=False):
    """
    Converts a given number of bits per second to a
    human-readable format (e.g., bps, Kbps, Mbps, etc.).

    Parameters
    ----------
    n : int or float
        The number of bits per second
        to convert.
    decimals : int, optional
        Number of decimal places.
        Defaults to 1.
    space : bool, optional
        If True, adds a space between
        the value and unit. Defaults to False.

    Returns
    -------
    str
        The human-readable representation of the input
        bits per second with the appropriate unit (e.g., '72Mbps').

    Examples
    --------
    >>> bps2human(72000000)
    '72.0Mbps'

    >>> bps2human(72000000, decimals=0)
    '72Mbps'

    >>> bps2human(72000000, decimals=2, space=True)
    '72.00 Mbps'
    """
    return _to_human(n, _BPS_THRESHOLDS, 'bps', decimals, space)


def bytes2human(n, decimals=1, space=False):
    """
    Converts a given number of bytes to a human-readable format
    (e.g., B, KiB, MiB, etc.).

    Parameters
    ----------
    n : int or float
        The number of bytes to convert.
    decimals : int, optional
        Number of decimal places.
        Defaults to 1.
    space : bool, optional
        Whether to add a space between
        value and unit. Defaults to False.

    Returns
    -------
    str
        The human-readable representation of the input
        bytes with the appropriate unit (e.g., '1.0KiB').

    Examples
    --------
    >>> bytes2human(1023)
    '1023.0B'

    >>> bytes2human(1024)
    '1.0KiB'

    >>> bytes2human(1536, decimals=2)
    '1.50KiB'

    >>> bytes2human(1048576, decimals=1, space=True)
    '1.0 MiB'
    """
    return _to_human(n, _BYTES_THRESHOLDS, 'B', decimals, space)


def extract_hrnumbers(s, boundaries=None):
    """
    Extracts all numbers from a string that start with a digit and end with a known boundary.

    This function scans the input string and extracts substrings that start with a digit and end
    with a known boundary character (such as 's', 'm', 'h', etc.), and returns these substrings
    as a list.

    Parameters
    ----------
    s : str
        The input string to extract numbers from.
    boundaries : list, optional
        A list of boundary characters that signify the end of
        a number. Defaults to `['s', 'm', 'h', 'd', 'D', 'w', 'W', 'M', 'Y']`, where
        `d` and `w` are aliases of `D` and `W`.

    Returns
    -------
    list
        A list of strings representing the extracted numbers along with their boundaries.

    Examples
    --------
    >>> string = '31Y 20M7s  88  abc12xyz   4s 5'
    >>> extract_hrnumbers(string)
    ['31Y', '20M', '7s', '4s']

    >>> extract_hrnumbers('1.5h 30m')
    ['1.5h', '30m']

    >>> string = '17G 3M 4B'
    >>> extract_hrnumbers(string, boundaries=['G', 'M', 'B'])
    ['17G', '3M', '4B']
    """
    if boundaries is None:
        # `d`/`w` are lowercase aliases for the canonical `D`/`W`
        # markers; see the note on `_UNIT_TO_SECONDS` above.
        boundaries = ['s', 'm', 'h', 'd', 'D', 'w', 'W', 'M', 'Y']

    # A number may carry a fraction, so '2.5h' stays '2.5h' instead of losing its
    # integer part. The lookbehind keeps a number from starting in the middle of
    # another one: '.5h' or '1.2.3h' yield nothing rather than '5h' or '2.3h'.
    units = ''.join(re.escape(boundary) for boundary in boundaries)
    if not units:
        return []
    return re.findall(r'(?<![\d.])\d+(?:\.\d+)?[' + units + ']', s)


def human2bytes(string, binary=True):
    """
    Converts a human-readable string to the equivalent number of bytes.

    This function converts a string representation of a file size, such as '3.072GiB' or '3.072GB',
    into the corresponding number of bytes. It supports both binary (base 1024) and decimal
    (base 1000) units.

    Parameters
    ----------
    string : str
        A string representing the size to convert. It can include any of the
        common size units like 'GiB', 'GB', 'MB', 'kB', etc. A string carrying no unit at all is
        read as a plain byte count.
    binary : bool, optional
        If True (default), the function will use binary units
        (base 1024). If False, it will use decimal units (base 1000).

    Returns
    -------
    int
        The equivalent size in bytes, or 0 if the conversion fails.

    Notes
    -----
    - The result is truncated towards zero, so '3.7' and '3.7B' both yield 3.

    Examples
    --------
    >>> human2bytes('3.072GiB')
    3298534883

    >>> human2bytes('3.072G', binary=False)
    3072000000

    >>> human2bytes('1024')
    1024
    """
    try:
        string_lower = string.lower()

        # Check binary units first (always 1024-based)
        for unit, multiplier in _BINARY_MULTIPLIERS:
            if unit in string_lower:
                return int(float(string_lower.replace(unit, '').strip()) * multiplier)

        # Check decimal units (base depends on binary parameter)
        multipliers = _DECIMAL_1024_MULTIPLIERS if binary else _DECIMAL_1000_MULTIPLIERS
        for unit, multiplier in multipliers:
            if unit in string_lower:
                return int(float(string_lower.replace(unit, '').strip()) * multiplier)

        # Check for plain 'b' (bytes)
        if 'b' in string_lower:
            return int(float(string_lower.replace('b', '').strip()))

        # No unit at all: the value is already a byte count. Consumers hand this
        # function raw counts from configuration files (`gcache.size = 134217728`,
        # a php.ini directive written as a plain integer) and thresholds an
        # administrator typed without a qualifier. Returning 0 for those turns a
        # threshold into "alert on anything above zero" without saying so.
        return int(float(string_lower.strip()))
    except Exception:
        # Not a size at all. Callers treat 0 as "nothing to compare against".
        return 0


def human2seconds(string):
    """
    Converts a human-readable duration into seconds.

    This function converts durations given in a human-readable format (e.g., '2.5h', '26Y')
    into the corresponding number of seconds. The units supported are: years (Y), months (M),
    weeks (W), days (D), hours (h), minutes (m), and seconds (s).

    Parameters
    ----------
    string : str
        A string representing the duration. It should include a numeric
        value followed by one of the supported units ('Y', 'M', 'W', 'D', 'h', 'm', or 's').

    Returns
    -------
    int
        The equivalent duration in seconds, rounded down to the nearest integer.
        Returns 0 if invalid.

    Examples
    --------
    >>> human2seconds('26Y')
    819936000

    >>> human2seconds('26M')
    67392000

    >>> human2seconds('26W')
    15724800

    >>> human2seconds('26D')
    2246400

    >>> human2seconds('26h')
    93600

    >>> human2seconds('26m')
    1560

    >>> human2seconds('26s')
    26

    >>> human2seconds('1.5W')
    907200

    >>> lib.human.human2seconds('0.5D')
    43200

    >>> human2seconds('2.5h')
    9000

    >>> human2seconds('a7.3X')
    0

    >>> human2seconds('invalid')
    0
    """
    string = string.strip()
    if not string or len(string) < 2:
        return 0

    unit = string[-1]
    value_str = string[:-1]

    if unit not in _UNIT_TO_SECONDS:
        return 0

    try:
        value = float(value_str)
    except (ValueError, TypeError):
        return 0

    seconds = value * _UNIT_TO_SECONDS[unit]
    return int(seconds) if math.isfinite(seconds) else 0


def humanduration2seconds(text):
    """
    Converts a complex human-readable duration string into seconds by summing individual durations.

    This function processes a string that may contain multiple duration components
    (e.g., '3Y 2M 7s') and converts each component into seconds. It ignores non-valid components
    (e.g., 'any-error') and sums the valid ones.

    Parameters
    ----------
    text : str
        A string containing one or more human-readable durations, where each
        duration is represented by a number followed by a unit (e.g., '3Y', '2M', '7s').
        Invalid components are ignored.

    Returns
    -------
    int
        The total duration in seconds, summing all valid duration components. Returns 0 if
        no valid components are found.

    Examples
    --------
    A component the text does not separate is still read, and `d` counts as a day:

    >>> humanduration2seconds('3Y 2M any-error 3d7s')
    100051207
    """
    return sum(human2seconds(duration) for duration in extract_hrnumbers(text))


# A bound the converters can read: one or more groups of a number followed by its unit,
# so `4K`, `5 MiB` and the `1Y1D` of a duration. Kept in step with the numbers
# `lib.base._parse_range()` accepts, so that a bound this module converts and a bound an
# administrator writes without a unit are held to the same grammar: no decimal comma, no
# thousands separator, nothing Python would read as a number but the range syntax does
# not define. Exponent notation is not one grammar here: in a size, `e` is exa, and
# `1e3` is three exabytes rather than the thousand it would be in a bare threshold.
#
# Every group but the last ends in a unit or in a space, so a run of digits belongs to
# exactly one group. Where groups may end in a digit, `1234` splits into as many groups
# as it has digits, and a bound that only fails at its last character costs 2^n to
# reject: the earlier `(?:\s*\d+(?:\.\d+)?\s*[A-Za-z]*\s*)+` needed 4.8s for 26
# digits (CPython 3.14, reported by CodeQL as py/redos). It also drops `0.00.0`, read
# until now as the two numbers `0.0` and `0.0`: no converter can read it, so it came
# back as the bound 0, which alerts on every value but zero.
_QUANTITY = re.compile(
    r'^\s*'
    r'(?:\d+(?:\.\d+)?\s*[A-Za-z]+\s*|\d+(?:\.\d+)?\s+)*'
    r'\d+(?:\.\d+)?\s*[A-Za-z]*\s*$'
)


def _convert_range(text, convert_fn):
    """Convert every bound of a Nagios range with `convert_fn`, marker by marker.

    A range is split on `:`, and the markers a bound may carry (`-`, `~`, `@`)
    are kept as they are, so only the number itself is converted.
    """
    parts = []
    for part in text.split(':'):
        raw = part.replace('-', '').replace('~', '').replace('@', '')
        if not raw:
            # The bound carries no number, it is only a marker: an omitted bound, `~`
            # for negative infinity, or a bare `@` for an inverted range. There is
            # nothing to convert, and `str.replace('', x)` would splice `x` between
            # every character and turn `~` into `0~0`, which no range parser accepts.
            # An omitted bound is kept in place rather than dropped: it is what tells
            # the range parser which side is open, and a `:` that lost it becomes a
            # range nobody can read.
            parts.append(part)
            continue
        if not _QUANTITY.match(raw):
            # Not a quantity the converters can read. They answer 0 for anything they
            # cannot, which as a range bound is not "nothing to compare against" but the
            # threshold zero: `1,5M` with a decimal comma would silently become `0:0`
            # and alert on every value but zero. Handing the bound on unconverted lets
            # the range parser reject it and the caller report UNKNOWN.
            parts.append(part)
            continue
        parts.append(part.replace(raw, str(convert_fn(raw))))
    return ':'.join(parts)


def humanrange2bytes(text):
    """
    Converts a Nagios range (e.g., `@4K:5 MiB`) into a range
    in bytes, where the base is always 1024.

    Parameters
    ----------
    text : str
        A Nagios-style range string, such as
        '@4K:5 MiB', where units like K, M, or B are used. A bound
        without a unit is taken as a byte count.

    Returns
    -------
    str
        The range with each value converted into bytes,
        using 1024 as the base for conversions.

    Notes
    -----
    - The markers of the range syntax are preserved: an omitted
      bound, `~` for negative infinity, the `@` of an inverted
      range, and the sign of a negative bound.

    Examples
    --------
    >>> text = '@4K:5 MiB'
    >>> humanrange2bytes(text)
    '@4096:5242880'

    >>> humanrange2bytes('~:1M')
    '~:1048576'
    """
    return _convert_range(text, human2bytes)


def humanrange2seconds(string):
    """
    Converts a Nagios range to seconds by interpreting the
    duration components and summing them.

    Parameters
    ----------
    string : str
        A Nagios-style range string, such as
        '@10m:1Y1D', where units like 'm', 'Y', 'D' are used.

    Returns
    -------
    str
        The range with each value converted into seconds.

    Examples
    --------
    >>> string = '@10m:1Y1D'
    >>> humanrange2seconds(string)
    '@600:31622400'
    """
    return _convert_range(string, humanduration2seconds)


def number2human(number):
    """
    Converts a number into a human-readable format using SI prefixes.

    This function converts large numbers into a more concise format with SI prefixes
    (e.g., 1,000 becomes '1K', 1,000,000 becomes '1M'). It supports values from 1 to extremely large
    numbers (up to 'Y' for 10^24).

    Parameters
    ----------
    number : int or float
        The number to convert into a human-readable format.

    Returns
    -------
    str
        The number formatted with an appropriate SI prefix.

    Notes
    -----
    - A fraction that turns out to be zero is dropped: `2` rather than `2.0`. Most of what
      this formats are counts of things, and a decimal place claims a precision a count does
      not have.

    Examples
    --------
    >>> number2human(2)
    '2'

    >>> number2human(123456.8)
    '123.5K'

    >>> number2human(123456789.0)
    '123.5M'

    >>> number2human(9223372036854775808)
    '9.2E'

    >>> number2human(999999)
    '1M'

    >>> number2human(float('inf'))
    'inf'
    """
    try:
        number = float(number)
    except Exception:
        return number
    if not math.isfinite(number):
        # no prefix scales infinity, and nan has no magnitude to pick one by
        return str(number)

    millidx = 0 if number == 0 else math.floor(math.log10(abs(number)) / 3)

    millidx = max(0, min(_SI_PREFIXES_MAX_IDX, millidx))
    scaled = number / 10 ** (3 * millidx)
    if abs(round(scaled, 1)) >= 1000 and millidx < _SI_PREFIXES_MAX_IDX:
        # 999999 is 999.999K and prints as 1000.0K, which is 1M
        millidx += 1
        scaled = number / 10 ** (3 * millidx)
    text = f'{scaled:.1f}'
    if text.endswith('.0'):
        text = text[:-2]
    return f'{text}{_SI_PREFIXES[millidx]}'


def seconds2human(seconds, keep_short=True, full_name=False):
    """
    Converts a number of seconds into a human-readable time range string.

    This function takes a number of seconds and returns a string that expresses that duration in
    a more understandable format. It supports both short and full-form time units (e.g., "1m" for
    minutes, "1 hour 30 minutes" for the full form).

    Parameters
    ----------
    seconds : int or float or str
        The number of seconds to convert.
    keep_short : bool, optional
        If True, returns only the largest two time units
        (default is True).
    full_name : bool, optional
        If True, returns full names for the time units
        (default is False).

    Returns
    -------
    str
        The formatted time duration in a human-readable format.

    Examples
    --------
    >>> seconds2human(0.125)
    '125ms'

    >>> seconds2human(1)
    '1s'

    >>> seconds2human(59)
    '59s'

    >>> seconds2human(60)
    '1m'

    >>> seconds2human(61)
    '1m 1s'

    >>> seconds2human(1387775)
    '2W 2D'

    >>> seconds2human('1387775')
    '2W 2D'

    >>> seconds2human('1387775', full_name=True)
    '2weeks 2days'

    >>> seconds2human(1387775, keep_short=False, full_name=True)
    '2weeks 2days 1hour 29minutes 35seconds'

    >>> seconds2human(0)
    '0s'

    >>> seconds2human(-5)
    '-5s'

    >>> seconds2human(1e-13)
    '0s'

    >>> seconds2human(float('inf'))
    'infs'
    """
    seconds = float(seconds)
    zero = '0seconds' if full_name else '0s'

    # No unit of zero is non-zero, so the loop below would return an empty string and
    # drop the duration out of the sentence it was formatted for.
    if seconds == 0:
        return zero
    if not math.isfinite(seconds):
        # no unit divides infinity, and nan has no magnitude to split
        return f'{seconds}seconds' if full_name else f'{seconds}s'

    # A negative duration is formatted like its positive counterpart and signed. The
    # division below rounds towards minus infinity, which turned -5 into '-1Y 12M'.
    sign = '-' if seconds < 0 else ''
    seconds = abs(seconds)

    # The duration is split into whole seconds and a fraction counted in whole
    # picoseconds, and every division below is an integer one. Dividing the float
    # itself by the size of each unit cannot be exact for the sub-second units,
    # because a tenth of a second has no exact binary representation: 0.35 // 1e-3
    # is 349.0, so 0.35 came out as "349ms 999us" instead of "350ms".
    whole = int(seconds)
    fraction = round((seconds - whole) * _PICOS_PER_SECOND)
    if fraction >= _PICOS_PER_SECOND:
        # the rounding carried over into the next second
        whole += 1
        fraction -= _PICOS_PER_SECOND

    units = _TIME_UNITS_FULL if full_name else _TIME_UNITS_SHORT

    result = []
    for name, count in units:
        if count >= 1:
            value, whole = divmod(whole, int(count))
        else:
            value, fraction = divmod(fraction, round(count * _PICOS_PER_SECOND))
        if value:
            if full_name and value == 1:
                name = name.rstrip('s')
            result.append(f'{value}{name}')

    if not result:
        # shorter than half the smallest unit, a picosecond: rounds to zero
        return zero
    if keep_short and len(result) > 2:
        return sign + ' '.join(result[:2])
    return sign + ' '.join(result)