telemetry-cli 1.0.0__py3-none-any.whl

telemetry_cli/__init__.py

@@ -0,0 +1,8 @@
+"""telemetry-cli: command-line tools for binary telemetry."""
+
+from importlib.metadata import PackageNotFoundError, version
+
+try:
+    __version__ = version("telemetry-cli")
+except PackageNotFoundError:  # running from a source tree without installing
+    __version__ = "0+unknown"

telemetry_cli/_cli.py

@@ -0,0 +1,18 @@
+"""Helpers shared by the command-line programs."""
+
+from __future__ import annotations
+
+import contextlib
+import os
+import sys
+
+
+def broken_pipe(stdout) -> int:
+    """Handle stdout closing early (``tool | head``): exit quietly, with status 0.
+
+    Python would otherwise report the error when it flushes stdout at exit.
+    """
+    if stdout is sys.stdout.buffer:
+        with contextlib.suppress(OSError, ValueError):
+            os.dup2(os.open(os.devnull, os.O_WRONLY), sys.stdout.fileno())
+    return 0

telemetry_cli/_getopt.py

@@ -0,0 +1,114 @@
+"""Command-line options as Perl's Getopt::Long read them (with its default settings).
+
+recs, recl and tgen used Getopt::Long, so their options behave like this:
+
+- an option starts with one or two dashes: ``-mml 4``, ``--mml=4``;
+- names are case-insensitive and can be shortened to any unique prefix
+  (``-ma`` for ``-max_reclen``);
+- a value comes after ``=`` or as the next argument, even one starting with a
+  dash (``-e -r`` sets ``e`` to ``-r``);
+- options and other arguments can be mixed; ``--`` ends the options, and a
+  lone ``-`` is an argument.
+
+Specs use Getopt::Long's syntax: ``"name|alias"`` for a flag, and ``=i``,
+``=f`` or ``=s`` for an integer, float or string value.
+
+Unlike the Perl tools, which printed a warning and carried on, a bad option is
+an error here.
+"""
+
+from __future__ import annotations
+
+import re
+from dataclasses import dataclass
+
+_INT = re.compile(r"^[-+]?\d+$")
+_FLOAT = re.compile(r"^[-+]?(?=\d|\.\d)\d*(\.\d*)?([eE][-+]?\d+)?$")
+
+
+class OptionError(ValueError):
+    pass
+
+
+@dataclass
+class _Spec:
+    key: str  # the first name, used as the result key
+    names: list[str]
+    kind: str | None  # None (a flag), "i", "f" or "s"
+
+
+def _parse_specs(specs: list[str]) -> list[_Spec]:
+    out = []
+    for spec in specs:
+        m = re.fullmatch(r"([\w|]+)(?:=([ifs]))?", spec)
+        if not m:
+            raise ValueError(f"bad option spec {spec!r}")
+        names = m.group(1).split("|")
+        out.append(_Spec(names[0], names, m.group(2)))
+    return out
+
+
+def getoptions(argv: list[str], specs: list[str]) -> tuple[dict, list[str]]:
+    """Parse argv. Returns (options by their first name, remaining arguments)."""
+    table = _parse_specs(specs)
+    opts: dict = {}
+    args: list[str] = []
+    i = 0
+    while i < len(argv):
+        a = argv[i]
+        i += 1
+        if a == "--":
+            args += argv[i:]
+            break
+        if not a.startswith("-") or a == "-":
+            args.append(a)
+            continue
+        body = a[2:] if a.startswith("--") else a[1:]
+        name, eq, value = body.partition("=")
+        spec, name = _find(table, name)
+        if spec.kind is None:
+            if eq:
+                raise OptionError(f"Option {name} does not take an argument")
+            opts[spec.key] = 1
+            continue
+        if not eq:
+            if i >= len(argv):
+                raise OptionError(f"Option {name} requires an argument")
+            value = argv[i]
+            i += 1
+        elif value == "":
+            raise OptionError(f"Option {name} requires an argument")
+        opts[spec.key] = _convert(spec, name, value)
+    return opts, args
+
+
+def _find(table: list[_Spec], name: str) -> tuple[_Spec, str]:
+    """The option a (possibly shortened) name refers to, and its full name."""
+    low = name.lower()
+    for s in table:
+        for n in s.names:
+            if n.lower() == low:
+                return s, n
+    matches: dict[str, tuple[_Spec, str]] = {}
+    for s in table:
+        for n in s.names:
+            if n.lower().startswith(low) and low:
+                matches.setdefault(s.key, (s, n))
+    if len(matches) == 1:
+        return next(iter(matches.values()))
+    if not matches:
+        raise OptionError(f"Unknown option: {low}")
+    names = ", ".join(sorted(n for _, n in matches.values()))
+    raise OptionError(f"Option {name} is ambiguous ({names})")
+
+
+def _convert(spec: _Spec, name: str, value: str):
+    if spec.kind == "i":
+        if not _INT.match(value):
+            raise OptionError(f'Value "{value}" invalid for option {name} (number expected)')
+        return int(value)
+    if spec.kind == "f":
+        if not _FLOAT.match(value):
+            raise OptionError(f'Value "{value}" invalid for option {name} (real number expected)')
+        return float(value)
+    return value

telemetry_cli/_msg.py

@@ -0,0 +1,39 @@
+"""Tagged diagnostic messages, replacing the Perl Util::Msg module.
+
+Util::Msg printed each message as ``TAG text``, with ``NOTE`` as the default
+tag, and could hide or select tags. recl's result lines (``RESULT 48``,
+``CORR 97.5``) use this format, so it is part of recl's output.
+"""
+
+from __future__ import annotations
+
+import sys
+from typing import TextIO
+
+
+class Messenger:
+    """Print ``TAG text`` lines to a stream, optionally filtering by tag."""
+
+    def __init__(
+        self,
+        stream: TextIO | None = None,
+        *,
+        hide: set[str] | frozenset[str] = frozenset(),
+        default_tag: str = "NOTE",
+    ):
+        self._stream = stream
+        self.hide = set(hide)
+        self.default_tag = default_tag
+        self.counts: dict[str, int] = {}
+
+    @property
+    def stream(self) -> TextIO:
+        # Look up sys.stderr at call time, so pytest's capsys sees the output.
+        return self._stream if self._stream is not None else sys.stderr
+
+    def __call__(self, text: object = "", tag: str | None = None) -> None:
+        tag = tag or self.default_tag
+        if tag in self.hide:
+            return
+        self.counts[tag] = self.counts.get(tag, 0) + 1
+        print(f"{tag} {text}", file=self.stream)

telemetry_cli/_pack.py

@@ -0,0 +1,183 @@
+"""A subset of Perl's pack/unpack, built on struct.
+
+tgen command files give their field types as Perl pack templates ('L', 'a10',
+'C256', 'd2'), and pick's data types map onto the same letters. This module
+reproduces Perl's behavior for the letters those tools use:
+
+    c C       8-bit signed / unsigned
+    s S       16-bit signed / unsigned
+    l L i I   32-bit signed / unsigned
+    q Q       64-bit signed / unsigned
+    n N       16 / 32-bit unsigned, big-endian
+    v V       16 / 32-bit unsigned, little-endian
+    f d       single / double float
+    a A Z     byte strings: null-padded, space-padded, null-terminated
+    x         a null byte
+
+Each letter can take a repeat count (``C4``) or ``*``, and the integer and
+float letters wider than a byte take a ``<`` or ``>`` byte-order modifier. Without a modifier
+the byte order is native, as in Perl.
+
+As in Perl, integers are truncated toward zero and wrap to the field width, so
+``pack('C', 257)`` is ``b'\\x01'`` and ``pack('L', -1)`` is ``b'\\xff\\xff\\xff\\xff'``.
+Missing values pack as zero (or as empty strings for a/A/Z).
+"""
+
+from __future__ import annotations
+
+import math
+import re
+import struct
+import sys
+
+from ._perl import numify as _to_number
+
+# letter -> (struct code, size in bytes, signed?)  for the integer letters
+_INTS = {
+    "c": ("b", 1, True),
+    "C": ("B", 1, False),
+    "s": ("h", 2, True),
+    "S": ("H", 2, False),
+    "l": ("i", 4, True),
+    "L": ("I", 4, False),
+    "i": ("i", 4, True),
+    "I": ("I", 4, False),
+    "q": ("q", 8, True),
+    "Q": ("Q", 8, False),
+    "n": ("H", 2, False),
+    "N": ("I", 4, False),
+    "v": ("H", 2, False),
+    "V": ("I", 4, False),
+}
+_FIXED_ORDER = {"n": ">", "N": ">", "v": "<", "V": "<"}
+_FLOATS = {"f": "f", "d": "d"}
+_STRINGS = "aAZ"
+
+_ITEM = re.compile(r"\s*([cCsSlLiIqQnNvVfdaAZx])([<>])?(\*|\d+)?\s*")
+NATIVE = "<" if sys.byteorder == "little" else ">"
+
+
+class PackError(ValueError):
+    """A template this module can't handle."""
+
+
+def parse(template: str) -> list[tuple[str, str, int | None]]:
+    """Split a template into (letter, byte order, count) items.
+
+    The count is None when omitted and -1 for ``*``.
+    """
+    items = []
+    pos = 0
+    while pos < len(template):
+        m = _ITEM.match(template, pos)
+        if not m or m.end() == pos:
+            if template[pos:].strip() == "":
+                break
+            raise PackError(f"unsupported pack template {template!r} at {template[pos:]!r}")
+        letter, order, count = m.groups()
+        if order and (letter in _STRINGS or letter in _FIXED_ORDER or letter in "cCx"):
+            raise PackError(f"'{order}' is not allowed after '{letter}' in {template!r}")
+        order = _FIXED_ORDER.get(letter, order or NATIVE)
+        n = None if count is None else (-1 if count == "*" else int(count))
+        items.append((letter, order, n))
+        pos = m.end()
+    return items
+
+
+def _to_int(v, size: int, signed: bool) -> int:
+    x = _to_number(v)
+    if isinstance(x, float):
+        x = 0 if math.isnan(x) else (int(x) if math.isfinite(x) else (-1 if x < 0 else 2**64 - 1))
+    bits = 8 * size
+    x &= (1 << bits) - 1
+    if signed and x >= 1 << (bits - 1):
+        x -= 1 << bits
+    return x
+
+
+def _to_bytes(v) -> bytes:
+    if v is None:
+        return b""
+    if isinstance(v, (bytes, bytearray)):
+        return bytes(v)
+    if isinstance(v, float) and v.is_integer():
+        v = int(v)
+    return str(v).encode("latin-1")
+
+
+def pack(template: str, *values) -> bytes:
+    """Pack values like Perl's pack(template, values)."""
+    out = bytearray()
+    vals = list(values)
+    i = 0
+
+    def take():
+        nonlocal i
+        v = vals[i] if i < len(vals) else None
+        i += 1
+        return v
+
+    for letter, order, count in parse(template):
+        if letter == "x":
+            out += b"\0" * (1 if count is None else max(count, 0))
+        elif letter in _STRINGS:
+            s = _to_bytes(take())
+            if count == -1:
+                out += s + (b"\0" if letter == "Z" else b"")
+            else:
+                n = 1 if count is None else count
+                pad = b" " if letter == "A" else b"\0"
+                if letter == "Z" and n > 0:
+                    s = s[: n - 1]
+                out += s[:n].ljust(n, pad)
+        else:
+            reps = len(vals) - i if count == -1 else (1 if count is None else count)
+            for _ in range(max(reps, 0)):
+                v = take()
+                if letter in _FLOATS:
+                    x = float(_to_number(0 if v is None else v))
+                    out += struct.pack(order + _FLOATS[letter], x)
+                else:
+                    code, size, signed = _INTS[letter]
+                    out += struct.pack(order + code, _to_int(0 if v is None else v, size, signed))
+    return bytes(out)
+
+
+def unpack(template: str, data: bytes) -> tuple:
+    """Unpack data like Perl's unpack(template, data).
+
+    Strings come back as bytes. Like Perl, unpacking stops quietly when the
+    data run out.
+    """
+    out = []
+    pos = 0
+    for letter, order, count in parse(template):
+        if letter == "x":
+            pos += 1 if count is None else max(count, 0)
+        elif letter in _STRINGS:
+            n = len(data) - pos if count == -1 else (1 if count is None else count)
+            s = data[pos : pos + n]
+            pos += len(s)
+            if letter == "A":
+                s = s.rstrip(b" \0\t\n\r\f")
+            elif letter == "Z":
+                s = s.split(b"\0", 1)[0]
+            out.append(s)
+        else:
+            if letter in _FLOATS:
+                fmt, size = order + _FLOATS[letter], struct.calcsize(_FLOATS[letter])
+            else:
+                code, size, _ = _INTS[letter]
+                fmt = order + code
+            reps = (len(data) - pos) // size if count == -1 else (1 if count is None else count)
+            for _ in range(reps):
+                if pos + size > len(data):
+                    break
+                out.append(struct.unpack_from(fmt, data, pos)[0])
+                pos += size
+    return tuple(out)
+
+
+def calcsize(template: str) -> int:
+    """Bytes produced by a template with fixed counts (no ``*``)."""
+    return len(pack(template))

telemetry_cli/_perl.py

@@ -0,0 +1,183 @@
+"""Small pieces of Perl semantics that the ported tools' output depends on.
+
+- numify: Perl's numeric value of a string (leading number, else 0)
+- to_iv / to_uv: Perl's conversion of a number to a signed / unsigned 64-bit
+  integer, as used by printf's %d, %u, %x and %o
+- sprintf: printf for the conversions pick uses, including Perl's spelling of
+  infinities and NaN ("Inf", "-Inf", "NaN")
+- substr: Perl's substr, which counts negative offsets from the end
+- truthy: Perl's idea of a true string ("" and "0" are false)
+- perl_str: a value as Perl prints it (floats with 15 significant digits)
+"""
+
+from __future__ import annotations
+
+import math
+import re
+
+_NUMBER = re.compile(
+    r"\s*([+-]?)(?:(inf(?:inity)?|nan)|(\d+\.?\d*(?:[eE][+-]?\d+)?|\.\d+(?:[eE][+-]?\d+)?))",
+    re.IGNORECASE,
+)
+IV_MIN, IV_MAX, UV_MAX = -(2**63), 2**63 - 1, 2**64 - 1
+
+
+def numify(v) -> int | float:
+    """Perl's numeric value of v. None (undef) and non-numeric strings are 0.
+
+    Handles ordinary numeric strings, "inf"/"nan", and Perl's odd reading of a
+    leading sign followed by another signed number ("--1" is 1, "- 1" is -1).
+    """
+    if v is None:
+        return 0
+    if isinstance(v, bool):
+        return int(v)
+    if isinstance(v, (int, float)):
+        return v
+    if isinstance(v, (bytes, bytearray)):
+        v = bytes(v).decode("latin-1")
+    m = _NUMBER.match(v)
+    if m:
+        return _number(m)
+    m = re.match(r"\s*([+-])\s*", v)
+    if m:
+        inner = _NUMBER.match(v, m.end())
+        if inner and not inner.group(0)[:1].isspace():
+            x = _number(inner)
+            return -x if m.group(1) == "-" else x
+    return 0
+
+
+def _number(m: re.Match) -> int | float:
+    sign, special, digits = m.groups()
+    if special:
+        x = math.inf if special[0] in "iI" else math.nan
+    elif any(c in digits for c in ".eE"):
+        x = float(digits)
+    else:
+        x = int(digits)
+    return -x if sign == "-" else x
+
+
+def to_iv(v) -> int:
+    """Perl's IV (signed 64-bit) value of a finite number."""
+    x = numify(v)
+    if isinstance(x, int):
+        if x < IV_MIN:
+            return IV_MIN
+        return x if x <= IV_MAX else min(x, UV_MAX) - 2**64
+    if x < IV_MIN:
+        return IV_MIN
+    if x < 2**63:
+        return int(x)
+    uv = UV_MAX if x >= 2**64 else int(x)  # Perl goes through UV here
+    return uv - 2**64
+
+
+def to_uv(v) -> int:
+    """Perl's UV (unsigned 64-bit) value of a finite number."""
+    x = numify(v)
+    if isinstance(x, int):
+        return min(x, UV_MAX) if x >= 0 else max(x, IV_MIN) & UV_MAX
+    if x < 0:
+        return to_iv(x) & UV_MAX
+    return UV_MAX if x >= 2**64 else int(x)
+
+
+def multiply(a, b) -> int | float:
+    """Perl's a * b: integer arithmetic when both are integer-valued (so -0.0 * 180 is 0)."""
+
+    def as_int(x):
+        x = numify(x)
+        if isinstance(x, float) and x.is_integer() and IV_MIN <= x <= UV_MAX:
+            return int(x)
+        return x
+
+    a, b = as_int(a), as_int(b)
+    if isinstance(a, int) and isinstance(b, int) and IV_MIN <= a * b <= UV_MAX:
+        return a * b
+    return float(a) * float(b)
+
+
+def _special(x) -> str | None:
+    """Perl's text for an infinity or NaN, else None."""
+    if isinstance(x, float) and not math.isfinite(x):
+        if math.isnan(x):
+            return "NaN"
+        return "Inf" if x > 0 else "-Inf"
+    return None
+
+
+_CONV = re.compile(r"%(-?)(0?)(\d*)(?:\.(\d+))?([dugGxosc%])")
+
+
+def sprintf(fmt: str, *args) -> str:
+    """Perl's sprintf for the flag/width/precision/conversion subset pick uses."""
+    it = iter(args)
+
+    def conv(m: re.Match) -> str:
+        left, zero, width, prec, c = m.groups()
+        if c == "%":
+            return "%"
+        v = next(it, None)
+        x = numify(v) if c != "s" else v
+        text = _special(x) if c != "s" else None
+        if text and c in "duxo" and isinstance(v, str) and not re.search("[a-zA-Z]{3}", v):
+            # Perl's integer conversions read a numeric string that overflows
+            # (like "1e400") as the largest integer, not as Inf
+            text = None
+        if text is not None:
+            w = int(width or 0)
+            return text.ljust(w) if left else text.rjust(w)
+        spec = f"%{left}{zero}{width}" + (f".{prec}" if prec is not None else "")
+        if c == "d":
+            return (spec + "d") % to_iv(x)
+        if c == "u":
+            return (spec + "d") % to_uv(x)
+        if c in "xo":
+            return (spec + c) % to_uv(x)
+        if c in "gG":
+            return (spec + c) % float(x)
+        if c == "c":
+            return (spec + "c") % chr(to_iv(x) & 0x10FFFF)
+        return (spec + "s") % ("" if v is None else v)
+
+    return _CONV.sub(conv, fmt)
+
+
+def substr(data: bytes, offset: int, length: int | None = None) -> bytes:
+    """Perl's substr(data, offset, length) for non-negative length.
+
+    A negative offset counts from the end; a start before the beginning is
+    clipped (so substr("abc", -5, 4) is "ab"). Past the end gives b"".
+    """
+    n = len(data)
+    start = n + offset if offset < 0 else offset
+    if start > n:
+        return b""
+    end = n if length is None else start + max(length, 0)
+    return data[max(start, 0) : max(min(end, n), 0)]
+
+
+def truthy(s) -> bool:
+    """Perl truth of a scalar: undef, "", "0" and 0 are false."""
+    if s is None:
+        return False
+    if isinstance(s, str):
+        return s not in ("", "0")
+    return bool(s)
+
+
+def perl_str(v) -> str:
+    """A value as Perl turns it into text: floats with 15 significant digits."""
+    if v is None:
+        return ""
+    if isinstance(v, bool):
+        return "1" if v else ""
+    if isinstance(v, float):
+        if v.is_integer() and abs(v) < 1e15:
+            return str(int(v))
+        return sprintf("%.15g", v)
+    if isinstance(v, bytes):
+        return v.decode("latin-1")
+    return str(v)

telemetry_cli/pick/__init__.py

@@ -0,0 +1 @@
+"""pick: extract and print fields from fixed-length binary records."""

telemetry_cli/pick/__main__.py

@@ -0,0 +1,7 @@
+"""Allow ``python -m telemetry_cli.pick``."""
+
+import sys
+
+from .cli import main
+
+sys.exit(main())