base.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

"""Provides very common every-day functions."""

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

import math
import numbers
import operator
import os
import re
import sys

from . import human, txt
from .globals import STATE_CRIT, STATE_OK, STATE_UNKNOWN, STATE_WARN

# A `<` that opens what a web interface would read as an HTML tag. This mirrors the
# expression Icinga Web uses to decide whether a plugin output is HTML or plain text
# (`Icingadb\Util\PluginOutput`, and the same one in the classic monitoring module).
# Only such a `<` is escaped, so comparisons and shell snippets survive verbatim while
# the output still cannot be mistaken for markup. See `oao()`.
TAG_START = re.compile(r'<(?=\w+(?:\s\w+=[^>]*)?>)')

WINDOWS = os.name == 'nt'
LINUX = sys.platform.startswith('linux')

# True on any 64-bit Python (x86_64, aarch64, ppc64*, s390x, riscv64, ...).
IS_64BIT = sys.maxsize > 2**32

if WINDOWS:
    # A monitoring agent reads a consumer's stdout through a pipe, and on Windows
    # Python gives a pipe the ANSI code page (cp1252 on a Western install) and
    # translates every "\n" into "\r\n" (`create_stdio()` in CPython's
    # Python/pylifecycle.c). Icinga 2 reads the output as UTF-8, so an "ä" arrives as
    # an invalid byte, and a character the code page lacks ("ő") ends the run with a
    # UnicodeEncodeError, exit 1 and so a WARNING. It also splits the output at "\r"
    # and "\n" alike (`PluginUtility::ParseCheckOutput()`), which turns every CRLF into
    # an empty line of its own. The console is not affected, as Python writes it
    # through the console API, which is why a run by hand looks fine. Verified with
    # Python 3.14 and Icinga 2 v2.16.5 on Windows Server 2025. Doing it here, on
    # import, covers every write to stdout, the consumer's own and argparse's
    # included.
    #
    # stderr gets the same treatment: the agent passes it on together with stdout,
    # and argparse writes its usage and error messages there. Without it, every line
    # of a "the following arguments are required" message arrived followed by an empty
    # one. Verified with Python 3.13 and Icinga 2 v2.16.5 on Windows Server 2025.
    for _stream in (sys.stdout, sys.stderr):
        try:
            _stream.reconfigure(encoding='utf-8', errors='replace', newline='\n')
        except AttributeError:
            # the stream was replaced by an object without reconfigure(), such as an
            # io.StringIO in a test, or is None under pythonw.exe
            pass

_OPS = {
    'ge': operator.ge,
    'gt': operator.gt,
    'le': operator.le,
    'lt': operator.lt,
    'eq': operator.eq,
    'ne': operator.ne,
}

_STATE_NAMES = {
    STATE_OK: '[OK]',
    STATE_WARN: '[WARNING]',
    STATE_CRIT: '[CRITICAL]',
    STATE_UNKNOWN: '[UNKNOWN]',
}


def coe(result, state=STATE_UNKNOWN):
    """
    Continue or Exit (CoE)

    This function simplifies error handling for function calls that return a `(success, result)`
    tuple. If the operation fails, it sanitizes and prints the error message and exits with a given
    state. Otherwise, it returns the successful result and allows the script to continue.

    Parameters
    ----------
    result : tuple
        A two-element tuple returned from a function.

        - `result[0]` (`bool`): Success indicator (`True` if successful, `False` otherwise).
        - `result[1]` (`any`): The actual result or an error message.
    state : int, optional
        Exit code to use if the function fails.
        Defaults to `STATE_UNKNOWN` (3).

    Returns
    -------
    any type
        The second element of the result tuple (`result[1]`) if successful.

    Notes
    -----
    - Sensitive information in error messages is automatically redacted before printing.
    - The message is escaped like in `oao()`: `|` becomes `!`, and a `<` that would open an
      HTML tag becomes `&lt;`.
    - This function is intended to be used **only** inside the `main()` function of the
      calling script, not inside library functions.
    - If the function fails (`result[0]` is `False`), the script immediately exits after printing
      the sanitized message.

    Examples
    --------
    Without `coe`:
    >>> success, html = lib.url.fetch(URL)
    >>> if not success:
    ...     print(html)
    ...     sys.exit(STATE_UNKNOWN)

    With `coe`:
    >>> html = lib.base.coe(lib.url.fetch(URL))
    """
    if result[0]:
        # success
        return result[1]
    # getting something like `(False, 'Error message')`; hide passwords in error message,
    # and escape it like `oao()` does: on a line where an `=` follows it, a `|` cuts the
    # message short and hands the rest to Icinga as performance data
    # (`PluginUtility::ParseCheckOutput()`, verified against Icinga 2 v2.16.0).
    msg = txt.sanitize_sensitive_data(str(result[1]))
    print(_escape_tag_start(msg).replace('|', '!'))
    sys.exit(state)


def cu(msg=None, traceback=True):
    """
    See you (cu)

    Print an optional error message and stack trace, then exit with STATE_UNKNOWN.

    This function prints an optional sanitized message, attaches a stack trace if an error occurred,
    and exits the script with `STATE_UNKNOWN`. Message and stack trace are escaped like in
    `oao()`: `|` becomes `!`, and a `<` that would open an HTML tag becomes `&lt;`.

    Parameters
    ----------
    msg : str, optional
        An optional message to print before exiting.
        If provided, it will be stripped, sanitized, and printed.
    traceback : bool, optional
        Whether to attach the stack trace of the exception being handled. Defaults to
        `True`. Pass `False` where the exception is the expected answer rather than a
        defect: a socket that is not there because the service is not installed, a
        command that is absent on this platform. The admin gets the sentence that says
        so, and no Python stack trace for a situation nobody needs to debug.

    Returns
    -------
    None
        This function does not return; it always exits the script with `STATE_UNKNOWN`.

    Notes
    -----
    - If a traceback exists, it is included for debugging, escaped like the message.
    - Sensitive information in the message is automatically redacted before printing.
    - If no traceback is present, only the optional message (if any) is printed.

    Examples
    --------
    >>> cu('Unable to connect to server')

    >>> cu()

    >>> cu('strongSwan is not running here.', traceback=False)
    """
    has_traceback = traceback and sys.exc_info()[0] is not None
    tb = None
    if has_traceback:
        # Imported here, not at module level: only a failing run needs it, and on
        # Python 3.14 `traceback` pulls in `_colorize`, `dataclasses` and `inspect`,
        # which costs every consumer of lib.base about 10 ms of startup time.
        from traceback import format_exc

        tb = format_exc()

    if msg is not None:
        # Normalize line endings to LF (see oao); error output may also carry
        # CRLF, for example when a Windows command prints its error to stdout.
        msg = msg.replace('\r\n', '\n').replace('\r', '\n')
        msg = _escape_tag_start(txt.sanitize_sensitive_data(msg).strip()).replace(
            '|', '!'
        )
        print(msg, end='')
        print(
            ' (Traceback for debugging purposes attached)\n' if has_traceback else '\n'
        )

    if has_traceback:
        print(_escape_tag_start(tb).replace('|', '!'))

    sys.exit(STATE_UNKNOWN)


def get_perfdata(label, value, uom=None, warn=None, crit=None, _min=None, _max=None):
    """
    Returns a Nagios performance data string in the format:
    `'label'=value[UOM];[warn];[crit];[min];[max]`

    Parameters
    ----------
    label : str
        The name of the performance data label.
    value : int or float
        The measured value. `None` means "nothing to report",
        and yields an empty string rather than a metric.
    uom : str, optional
        The unit of measurement (e.g., 's', 'B', '%'). Defaults to None.
    warn : int or float, optional
        Warning threshold. Defaults to None.
    crit : int or float, optional
        Critical threshold. Defaults to None.
    _min : int or float, optional
        Minimum value. Defaults to None.
    _max : int or float, optional
        Maximum value. Defaults to None.

    Returns
    -------
    str
        A properly formatted Nagios performance data string, or an empty string if
        there is no value to report.

    Notes
    -----
    - A `value` of `None` returns an empty string. A source that did not report the reading
      hands `None` through, and interpolating that would emit the literal `'label'=None`,
      which is not a number: consumers that parse the perfdata line drop the whole line over
      it, not just the one broken metric. Callers therefore no longer have to guard every
      single call.

    Examples
    --------
    >>> get_perfdata('load1', 0.42, '', 1.0, 5.0, 0, 10)
    "'load1'=0.42;1.0;5.0;0;10 "

    >>> get_perfdata('load1', None)
    ''
    """
    if value is None:
        return ''

    label = str(label).replace("'", '').replace('=', '_')
    msg = f"'{label}'={value}{uom or ''};"
    msg += f'{warn};' if warn is not None else ';'
    msg += f'{crit};' if crit is not None else ';'
    msg += f'{_min};' if _min is not None else ';'
    msg += f'{_max}' if _max is not None else ''
    return msg.rstrip(';') + ' '


def get_state(value, warn, crit, _operator='ge'):
    """
    Returns the STATE by comparing `value` to the given thresholds using
    a comparison `_operator`. `warn` and `crit` thresholds may also be `None`.

    Parameters
    ----------
    value : float
        Numeric value to evaluate.
    warn : float
        Numeric warning threshold.
    crit : float
        Numeric critical threshold.
    _operator : str
        Comparison operator to use:

        - `eq`: equal to
        - `ge`: greater or equal
        - `gt`: greater than
        - `le`: less or equal
        - `lt`: less than
        - `ne`: not equal to
        - `range`: match Nagios range definition

    Returns
    -------
    int
        `STATE_OK`, `STATE_WARN`, or `STATE_CRIT`. `STATE_UNKNOWN` for a
        threshold that does not parse, an unknown `_operator`, or a `value` that is not
        a number.

    Examples
    --------
    >>> get_state(15, 10, 20, 'ge')
    1  # STATE_WARN

    >>> get_state(10, 10, 20, 'gt')
    0  # STATE_OK
    """
    # A value that is not a number is the same kind of unusable input as a threshold
    # that does not parse, and is answered the same way instead of raising. Float
    # comparison throughout, so a bound and a value are rounded alike.
    value = _value2float(value)
    if value is None:
        return STATE_UNKNOWN

    if _operator == 'range':
        if crit is not None:
            success, result = match_range(value, crit)
            if not success:
                return STATE_UNKNOWN
            if not result:
                return STATE_CRIT
        if warn is not None:
            success, result = match_range(value, warn)
            if not success:
                return STATE_UNKNOWN
            if not result:
                return STATE_WARN
        return STATE_OK

    op = _OPS.get(_operator)
    if op is None:
        return STATE_UNKNOWN

    # `None` means "no threshold". A threshold that is given but does not read as a
    # number (`abc`, an empty string) is answered with UNKNOWN instead of raising, and
    # must not fall back to "no threshold", which would report OK.
    crit_bound = None if crit is None else _value2float(crit)
    warn_bound = None if warn is None else _value2float(warn)
    if (crit is not None and crit_bound is None) or (
        warn is not None and warn_bound is None
    ):
        return STATE_UNKNOWN
    if crit_bound is not None and op(value, crit_bound):
        return STATE_CRIT
    if warn_bound is not None and op(value, warn_bound):
        return STATE_WARN
    return STATE_OK


def _is_empty_cell(value):
    """Whether a rendered cell carries no information: empty, or one of the hyphen
    placeholders consumers print for "this object has no such field". A value that only
    starts with a hyphen, `-1` for instance, is a value and is not matched.
    """
    return str(value).strip().strip('-') == ''


def _escape_tag_start(text):
    """Replace a `<` that a web interface would read as the start of an HTML tag by
    `&lt;`. See `TAG_START` for which `<` that is.

    Both `oao()` and `get_table()` apply this. A table has to do it before it measures
    its columns: the replacement is three characters longer than what it replaces, so a
    cell escaped afterwards pushes the delimiters of its row out of line, and a value
    such as `<unknown>` bends the whole table. Escaping the cell first also leaves
    nothing for `oao()` to escape a second time.
    """
    return TAG_START.sub('&lt;', text)


def get_table(
    data,
    cols,
    header=None,
    strip=True,
    sort_by_key=None,
    sort_order_reverse=False,
    missing=None,
    hide_empty=False,
    max_rows=None,
    max_rows_label='row',
    max_rows_suffix='s',
):
    """
    Format a list of dictionaries into a simple ASCII table.

    Uses pure ASCII delimiters (`!`, `+`, `-`) instead of Unicode box-drawing characters
    (like `│`, `┼`, `─`) to guarantee correct rendering on any platform, locale, terminal,
    and transport layer regardless of encoding.

    Each dictionary must contain the specified columns (`cols`), unless `missing` states
    what to print for the ones it does not. Optionally supports a custom header, sorting by
    a given key, and stripping whitespace from values.

    Parameters
    ----------
    data : list
        List of dictionaries representing the table rows.
    cols : list
        List of keys to display as table columns.
    header : list, optional
        List of custom column headers. Defaults to None.
    strip : bool, optional
        Whether to strip whitespace from values. Defaults to True.
    sort_by_key : str, optional
        Column key to sort the table by. Defaults to None.
    sort_order_reverse : bool, optional
        Sort descending if True. Defaults to False.
    missing : str, optional
        What to print in a cell whose key the row does not have. Defaults to `None`, which
        reports the missing column instead of printing the table at all.
    hide_empty : bool, optional
        Leave out every column that no row filled in, that is one whose cells are all empty
        or all a hyphen placeholder. Defaults to False.
    max_rows : int, optional
        Render at most this many data rows and state below the table how many were left out.
        Defaults to `None`, which renders every row.
    max_rows_label : str, optional
        What the rows left out by `max_rows` are called in that sentence, in the singular.
        It is pluralized as needed. Defaults to `'row'`.
    max_rows_suffix : str, optional
        How `max_rows_label` forms its plural, passed to `txt.pluralize()`, so an irregular
        noun can be spelled out as `'entr'` plus `'y,ies'`. Defaults to `'s'`.

    Returns
    -------
    str
        A string containing the formatted table.

    Notes
    -----
    - Without `missing`, a column no row carries is treated as a mistake in the calling
      code and reported as `Unknown column "..."`, which is what a mistyped column name
      deserves. That is the default because most consumers build their rows themselves and
      a silently empty column would hide the typo.
    - A consumer whose rows come from somewhere else, such as an API that only sends the
      fields it has something to say about, passes `missing='--'` instead. One optional
      field a firmware leaves out then costs that one cell rather than the whole table.
    - `hide_empty` is for the consumer whose column set is fixed but whose rows are not:
      a consumer listing several kinds of object prints the columns that apply to none of the
      objects it actually found as a wall of hyphens, pushing the text that matters off to
      the right. It is off by default, because a column that is empty today and filled
      tomorrow would otherwise make the table change shape between runs.
    - When `hide_empty` would leave nothing at all, every column is kept. A table of
      headers says more than a blank line.
    - `max_rows` is for the consumer whose row count grows with the very situation the
      table reports, where the interesting case is also the longest one: a table per
      affected object turns into thousands of lines exactly when something went wrong,
      and whatever stores or forwards that text carries all of them. The cap keeps the
      output readable and says how much it left out, so the number is never silently
      lost. It shapes the text alone: the caller counts, aggregates and reports on the
      full `data` it passed in, which the truncated table says nothing about.
    - Rows are cut after sorting, so `max_rows` together with `sort_by_key` keeps the
      rows that sort first rather than an arbitrary selection.
    - A cell carrying a `<` that a web interface would read as the start of an HTML tag,
      `<unknown>` for example, is escaped here rather than in `oao()`, so the column
      widths are measured on the text that is actually printed and the table keeps its
      shape. See `TAG_START`.
    - Column widths come from the rows that are actually printed. A long value in a row
      that was cut does not widen the table it no longer appears in.

    Examples
    --------
    >>> data = [{'name': 'Alice', 'age': 30}, {'name': 'Bob', 'age': 25}]
    >>> cols = ['name', 'age']
    >>> print(get_table(data, cols))
    Alice ! 30
    Bob   ! 25

    >>> print(get_table(data, cols, header=['name', 'age']))
    name  ! age
    ------+----
    Alice ! 30
    Bob   ! 25

    >>> print(get_table([{'name': 'Alice'}], ['name', 'age'], missing='--'))
    Alice ! --

    >>> data = [{'name': 'Alice', 'age': '-'}, {'name': 'Bob', 'age': '-'}]
    >>> print(get_table(data, ['name', 'age'], header=['Name', 'Age'], hide_empty=True))
    Name
    -----
    Alice
    Bob

    >>> data = [{'n': 'a'}, {'n': 'b'}, {'n': 'c'}]
    >>> print(get_table(data, ['n'], max_rows=1, max_rows_label='finding'))
    a
    ... and 2 more findings.
    """
    if not data:
        return ''
    data = data.copy()  # data has been passed by-reference - kick the reference

    if sort_by_key:
        data = sorted(
            data, key=operator.itemgetter(sort_by_key), reverse=sort_order_reverse
        )

    # Cut before anything is measured, so the rows that are not printed neither widen a
    # column nor keep a column alive that `hide_empty` would otherwise drop.
    left_out = 0
    if max_rows is not None and len(data) > max_rows:
        left_out = len(data) - max_rows
        data = data[:max_rows]
    if not data:
        # `max_rows=0` asked for the count alone. A header above nothing would be a table
        # promising rows that follow.
        return (
            f'... and {left_out} more '
            f'{txt.pluralize(max_rows_label, left_out, max_rows_suffix)}.\n'
        )

    if hide_empty:
        # Judged on the rows only, before the header joins them: the header text would
        # otherwise fill every column and nothing would ever be dropped.
        kept = [
            index
            for index, col in enumerate(cols)
            if any(not _is_empty_cell(row.get(col, missing or '')) for row in data)
        ]
        if kept:
            if header:
                header = [header[index] for index in kept]
            cols = [cols[index] for index in kept]

    if header:
        data.insert(0, dict(zip(cols, header)))

    # Process values and calculate column widths in a single pass
    processed_rows = []
    column_widths = {}

    for row in data:
        processed_row = {}
        for col in cols:
            if col not in row:
                if missing is None:
                    return f'Unknown column "{col}"'
                value = _escape_tag_start(missing)
                processed_row[col] = value
                column_widths[col] = max(column_widths.get(col, 0), len(value))
                continue
            value = str(row[col])
            if strip:
                value = value.strip()
            value = _escape_tag_start(value)
            processed_row[col] = value
            column_widths[col] = max(column_widths.get(col, 0), len(value))
        processed_rows.append(processed_row)

    if header:
        divider = {col: '-' * width for col, width in column_widths.items()}
        processed_rows.insert(1, divider)

    # Generate output lines
    lines = []
    for idx, row in enumerate(processed_rows):
        parts = [f'{row[col]:<{column_widths[col]}}' for col in column_widths]
        lines.append(('-+-' if header and idx == 1 else ' ! ').join(parts))

    if left_out:
        lines.append(
            f'... and {left_out} more '
            f'{txt.pluralize(max_rows_label, left_out, max_rows_suffix)}.'
        )

    return '\n'.join(lines) + '\n'


def get_worst(*states):
    """
    Returns the worst state among any number of input states, using the
    following priority: STATE_OK < STATE_UNKNOWN < STATE_WARNING < STATE_CRITICAL.
    Any non-OK state is prioritized over STATE_OK.

    Note that numerically the priority order does not match their integer
    values. Calling with no arguments returns `STATE_OK`.

    Parameters
    ----------
    *states : int
        One or more states to compare.

    Returns
    -------
    int
        The worse state according to the priority order.

    Examples
    --------
    >>> get_worst(STATE_OK, STATE_WARN)
    1

    >>> get_worst(STATE_UNKNOWN, STATE_CRIT)
    2

    >>> get_worst(STATE_OK, STATE_WARN, STATE_CRIT)
    2
    """
    states = [int(s) for s in states]
    if STATE_CRIT in states:
        return STATE_CRIT
    if STATE_WARN in states:
        return STATE_WARN
    if STATE_UNKNOWN in states:
        return STATE_UNKNOWN
    return STATE_OK


def guess_type(v, consumer='python'):
    """
    Guess the type of a value (None, int, float, or string) for different types of consumers
    (e.g., Python, SQLite).

    For Python, it returns the actual value converted to its type (`int`, `float`, or `str`).
    For SQLite, it returns a string describing the type (`'integer'`, `'real'`, `'text'`).

    Parameters
    ----------
    v : any
        The value to guess the type for.
    consumer : str, optional
        The consumer type ('python' or 'sqlite'). Defaults to
        'python'.

    Returns
    -------
    any
        - If `consumer='python'`, returns `None`, `int`, `float`, or `str`.
        - If `consumer='sqlite'`, returns `'integer'`, `'real'`, or `'text'`.

    Examples
    --------
    >>> guess_type('1')
    1

    >>> guess_type('1', 'sqlite')
    'integer'

    >>> guess_type('1.0')
    1.0

    >>> guess_type('1.0', 'sqlite')
    'real'

    >>> guess_type('abc')
    'abc'

    >>> guess_type('abc', 'sqlite')
    'text'

    >>> guess_type(1.9)
    1.9

    >>> guess_type(float('inf'), 'sqlite')
    'real'

    >>> value_type = lib.base.guess_type(value)
    >>> if isinstance(value_type, int) or isinstance(value_type, float):
    ...     ...
    """
    if v is None:
        return None if consumer == 'python' else 'text'

    # int() is only asked about whole numbers and text: on a float it truncates, so
    # 1.9 became 1 and an 'integer', and on infinity it raises OverflowError.
    if isinstance(v, (int, str, bytes)):
        try:
            result = int(v)
            return result if consumer == 'python' else 'integer'
        except (ValueError, TypeError, OverflowError):
            pass
    try:
        result = float(v)
        return result if consumer == 'python' else 'real'
    except (ValueError, TypeError, OverflowError):
        return str(v) if consumer == 'python' else 'text'


def is_numeric(value):
    """
    Return True if the value is truly numeric (int, float, etc.).

    Parameters
    ----------
    value : any
        The value to check.

    Returns
    -------
    bool
        True if the value is numeric, otherwise False.

    Examples
    --------
    >>> is_numeric(+53.4)
    True

    >>> is_numeric('53.4')
    False
    """
    return isinstance(value, numbers.Number)


def lookup_lod(haystack, key, needle):
    """
    Search in a list of dictionaries ("lod") for a key containing a specific value
    and return the first dictionary item found.

    Returns `(index, item)` if the needle was found, otherwise `(-1, None)`.

    Parameters
    ----------
    haystack : list
        A list of dictionaries to search through.
    key : str
        The key to look for in each dictionary.
    needle : any
        The value to match against the specified key.

    Returns
    -------
    tuple
          - If found: (index, dictionary item).
          - If not found: (-1, None).

    Examples
    --------
    >>> haystack = [
    ...     {'name': 'Tom', 'age': 10},
    ...     {'name': 'Mark', 'age': 5},
    ...     {'name': 'Pam', 'age': 7},
    ...     {'name': 'Dick', 'age': 12},
    ... ]
    >>> lookup_lod(haystack, 'name', 'Pam')
    (2, {'name': 'Pam', 'age': 7})

    >>> lookup_lod(haystack, 'name', 'Pamela')
    (-1, None)
    """
    for idx, item in enumerate(haystack):
        if isinstance(item, dict) and key in item and item[key] == needle:
            return idx, item
    return -1, None


# One bound of a range: an optional sign, digits with an optional decimal point, an
# optional exponent, and an optional percent sign.
_RANGE_ATOM = re.compile(r'^[+-]?(?:\d+\.?\d*|\.\d+)(?:[eE][+-]?\d+)?%?$')


def _parse_range_atom(atom, default):
    """Turns one bound of a range into a float, or raises `ValueError` if it is not a
    number. An empty bound is the omitted one and yields `default`.

    A trailing `%` is dropped: a percentage sign in a threshold repeats the unit of the
    value and carries nothing the comparison needs, so `90%:` means what `90:` means.
    Verified against monitoring-plugins 2.4.x, whose `lib/tests/test_utils.c` asserts
    the same for `1:12%`.

    Every bound is a float, never an int, because the reference implementation holds the
    whole range in C doubles and the value is a float here too. A bound kept as an exact
    Python int is compared exactly against a value that has already been rounded to a
    float, so `12345678901234567890` reads as greater than the very value it was written
    for and the caller alerts on it. Both sides have to be rounded the same way, which is
    what `lib/tests/test_utils.c` asserts for that bound.

    Deliberately stricter than the reference implementation, which reads a bound with
    `strtod()`: that takes the longest numeric prefix and silently answers 0 for a bound
    with no numeric prefix at all, so `1,5` becomes the threshold 1 and `abc` becomes 0.
    Guessing a number out of a typo gives an admin a threshold that alerts forever without
    saying why, so anything outside this grammar is refused and reported instead. The
    same refusal covers what Python would read but the range syntax does not define:
    `1_000`, `inf`, `nan`, `0x10`.
    """
    atom = atom.strip()
    if not atom:
        return default
    if not _RANGE_ATOM.match(atom):
        raise ValueError(f'{atom!r} is not a number')
    return float(atom.rstrip('%'))


def _value2float(value):
    """Reads the value of a threshold comparison as a `float`, or answers `None` when it
    is not a number the comparison can use.

    A value that is not numeric used to raise out of `match_range()` and reached the
    admin as a stack trace, the way a mistyped range once did. `None` raised as well,
    one type later, when it was compared against a bound.

    NaN is refused too, and it is the reason this is a single reader rather than a
    `try` around every conversion: every comparison against NaN is False, so a NaN
    value passed both bound checks and was reported as inside the range. A value the
    check could not read at all came out as OK.

    A trailing `%` is dropped, so a value of `90%` is compared like `90`, the way
    `_parse_range_atom()` reads a bound of `90%`.
    """
    if isinstance(value, (bytes, bytearray)):
        value = txt.to_text(value, errors='strict_or_latin1')
    if isinstance(value, str):
        value = value.replace('%', '').strip()
    try:
        value = float(value)
    except (TypeError, ValueError):
        return None
    return None if math.isnan(value) else value


def _parse_range(spec_):
    """
    Inspired by
    https://github.com/mpounsett/nagiosplugin/blob/master/nagiosplugin/range.py

    +--------+-------------------+-------------------+----------------+
    | -w, -c | OK if result is   | WARN/CRIT if      | returns        |
    +--------+-------------------+-------------------+----------------+
    | 10     | in (0..10)        | not in (0..10)    | (0, 10, False) |
    +--------+-------------------+-------------------+----------------+
    | -10:0  | in (-10..0)       | not in (-10..0)   | (-10, 0, False)|
    +--------+-------------------+-------------------+----------------+
    | 10:    | in (10..inf)      | not in (10..inf)  | (10, inf, F)   |
    +--------+-------------------+-------------------+----------------+
    | :      | in (0..inf)       | not in (0..inf)   | (0, inf, False)|
    +--------+-------------------+-------------------+----------------+
    | ~:10   | in (-inf..10)     | not in (-inf..10) | (-inf, 10, F)  |
    +--------+-------------------+-------------------+----------------+
    | 10:20  | in (10..20)       | not in (10..20)   | (10, 20, False)|
    +--------+-------------------+-------------------+----------------+
    | @10:20 | not in (10..20)   | in 10..20         | (10, 20, True) |
    +--------+-------------------+-------------------+----------------+
    | @~:20  | not in (-inf..20) | in (-inf..20)     | (-inf, 20, T)  |
    +--------+-------------------+-------------------+----------------+
    | @      | not in (0..inf)   | in (0..inf)       | (0, inf, True) |
    +--------+-------------------+-------------------+----------------+
    """
    if spec_ is None or str(spec_).lower() == 'none':
        return True, None

    if not isinstance(spec_, str):
        spec_ = str(spec_)

    invert = spec_.startswith('@')
    if invert:
        spec_ = spec_[1:]

    if ':' in spec_:
        try:
            start, end = spec_.split(':')
        except ValueError:
            return False, 'Not using range definition correctly'
    else:
        start, end = '', spec_

    try:
        start = float('-inf') if start.strip() == '~' else _parse_range_atom(start, 0)
        end = _parse_range_atom(end, float('inf'))
    except ValueError:
        # An unparseable bound is reported the way an unparseable range has always been
        # reported, as a message the caller turns into UNKNOWN. Letting the `ValueError`
        # escape instead hands the admin a Python traceback in place of the threshold
        # they mistyped.
        return False, 'Range format incorrect'

    if start > end:
        return (
            False,
            f'Start {start:g} must not be greater than end {end:g}',
        )
    return True, (start, end, invert)


def match_range(value, spec):
    """
    Decides if `value` is inside or outside the Nagios threshold
    specification.

    Parameters
    ----------
    value : int or float or str
        The numeric value to check.
    spec : str
        The Nagios range specification string.

    Returns
    -------
    tuple of (bool, bool or str)
        - On a `spec` that parses: (True, matched), where `matched` is True if `value` is
          inside the bounds for a non-inverted `spec`, or outside the bounds for an
          inverted one. Callers alert when `matched` is False.
        - On a `spec` that does not parse: (False, reason). Callers turn this into UNKNOWN.
        - On a `value` that is not a number: (False, reason), the same way.

    Notes
    -----
    - Both bounds are inclusive.
    - A trailing `%` on a bound is ignored, so `90:` and `90%:` mean the same.

    Examples
    --------
    >>> match_range(15, '10')  # outside 0..10
    (True, False)

    >>> match_range(5, '10')  # inside 0..10
    (True, True)

    >>> match_range(15, '-10')
    (False, 'Start 0 must not be greater than end -10')

    >>> match_range(15, '1,5')
    (False, 'Range format incorrect')

    >>> match_range('11.abc', '10')
    (False, "'11.abc' is not a number")

    >>> match_range(15, '10:')  # inside 10..inf
    (True, True)

    >>> match_range(15, ':')  # inside 0..inf
    (True, True)

    >>> match_range(15, '~:10')  # outside -inf..10
    (True, False)

    >>> match_range(15, '10:20')  # inside 10..20
    (True, True)

    >>> match_range(15, '@10:20')  # inside 10..20, and the range is inverted
    (True, False)

    >>> match_range(15, '@~:20')  # inside -inf..20, and the range is inverted
    (True, False)

    >>> match_range(15, '@')  # inside 0..inf, and the range is inverted
    (True, False)
    """
    if isinstance(spec, str):
        spec = spec.lstrip('\\')

    if spec is None or str(spec).lower() == 'none':
        return True, True

    success, result = _parse_range(spec)
    if not success:
        return success, result

    start, end, invert = result

    numeric_value = _value2float(value)
    if numeric_value is None:
        return False, f'{value!r} is not a number'
    value = numeric_value

    if value < start or value > end:
        return True, bool(invert)
    return True, not invert


def oao(msg, state=STATE_OK, perfdata='', always_ok=False, no_perfdata=False):
    """
    Over and Out (OaO)

    Print a sanitized result message with optional performance data and exit the script.

    This function formats and prints the message, appends performance data if provided,
    sanitizes sensitive information, replaces reserved `|` characters, and exits with the
    specified state code. Optionally, it can always exit with `STATE_OK` regardless of the given
    state.

    Parameters
    ----------
    msg : str
        The message to print. Will be stripped, sanitized, and processed.
    state : int, optional
        The exit code to use. Defaults to `STATE_OK`.
    perfdata : str, optional
        Performance data to append after a `|` separator.
        Defaults to an empty string (no performance data).
    always_ok : bool, optional
        If `True`, forces the exit code to `STATE_OK` regardless
        of the specified `state`. Defaults to `False`.
    no_perfdata : bool, optional
        If `True`, suppresses the performance data section
        entirely, printing only the message and preserving the exit code. Defaults to `False`.

    Returns
    -------
    None
        This function does not return; it terminates the script via `sys.exit()`.

    Notes
    -----
    - Any `|` characters inside the message are replaced with `!`, the character being
      reserved as the performance data separator of the Monitoring Plugins output format.
    - A `<` that would open an HTML tag is replaced by `&lt;`, so a web interface cannot
      mistake the output for markup. Everything else is left as it is: `<= 10`,
      `< 5.3.2` and `echo 1 > /proc/sys/...` reach the terminal exactly as written, and
      `&` and `>` are never touched. A web interface escapes those itself when it renders
      the output as plain text, which is the path this keeps the output on. Rendering it
      as HTML instead would drop the monospace formatting that tables depend on.
    - Sensitive information like passwords, tokens, and keys is automatically redacted.
    - `perfdata`, if provided, must follow the Monitoring Plugins specification for
      performance metrics.
    - `no_perfdata` only affects what is printed; the message and the exit code are unchanged, so
      alerting keeps working while trending data is dropped from the output.

    Examples
    --------
    >>> oao('Service is healthy', STATE_OK, 'load=0.12;1.00;5.00', always_ok=False)
    Service is healthy|load=0.12;1.00;5.00
    (and exits with code 0)

    >>> oao('password=linuxfabrik found!', STATE_CRIT)
    password=****** found!
    (and exits with code 2)

    """
    # Normalize line endings to LF. Output captured on Windows (or read from a
    # file or HTTP response) can carry CRLF or stray CR, which a web UI showing
    # the output with `white-space: pre-wrap` would render as an extra line break.
    msg = msg.replace('\r\n', '\n').replace('\r', '\n')
    msg = _escape_tag_start(txt.sanitize_sensitive_data(msg.strip())).replace('|', '!')
    if always_ok and msg:
        # Instead of splitlines(), we just split('\n', 1), so only first line is touched.
        parts = msg.split('\n', 1)
        parts[0] += ' (always ok)'
        msg = '\n'.join(parts)
    print(f'{msg}|{perfdata.strip()}' if perfdata and not no_perfdata else msg)
    sys.exit(STATE_OK if always_ok else state)


def _bound2txt(bound, fmt):
    """Formats one bound of a range for a human reader.

    Infinity keeps its name whatever `fmt` does with it, an integral bound loses the
    `.0` that every bound carries as a float, and a `fmt` that answers with nothing
    falls back to the plain number instead of dropping the bound out of the sentence.
    """
    if bound == float('inf'):
        return 'inf'
    if bound == float('-inf'):
        return '-inf'
    plain = str(int(bound)) if float(bound).is_integer() else str(bound)
    if fmt is None:
        return plain
    formatted = fmt(bound)
    return str(formatted) if formatted else plain


def range2txt(spec, value=None, value_name='value', fmt=None, view='alert'):
    """
    Puts a Nagios threshold range, and optionally the value compared against it, into
    the wording of THRESHOLDS.md, so a message can say what was compared instead of
    repeating the range syntax at the admin.

    What is described is the condition, not where the value lies: by default the
    `WARN/CRIT if` column of THRESHOLDS.md, so a consumer that alerts can name what it
    alerted on. `view='ok'` gives the `OK if result is` column instead.

    Parameters
    ----------
    spec : str
        The Nagios range specification string, as `match_range()` takes
        it. Note the argument order: the range comes first here, the value is optional.
    value : int or float or str, optional
        The value that was compared.
        Without it, only the condition is returned.
    value_name : str, optional
        What to call the value in the text. Defaults to
        `value`.
    fmt : callable, optional
        Turns a number into its human-readable form, for
        example `human.seconds2human` or `human.bytes2human`. Without it, the numbers are
        printed as they are.
    view : str, optional
        `alert` for the condition that alerts, `ok` for the
        condition that does not. Defaults to `alert`.

    Returns
    -------
    tuple of (bool, str)
        - On success: (True, text), where `text` is `not in (start..end)`, or
          `name=value not in (start..end)` when a `value` was given. Empty for a `spec`
          of `None`, which is a threshold that was never set.
        - On a `spec` that does not parse, a `value` that is not a number, or an unknown
          `view`: (False, reason). Callers turn this into UNKNOWN, the same way they do
          for `match_range()`.

    Notes
    -----
    - Both bounds are inclusive, and a trailing `%` on a bound or on the value is
      dropped, the way `match_range()` reads them.
    - The state marker is left to the caller, who can pick its wording with
      `state2str()`: `f'{text}{state2str(state, prefix=" ")}'`.
    - An inverted range alerts inside its bounds, so `10:20` and `@10:20` describe
      opposite conditions and never read alike.

    Examples
    --------
    >>> range2txt('10')
    (True, 'not in (0..10)')

    >>> range2txt('10', view='ok')
    (True, 'in (0..10)')

    >>> range2txt('~:10')
    (True, 'not in (-inf..10)')

    >>> range2txt('10:20', value=15, value_name='age')
    (True, 'age=15 not in (10..20)')

    >>> range2txt('@10:20', value=15, value_name='age')
    (True, 'age=15 in (10..20)')

    >>> range2txt('172800', value=259200, value_name='age', fmt=human.seconds2human)
    (True, 'age=3D not in (0s..2D)')

    >>> range2txt('10:20', value='11.abc')
    (False, "'11.abc' is not a number")

    >>> range2txt('1,5')
    (False, 'Range format incorrect')

    >>> range2txt(None, value=11, value_name='age')
    (True, '')
    """
    if view not in ('alert', 'ok'):
        return False, f'Unknown view {view!r}'

    if spec is None or str(spec).lower() == 'none':
        return True, ''

    success, result = _parse_range(spec)
    if not success:
        return False, result

    start, end, invert = result
    rng = f'({_bound2txt(start, fmt)}..{_bound2txt(end, fmt)})'
    # THRESHOLDS.md tabulates both columns: a plain range alerts outside its bounds,
    # an inverted one inside them, and the OK column is the other one. Rendering the
    # condition rather than where the value happens to lie is what keeps `10:20` and
    # `@10:20` apart, which the bounds alone cannot do.
    alerts_inside = invert
    if view == 'alert':
        condition = 'in' if alerts_inside else 'not in'
    else:
        condition = 'not in' if alerts_inside else 'in'

    if value is None:
        return True, f'{condition} {rng}'

    numeric_value = _value2float(value)
    if numeric_value is None:
        return False, f'{value!r} is not a number'

    return True, f'{value_name}={_bound2txt(numeric_value, fmt)} {condition} {rng}'


# One duration token such as `3d`, `12h`, `2W` or `1M`. The unit letters are the ones
# `human.human2seconds()` knows; listing fewer here would let a valid duration fall
# through and be read as a threshold range instead, which is silently wrong rather
# than an error.
_DURATION_ATOM = re.compile(r'^\d+(\.\d+)?[YMWwDdhms]$')


def resolve_time_threshold(threshold, total_seconds):
    """
    Normalize a "time left" threshold into a Nagios range expressed in days.

    A consumer that alerts on how much of a lifetime is left - a certificate, a
    licence, a token, a support contract - wants to let the operator say that in
    whichever way suits the subject: an absolute number of days, a share of the total
    lifetime, or a duration. This turns all three into the one form `get_state()`
    understands, so the comparison and the performance data stay in days throughout.

    Accepted forms:

    - empty: no threshold, passes through as empty
    - `N%`: N percent of `total_seconds`, converted to days
    - a single duration token (`3d`, `12h`, `2W`, `1M`): that duration in days
    - anything else: already a Nagios range in days (`14:`, `@5:10`), passed through

    A percentage and a duration both become a `<n>:` range, which alerts when *fewer*
    than `n` days are left. That is the direction "time left" runs in, and it is why
    the two shorthands cannot express the other one; an operator who needs that writes
    the range out.

    Parameters
    ----------
    threshold : str
        The threshold as the operator wrote it.
    total_seconds : float
        The whole lifetime the percentage form refers to.
        Only read for that form.

    Returns
    -------
    str
        A Nagios range in days, ready for `get_state(..., _operator='range')`.

    Notes
    -----
    - A percentage that does not parse as a number is passed through unchanged, so it
      reaches the range parser and is reported there rather than being read as zero.

    Examples
    --------
    >>> resolve_time_threshold('14:', 7776000)
    '14:'

    >>> resolve_time_threshold('10%', 7776000)
    '9:'

    >>> resolve_time_threshold('12h', 7776000)
    '0.5:'
    """
    threshold = str(threshold).strip()
    if not threshold:
        return ''
    if threshold.endswith('%'):
        try:
            pct = float(threshold[:-1])
        except ValueError:
            return threshold
        # `:g` drops trailing zeros, so 25% of 60 days reads "15:", not "15.000000:"
        return f'{pct / 100.0 * total_seconds / 86400.0:g}:'
    if _DURATION_ATOM.match(threshold):
        return f'{human.human2seconds(threshold) / 86400.0:g}:'
    return threshold


def smartcast(value):
    """
    Returns the value converted to `float` if possible, else to `str`, else returns
    the uncasted value.

    Parameters
    ----------
    value : any
        The value to attempt to cast.

    Returns
    -------
    float, str, or any
        - If convertible to `float`, returns a `float`.
        - If not, tries to convert to `str`.
        - If neither succeeds, returns the original value unchanged.

    Examples
    --------
    >>> smartcast('3.14')
    3.14

    >>> smartcast(42)
    42.0

    >>> smartcast('hello')
    'hello'
    """
    try:
        return float(value)
    except (ValueError, TypeError):
        try:
            return str(value)
        except (ValueError, TypeError):
            return value


def sort(array, reverse=True, sort_by_key=False):
    """
    Sort a dict, list, or tuple.

    - If dict: sorts by values (default) or keys (if sort_by_key=True).
    - If list or tuple: sorts the elements.
    - Other types: returned unchanged.

    When a dictionary is provided, this function returns a list of (key, value)
    tuples sorted based on the specified criteria:
      - If `sort_by_key` is False (default), the dictionary items are sorted by their values.
      - If `sort_by_key` is True, the items are sorted by their keys (compared case-insensitively).

    The sort order is descending by default (`reverse=True`).
    If the input is not a dictionary, the original input is returned unmodified.

    Parameters
    ----------
    array : dict or any
        The dictionary to be sorted. If not a dictionary, the input is
        returned as is.
    reverse : bool, optional
        If True, sort in descending order; if False, ascending.
        Defaults to True.
    sort_by_key : bool, optional
        If True, sort by dictionary keys; if False, by values.
        Defaults to False.

    Returns
    -------
    list or any
        A list of sorted (key, value) tuples if a dictionary is provided,
        otherwise the original input.

    Examples
    --------
    >>> sort({'a': 2, 'b': 1})
    [('a', 2), ('b', 1)]

    >>> sort({'a': 2, 'b': 1}, reverse=False)
    [('b', 1), ('a', 2)]

    >>> sort({'a': 2, 'B': 1}, sort_by_key=True)
    [('B', 1), ('a', 2)]
    """
    if isinstance(array, dict):
        keyfunc = (lambda x: str(x[0]).lower()) if sort_by_key else (lambda x: x[1])
        return sorted(array.items(), key=keyfunc, reverse=reverse)

    if isinstance(array, (list, tuple)):
        return sorted(array, reverse=reverse)

    return array


def state2str(state, empty_ok=True, prefix='', suffix=''):
    """
    Return the state's string representation.

    The square brackets around the state cause Icinga Web 2 to color the state.

    Parameters
    ----------
    state : int
        The state code (e.g., 0, 1, 2, 3).
    empty_ok : bool, optional
        If True and the state is OK (0), return an empty string.
        Defaults to True.
    prefix : str, optional
        A prefix string to prepend to the result. Defaults to ''.
    suffix : str, optional
        A suffix string to append to the result. Defaults to ''.

    Returns
    -------
    str
        A formatted string representation of the state.

    Examples
    --------
    >>> state2str(2)
    '[CRITICAL]'

    >>> state2str(0)
    ''

    >>> state2str(0, empty_ok=False)
    '[OK]'

    >>> state2str(0, empty_ok=False, suffix=' ')
    '[OK] '

    >>> state2str(0, empty_ok=False, prefix=' (', suffix=')')
    ' ([OK])'
    """
    state = int(state)
    text = _STATE_NAMES.get(state, str(state))

    if state == STATE_OK and empty_ok:
        return ''
    return f'{prefix}{text}{suffix}'


def str2bool(s):
    """
    Return True or False depending on the given string.

    Parameters
    ----------
    s : str
        The input string to evaluate.

    Returns
    -------
    bool
        True if the string is not empty and not equal to "false" (case-insensitive),
        otherwise False.

    Examples
    --------
    >>> str2bool('')
    False

    >>> str2bool('false')
    False

    >>> str2bool('FalSE')
    False

    >>> str2bool('true')
    True

    >>> str2bool('Linuxfabrik')
    True

    >>> str2bool('0')
    True

    >>> str2bool('1')
    True
    """
    return bool(s) and s.lower() != 'false'


def str2state(string, ignore_error=True):
    """
    Return the numeric state based on a (case-insensitive) string.

    Matches up to the first four characters of the input string.

    Parameters
    ----------
    string : str
        The input string to match against known states.
    ignore_error : bool, optional
        If True, unrecognized strings return `STATE_UNKNOWN`.
        If False, unrecognized strings return None. Defaults to True.

    Returns
    -------
    int or None
        - The numeric state code (`STATE_OK`, `STATE_WARN`, `STATE_CRIT`, `STATE_UNKNOWN`) if
          recognized.
        - Otherwise, `STATE_UNKNOWN` or None, depending on `ignore_error`.

    Examples
    --------
    >>> str2state('ok')
    0

    >>> str2state('okidoki')
    3

    >>> str2state('okidoki', ignore_error=False)
    None

    >>> str2state('war')
    3

    >>> str2state('warn')
    1

    >>> str2state('Warnung')
    1

    >>> str2state('CrITical')
    2

    >>> str2state('UNKNOWN')
    3

    >>> str2state('gobbledygook')
    3

    >>> str2state('gobbledygook', ignore_error=False)
    None
    """
    lookup = {
        'ok': STATE_OK,
        'warn': STATE_WARN,
        'crit': STATE_CRIT,
        'unkn': STATE_UNKNOWN,
    }
    return lookup.get(str(string).lower()[:4], STATE_UNKNOWN if ignore_error else None)


def sum_dict(dict1, dict2):
    """
    Sum up two dictionaries, possibly with different keys.

    Only numeric values are considered for summation; non-numeric values are ignored.

    Parameters
    ----------
    dict1 : dict
        The first dictionary to sum.
    dict2 : dict
        The second dictionary to sum.

    Returns
    -------
    dict
        A new dictionary with summed numeric values by key.

    Examples
    --------
    >>> sum_dict({'in': 100, 'out': 10}, {'in': 50, 'error': 5, 'uuid': '1234-xyz'})
    {'in': 150, 'out': 10, 'error': 5}
    """
    return sum_lod([dict1, dict2])


def sum_lod(mylist):
    """
    Sum up a list of (simple 1-dimensional) dictionary items.

    Only numeric values are considered for summation; non-numeric values are ignored.

    Parameters
    ----------
    mylist : list
        A list of dictionaries to sum.

    Returns
    -------
    dict
        A dictionary with summed numeric values by key.

    Examples
    --------
    >>> sum_lod(
    ...     [
    ...         {'in': 100, 'out': 10},
    ...         {'in': 50, 'out': 20},
    ...         {'error': 5, 'uuid': '1234-xyz'},
    ...     ]
    ... )
    {'in': 150, 'out': 30, 'error': 5}
    """
    total = {}

    for d in mylist:
        for key, value in d.items():
            if is_numeric(value):
                total[key] = total.get(key, 0) + value

    return total


def verbose(enabled, msg):
    """
    Print a progress message, but only when verbose output is switched on.

    Long-running consumers (a scan over a subnet, an external tool that runs for
    minutes) otherwise give no sign of life while they work. Guarding every such message
    with an `if` at the call site is what this replaces, so the condition and the
    destination are decided in one place.

    Output goes to STDOUT, never to STDERR, because the monitoring protocol only
    captures STDOUT. The message therefore becomes part of the result and is meant
    for interactive debugging, not for a scheduled run.

    The message is redacted and escaped the same way `coe()`, `cu()` and `oao()` treat
    theirs. Progress messages routinely carry the command that was run or the error a
    helper returned, and either can contain a credential the caller never meant to print,
    a `|` that would hand the rest of the line to the monitoring server as performance
    data, or a tag a web interface would render.

    Parameters
    ----------
    enabled : bool
        Whether verbose output is switched on. Pass the value of the
        consumer's own verbose switch.
    msg : str
        The message to print.

    Returns
    -------
    None

    Examples
    --------
    >>> verbose(args.VERBOSE, f'Scanning {url}...')
    """
    if enabled:
        msg = txt.sanitize_sensitive_data(str(msg))
        print(_escape_tag_start(msg).replace('|', '!'))