transcrypto 1.2.0__py3-none-any.whl → 1.4.0__py3-none-any.whl

transcrypto/base.py

@@ -7,23 +7,32 @@
 from __future__ import annotations
 
 import abc
+import argparse
 import base64
+import codecs
 import dataclasses
 # import datetime
+import enum
 import functools
 import hashlib
+import json
 import logging
 import math
 import os.path
 import pickle
 # import pdb
 import secrets
+import sys
 import time
-from typing import Any, Callable, final, MutableSequence, Protocol, runtime_checkable, Self, TypeVar
+from typing import Any, Callable, final, MutableSequence, Protocol, runtime_checkable
+from typing import Sequence, Self, TypeVar
+
+import numpy as np
+from scipy import stats  # type:ignore
 import zstandard
 
 __author__ = 'balparda@github.com'
-__version__ = '1.2.0'  # 2025-09-05, Fri
+__version__ = '1.4.0'  # 2026-01-13, Tue
 __version_tuple__: tuple[int, ...] = tuple(int(v) for v in __version__.split('.'))
 
 # MIN_TM = int(  # minimum allowed timestamp
@@ -41,15 +50,44 @@ EncodedToBytes: Callable[[str], bytes] = lambda e: base64.urlsafe_b64decode(e.en
 
 PadBytesTo: Callable[[bytes, int], bytes] = lambda b, i: b.rjust((i + 7) // 8, b'\x00')
 
+# SI prefix table, powers of 1000
+_SI_PREFIXES: dict[int, str] = {
+    -6: 'a',  # atto
+    -5: 'f',  # femto
+    -4: 'p',  # pico
+    -3: 'n',  # nano
+    -2: 'µ',  # micro (unicode U+00B5)
+    -1: 'm',  # milli
+    0: '',    # base
+    1: 'k',   # kilo
+    2: 'M',   # mega
+    3: 'G',   # giga
+    4: 'T',   # tera
+    5: 'P',   # peta
+    6: 'E',   # exa
+}
 
 # these control the pickling of data, do NOT ever change, or you will break all databases
 # <https://docs.python.org/3/library/pickle.html#pickle.DEFAULT_PROTOCOL>
 _PICKLE_PROTOCOL = 4  # protocol 4 available since python v3.8 # do NOT ever change!
+PickleGeneric: Callable[[Any], bytes] = lambda o: pickle.dumps(o, protocol=_PICKLE_PROTOCOL)
+UnpickleGeneric: Callable[[bytes], Any] = pickle.loads
+PickleJSON: Callable[[dict[str, Any]], bytes] = lambda d: json.dumps(
+    d, separators=(',', ':')).encode('utf-8')
+UnpickleJSON: Callable[[bytes], dict[str, Any]] = lambda b: json.loads(b.decode('utf-8'))
 _PICKLE_AAD = b'transcrypto.base.Serialize.1.0'  # do NOT ever change!
 # these help find compressed files, do NOT change unless zstandard changes
 _ZSTD_MAGIC_FRAME = 0xFD2FB528
 _ZSTD_MAGIC_SKIPPABLE_MIN = 0x184D2A50
 _ZSTD_MAGIC_SKIPPABLE_MAX = 0x184D2A5F
+# JSON
+_JSON_DATACLASS_TYPES: set[str] = {
+    # native support
+    'int', 'float', 'str', 'bool',
+    'list[int]', 'list[float]', 'list[str]', 'list[bool]',
+    # need conversion/encoding
+    'bytes',
+}
 
 
 class Error(Exception):
@@ -64,14 +102,18 @@ class CryptoError(Error):
   """Cryptographic exception (TransCrypto)."""
 
 
-def HumanizedBytes(inp_sz: int, /) -> str:  # pylint: disable=too-many-return-statements
+class ImplementationError(Error, NotImplementedError):
+  """This feature is not implemented yet (TransCrypto)."""
+
+
+def HumanizedBytes(inp_sz: int | float, /) -> str:  # pylint: disable=too-many-return-statements
   """Convert a byte count into a human-readable string using binary prefixes (powers of 1024).
 
   Scales the input size by powers of 1024, returning a value with the
   appropriate IEC binary unit suffix: `B`, `KiB`, `MiB`, `GiB`, `TiB`, `PiB`, `EiB`.
 
   Args:
-    inp_sz (int): Size in bytes. Must be a non-negative integer.
+    inp_sz (int | float): Size in bytes. Must be non-negative.
 
   Returns:
     str: Formatted size string with up to two decimal places for units above bytes.
@@ -100,72 +142,79 @@ def HumanizedBytes(inp_sz: int, /) -> str:  # pylint: disable=too-many-return-st
   if inp_sz < 0:
     raise InputError(f'input should be >=0 and got {inp_sz}')
   if inp_sz < 1024:
-    return f'{inp_sz} B'
+    return f'{inp_sz} B' if isinstance(inp_sz, int) else f'{inp_sz:0.3f} B'
   if inp_sz < 1024 * 1024:
-    return f'{(inp_sz / 1024):0.2f} KiB'
+    return f'{(inp_sz / 1024):0.3f} KiB'
   if inp_sz < 1024 * 1024 * 1024:
-    return f'{(inp_sz / (1024 * 1024)):0.2f} MiB'
+    return f'{(inp_sz / (1024 * 1024)):0.3f} MiB'
   if inp_sz < 1024 * 1024 * 1024 * 1024:
-    return f'{(inp_sz / (1024 * 1024 * 1024)):0.2f} GiB'
+    return f'{(inp_sz / (1024 * 1024 * 1024)):0.3f} GiB'
   if inp_sz < 1024 * 1024 * 1024 * 1024 * 1024:
-    return f'{(inp_sz / (1024 * 1024 * 1024 * 1024)):0.2f} TiB'
+    return f'{(inp_sz / (1024 * 1024 * 1024 * 1024)):0.3f} TiB'
   if inp_sz < 1024 * 1024 * 1024 * 1024 * 1024 * 1024:
-    return f'{(inp_sz / (1024 * 1024 * 1024 * 1024 * 1024)):0.2f} PiB'
-  return f'{(inp_sz / (1024 * 1024 * 1024 * 1024 * 1024 * 1024)):0.2f} EiB'
+    return f'{(inp_sz / (1024 * 1024 * 1024 * 1024 * 1024)):0.3f} PiB'
+  return f'{(inp_sz / (1024 * 1024 * 1024 * 1024 * 1024 * 1024)):0.3f} EiB'
 
 
-def HumanizedDecimal(inp_sz: int | float, unit: str = '', /) -> str:  # pylint: disable=too-many-return-statements
-  """Convert a numeric value into a human-readable string using metric prefixes (powers of 1000).
+def HumanizedDecimal(inp_sz: int | float, /, *, unit: str = '') -> str:
+  """Convert a numeric value into a human-readable string using SI metric prefixes.
 
   Scales the input value by powers of 1000, returning a value with the
-  appropriate SI metric unit prefix: `k`, `M`, `G`, `T`, `P`, `E`. The caller
-  can optionally specify a base unit (e.g., `'Hz'`, `'m'`).
-
-  Args:
-    inp_sz (int | float): Quantity to convert. Must be finite and non-negative.
-    unit (str, optional): Base unit to append to the result (e.g., `'Hz'`).
-        If given, it will be separated by a space for values <1000 and appended
-        without a space for scaled values.
-
-  Returns:
-    str: Formatted string with up to two decimal places for scaled values
-        and up to four decimal places for small floats.
-
-  Raises:
-    InputError: If `inp_sz` is negative or not finite.
+  appropriate SI unit prefix. Supports both large multiples (kilo, mega,
+  giga, … exa) and small sub-multiples (milli, micro, nano, pico, femto, atto).
 
   Notes:
-    - Uses decimal multiples: 1 k = 1000 units.
-    - Values <1000 are returned as-is (integer) or with four decimal places (float).
-    - Unit string is stripped of surrounding whitespace before use.
+    • Uses decimal multiples: 1 k = 1000 units, 1 m = 1/1000 units.
+    • Supported large prefixes: k, M, G, T, P, E.
+    • Supported small prefixes: m, µ, n, p, f, a.
+    • Unit string is stripped of surrounding whitespace before use.
+    • Zero is returned as '0' plus unit (no prefix).
 
   Examples:
     >>> HumanizedDecimal(950)
     '950'
     >>> HumanizedDecimal(1500)
     '1.50 k'
-    >>> HumanizedDecimal(1500, ' Hz ')
-    '1.50 kHz'
-    >>> HumanizedDecimal(0.123456, 'V')
-    '0.1235 V'
+    >>> HumanizedDecimal(0.123456, unit='V')
+    '123.456 mV'
+    >>> HumanizedDecimal(3.2e-7, unit='F')
+    '320.000 nF'
+    >>> HumanizedDecimal(9.14e18, unit='Hz')
+    '9.14 EHz'
+
+  Args:
+    inp_sz (int | float): Quantity to convert. Must be finite.
+    unit (str, optional): Base unit to append to the result (e.g., 'Hz', 'm').
+        If given, it will be separated by a space for unscaled values and
+        concatenated to the prefix for scaled values.
+
+  Returns:
+    str: Formatted string with a few decimal places
+
+  Raises:
+    InputError: If `inp_sz` is not finite.
   """
-  if not math.isfinite(inp_sz) or inp_sz < 0:
-    raise InputError(f'input should be >=0 and got {inp_sz} / {unit!r}')
+  if not math.isfinite(inp_sz):
+    raise InputError(f'input should finite; got {inp_sz!r}')
   unit = unit.strip()
-  if inp_sz < 1000:
-    return (f'{inp_sz:0.4f}{" " + unit if unit else ""}' if isinstance(inp_sz, float) else
-            f'{inp_sz}{" " + unit if unit else ""}')
-  if inp_sz < 1000 * 1000:
-    return f'{(inp_sz / 1000):0.2f} k{unit}'
-  if inp_sz < 1000 * 1000 * 1000:
-    return f'{(inp_sz / (1000 * 1000)):0.2f} M{unit}'
-  if inp_sz < 1000 * 1000 * 1000 * 1000:
-    return f'{(inp_sz / (1000 * 1000 * 1000)):0.2f} G{unit}'
-  if inp_sz < 1000 * 1000 * 1000 * 1000 * 1000:
-    return f'{(inp_sz / (1000 * 1000 * 1000 * 1000)):0.2f} T{unit}'
-  if inp_sz < 1000 * 1000 * 1000 * 1000 * 1000 * 1000:
-    return f'{(inp_sz / (1000 * 1000 * 1000 * 1000 * 1000)):0.2f} P{unit}'
-  return f'{(inp_sz / (1000 * 1000 * 1000 * 1000 * 1000 * 1000)):0.2f} E{unit}'
+  pad_unit: str = ' ' + unit if unit else ''
+  if inp_sz == 0:
+    return '0' + pad_unit
+  neg: str = '-' if inp_sz < 0 else ''
+  inp_sz = abs(inp_sz)
+  # Find exponent of 1000 that keeps value in [1, 1000)
+  exp: int
+  exp = int(math.floor(math.log10(abs(inp_sz)) / 3))
+  exp = max(min(exp, max(_SI_PREFIXES)), min(_SI_PREFIXES))  # clamp to supported range
+  if not exp:
+    # No scaling: use int or 4-decimal float
+    if isinstance(inp_sz, int) or inp_sz.is_integer():
+      return f'{neg}{int(inp_sz)}{pad_unit}'
+    return f'{neg}{inp_sz:0.3f}{pad_unit}'
+  # scaled
+  scaled: float = inp_sz / (1000 ** exp)
+  prefix: str = _SI_PREFIXES[exp]
+  return f'{neg}{scaled:0.3f} {prefix}{unit}'
 
 
 def HumanizedSeconds(inp_secs: int | float, /) -> str:  # pylint: disable=too-many-return-statements
@@ -183,11 +232,7 @@ def HumanizedSeconds(inp_secs: int | float, /) -> str:  # pylint: disable=too-ma
     inp_secs (int | float): Time interval in seconds. Must be finite and non-negative.
 
   Returns:
-    str: Human-readable string with the duration and unit. Precision depends
-        on the chosen unit:
-          - µs / ms: 3 decimal places
-          - seconds ≥1: 2 decimal places
-          - minutes, hours, days: 2 decimal places
+    str: Human-readable string with the duration and unit
 
   Raises:
     InputError: If `inp_secs` is negative or not finite.
@@ -217,19 +262,115 @@ def HumanizedSeconds(inp_secs: int | float, /) -> str:  # pylint: disable=too-ma
   if not math.isfinite(inp_secs) or inp_secs < 0:
     raise InputError(f'input should be >=0 and got {inp_secs}')
   if inp_secs == 0:
-    return '0.00 s'
+    return '0.000 s'
   inp_secs = float(inp_secs)
   if inp_secs < 0.001:
     return f'{inp_secs * 1000 * 1000:0.3f} µs'
   if inp_secs < 1:
     return f'{inp_secs * 1000:0.3f} ms'
   if inp_secs < 60:
-    return f'{inp_secs:0.2f} s'
+    return f'{inp_secs:0.3f} s'
   if inp_secs < 60 * 60:
-    return f'{(inp_secs / 60):0.2f} min'
+    return f'{(inp_secs / 60):0.3f} min'
   if inp_secs < 24 * 60 * 60:
-    return f'{(inp_secs / (60 * 60)):0.2f} h'
-  return f'{(inp_secs / (24 * 60 * 60)):0.2f} d'
+    return f'{(inp_secs / (60 * 60)):0.3f} h'
+  return f'{(inp_secs / (24 * 60 * 60)):0.3f} d'
+
+
+def MeasurementStats(
+    data: list[int | float], /, *,
+    confidence: float = 0.95) -> tuple[int, float, float, float, tuple[float, float], float]:
+  """Compute descriptive statistics for repeated measurements.
+
+  Given N ≥ 1 measurements, this function computes the sample mean, the
+  standard error of the mean (SEM), and the symmetric error estimate for
+  the chosen confidence interval using Student's t distribution.
+
+  Notes:
+    • If only one measurement is given, SEM and error are reported as +∞ and
+      the confidence interval is (-∞, +∞).
+    • This function assumes the underlying distribution is approximately
+      normal, or n is large enough for the Central Limit Theorem to apply.
+
+  Args:
+    data (list[int | float]): Sequence of numeric measurements.
+    confidence (float, optional): Confidence level for the interval, 0.5 <= confidence < 1;
+        defaults to 0.95 (95% confidence interval).
+
+  Returns:
+    tuple:
+      - n (int): number of measurements.
+      - mean (float): arithmetic mean of the data
+      - sem (float): standard error of the mean, sigma / √n
+      - error (float): half-width of the confidence interval (mean ± error)
+      - ci (tuple[float, float]): lower and upper confidence interval bounds
+      - confidence (float): the confidence level used
+
+  Raises:
+    InputError: if the input list is empty.
+  """
+  # test inputs
+  n: int = len(data)
+  if not n:
+    raise InputError('no data')
+  if not 0.5 <= confidence < 1.0:
+    raise InputError(f'invalid confidence: {confidence=}')
+  # solve trivial case
+  if n == 1:
+    return (n, float(data[0]), math.inf, math.inf, (-math.inf, math.inf), confidence)
+  # call scipy for the science data
+  np_data = np.array(data)
+  mean = np.mean(np_data)
+  sem = stats.sem(np_data)  # type:ignore
+  ci = stats.t.interval(confidence, n - 1, loc=mean, scale=sem)            # type:ignore
+  t_crit = stats.t.ppf((1.0 + confidence) / 2.0, n - 1)  # type:ignore
+  error = t_crit * sem  # half-width of the CI  # type:ignore
+  return (n, float(mean), float(sem), float(error), (float(ci[0]), float(ci[1])), confidence)  # type:ignore
+
+
+def HumanizedMeasurements(
+    data: list[int | float], /, *,
+    unit: str = '', parser: Callable[[float], str] | None = None,
+    clip_negative: bool = True, confidence: float = 0.95) -> str:
+  """Render measurement statistics as a human-readable string.
+
+  Uses `MeasurementStats()` to compute mean and uncertainty, and formats the
+  result with units, sample count, and confidence interval. Negative values
+  can optionally be clipped to zero and marked with a leading “*”.
+
+  Notes:
+    • For a single measurement, error is displayed as “± ?”.
+    • The output includes the number of samples (@n) and the confidence
+      interval unless a different confidence was requested upstream.
+
+  Args:
+    data (list[int | float]): Sequence of numeric measurements.
+    unit (str, optional): Unit of measurement to append, e.g. "ms" or "s".
+      Defaults to '' (no unit).
+    parser (Callable[[float], str] | None, optional): Custom float-to-string
+      formatter. If None, values are formatted with 3 decimal places.
+    clip_negative (bool, optional): If True (default), negative values are
+      clipped to 0.0 and prefixed with '*'.
+    confidence (float, optional): Confidence level for the interval, 0.5 <= confidence < 1;
+        defaults to 0.95 (95% confidence interval).
+
+  Returns:
+    str: A formatted summary string, e.g.: '9.720 ± 1.831 ms [5.253 … 14.187]95%CI@5'
+  """
+  n: int
+  mean: float
+  error: float
+  ci: tuple[float, float]
+  conf: float
+  unit = unit.strip()
+  n, mean, _, error, ci, conf = MeasurementStats(data, confidence=confidence)
+  f: Callable[[float], str] = lambda x: (
+      ('*0' if clip_negative and x < 0.0 else str(x)) if parser is None else
+      (f'*{parser(0.0)}' if clip_negative and x < 0.0 else parser(x)))
+  if n == 1:
+    return f'{f(mean)}{unit} ±? @1'
+  pct = int(round(conf * 100))
+  return f'{f(mean)}{unit} ± {f(error)}{unit} [{f(ci[0])}{unit} … {f(ci[1])}{unit}]{pct}%CI@{n}'
 
 
 class Timer:
@@ -254,15 +395,13 @@ class Timer:
     print(tm)
 
   Attributes:
-    label (str): Timer label
-    emit_print (bool): If True will print() the timer, else will logging.info() the timer
-    start (float | None): Start time
-    end (float | None): End time
-    elapsed (float | None): Time delta
+    label (str, optional): Timer label
+    emit_log (bool, optional): If True (default) will logging.info() the timer, else will not
+    emit_print (bool, optional): If True will print() the timer, else (default) will not
   """
 
   def __init__(
-      self, label: str = 'Elapsed time', /, *,
+      self, label: str = '', /, *,
       emit_log: bool = True, emit_print: bool = False) -> None:
     """Initialize the Timer.
 
@@ -277,19 +416,27 @@ class Timer:
     self.emit_log: bool = emit_log
     self.emit_print: bool = emit_print
     self.label: str = label.strip()
-    if not self.label:
-      raise InputError('Empty label')
     self.start: float | None = None
     self.end: float | None = None
-    self.elapsed: float | None = None
+
+  @property
+  def elapsed(self) -> float:
+    """Elapsed time. Will be zero until a measurement is available with start/end."""
+    if self.start is None or self.end is None:
+      return 0.0
+    delta: float = self.end - self.start
+    if delta <= 0.0:
+      raise Error(f'negative/zero delta: {delta}')
+    return delta
 
   def __str__(self) -> str:
     """Current timer value."""
     if self.start is None:
-      return f'{self.label}: <UNSTARTED>'
-    if self.end is None or self.elapsed is None:
-      return f'{self.label}: <PARTIAL> {HumanizedSeconds(time.perf_counter() - self.start)}'
-    return f'{self.label}: {HumanizedSeconds(self.elapsed)}'
+      return f'{self.label}: <UNSTARTED>' if self.label else '<UNSTARTED>'
+    if self.end is None:
+      return ((f'{self.label}: ' if self.label else '') +
+              f'<PARTIAL> {HumanizedSeconds(time.perf_counter() - self.start)}')
+    return (f'{self.label}: ' if self.label else '') + f'{HumanizedSeconds(self.elapsed)}'
 
   def Start(self) -> None:
     """Start the timer."""
@@ -306,10 +453,9 @@ class Timer:
     """Stop the timer and emit logging.info with timer message."""
     if self.start is None:
       raise Error('Stopping an unstarted timer')
-    if self.end is not None or self.elapsed is not None:
+    if self.end is not None:
       raise Error('Re-stopping timer is forbidden')
     self.end = time.perf_counter()
-    self.elapsed = self.end - self.start
     message: str = str(self)
     if self.emit_log:
       logging.info(message)
@@ -578,6 +724,134 @@ def ObfuscateSecret(data: str | bytes | int, /) -> str:
   return BytesToHex(Hash512(data))[:8] + '…'
 
 
+class CryptoInputType(enum.StrEnum):
+  """Types of inputs that can represent arbitrary bytes."""
+  # prefixes; format prefixes are all 4 bytes
+  PATH = '@'       # @path on disk → read bytes from a file
+  STDIN = '@-'     # stdin
+  HEX = 'hex:'     # hex:deadbeef → decode hex
+  BASE64 = 'b64:'  # b64:... → decode base64
+  STR = 'str:'     # str:hello → UTF-8 encode the literal
+  RAW = 'raw:'     # raw:... → byte literals via \\xNN escapes (rare but handy)
+
+
+def BytesToRaw(b: bytes, /) -> str:
+  """Convert bytes to double-quoted string with \\xNN escapes where needed.
+
+  1. map bytes 0..255 to same code points (latin1)
+  2. escape non-printables/backslash/quotes via unicode_escape
+
+  Args:
+    b (bytes): input
+
+  Returns:
+    str: double-quoted string with \\xNN escapes where needed
+  """
+  inner: str = b.decode('latin1').encode('unicode_escape').decode('ascii')
+  return f'"{inner.replace('"', r'\"')}"'
+
+
+def RawToBytes(s: str, /) -> bytes:
+  """Convert double-quoted string with \\xNN escapes where needed to bytes.
+
+  Args:
+    s (str): input (expects a double-quoted string; parses \\xNN, \n, \\ etc)
+
+  Returns:
+    bytes: data
+  """
+  if len(s) >= 2 and s[0] == s[-1] == '"':
+    s = s[1:-1]
+  # decode backslash escapes to code points, then map 0..255 -> bytes
+  return codecs.decode(s, 'unicode_escape').encode('latin1')
+
+
+def DetectInputType(data_str: str, /) -> CryptoInputType | None:
+  """Auto-detect `data_str` type, if possible.
+
+  Args:
+    data_str (str): data to process, putatively a bytes blob
+
+  Returns:
+    CryptoInputType | None: type if has a known prefix, None otherwise
+
+  Raises:
+    InputError: unexpected type or conversion error
+  """
+  data_str = data_str.strip()
+  if data_str == CryptoInputType.STDIN:
+    return CryptoInputType.STDIN
+  for t in (
+      CryptoInputType.PATH, CryptoInputType.STR, CryptoInputType.HEX,
+      CryptoInputType.BASE64, CryptoInputType.RAW):
+    if data_str.startswith(t):
+      return t
+  return None
+
+
+def BytesFromInput(data_str: str, /, *, expect: CryptoInputType | None = None) -> bytes:  # pylint:disable=too-many-return-statements
+  """Parse input `data_str` into `bytes`. May auto-detect or enforce a type of input.
+
+  Can load from disk ('@'). Can load from stdin ('@-').
+
+  Args:
+    data_str (str): data to process, putatively a bytes blob
+    expect (CryptoInputType | None, optional): If not given (None) will try to auto-detect the
+        input type by looking at the prefix on `data_str` and if none is found will suppose
+        a 'str:' was given; if one of the supported CryptoInputType is given then will enforce
+        that specific type prefix or no prefix
+
+  Returns:
+    bytes: data
+
+  Raises:
+    InputError: unexpected type or conversion error
+  """
+  data_str = data_str.strip()
+  # auto-detect
+  detected_type: CryptoInputType | None = DetectInputType(data_str)
+  expect = CryptoInputType.STR if expect is None and detected_type is None else expect
+  if detected_type is not None and expect is not None and detected_type != expect:
+    raise InputError(f'Expected type {expect=} is different from detected type {detected_type=}')
+  # now we know they don't conflict, so unify them; remove prefix if we have it
+  expect = detected_type if expect is None else expect
+  assert expect is not None, 'should never happen: type should be known here'
+  data_str = data_str[len(expect):] if data_str.startswith(expect) else data_str
+  # for every type something different will happen now
+  try:
+    match expect:
+      case CryptoInputType.STDIN:
+        # read raw bytes from stdin: prefer the binary buffer; if unavailable,
+        # fall back to text stream encoded as UTF-8 (consistent with str: policy).
+        stream = getattr(sys.stdin, 'buffer', None)
+        if stream is None:
+          text: str = sys.stdin.read()
+          if not isinstance(text, str):  # type:ignore
+            raise InputError('sys.stdin.read() produced non-text data')
+          return text.encode('utf-8')
+        data: bytes = stream.read()
+        if not isinstance(data, bytes):  # type:ignore
+          raise InputError('sys.stdin.buffer.read() produced non-binary data')
+        return data
+      case CryptoInputType.PATH:
+        if not os.path.exists(data_str):
+          raise InputError(f'cannot find file {data_str!r}')
+        with open(data_str, 'rb') as file_obj:
+          return file_obj.read()
+      case CryptoInputType.STR:
+        return data_str.encode('utf-8')
+      case CryptoInputType.HEX:
+        return HexToBytes(data_str)
+      case CryptoInputType.BASE64:
+        return EncodedToBytes(data_str)
+      case CryptoInputType.RAW:
+        return RawToBytes(data_str)
+      case _:
+        raise InputError(f'invalid type {expect!r}')
+  except Exception as err:
+    raise InputError(f'invalid input: {err}') from err
+
+
 @dataclasses.dataclass(kw_only=True, slots=True, frozen=True, repr=False)
 class CryptoKey(abc.ABC):
   """A cryptographic key."""
@@ -593,7 +867,6 @@ class CryptoKey(abc.ABC):
       string representation of the key without leaking secrets
     """
     # every sub-class of CryptoKey has to implement its own version of __str__()
-    # TODO: make printing a part of the CLI
 
   @final
   def __repr__(self) -> str:
@@ -626,23 +899,110 @@ class CryptoKey(abc.ABC):
 
   @final
   @property
-  def blob(self) -> bytes:
-    """Serial (bytes) representation of the object.
+  def _json_dict(self) -> dict[str, Any]:
+    """Dictionary representation of the object suitable for JSON conversion.
 
     Returns:
-      bytes, pickled, representation of the object
+      dict[str, Any]: representation of the object suitable for JSON conversion
+
+    Raises:
+      ImplementationError: object has types that are not supported in JSON
     """
-    return Serialize(self, compress=-2, silent=True)
+    self_dict: dict[str, Any] = dataclasses.asdict(self)
+    for field in dataclasses.fields(self):
+      # check the type is OK
+      if field.type not in _JSON_DATACLASS_TYPES:
+        raise ImplementationError(
+            f'Unsupported JSON field {field.name!r}/{field.type} not in {_JSON_DATACLASS_TYPES}')
+      # convert types that we accept but JSON does not
+      if field.type == 'bytes':
+        self_dict[field.name] = BytesToEncoded(self_dict[field.name])
+    return self_dict
 
   @final
   @property
-  def encoded(self) -> str:
-    """Base-64 representation of the object.
+  def json(self) -> str:
+    """JSON representation of the object, tightly packed, not for humans.
 
     Returns:
-      str, pickled, base64, representation of the object
+      str: JSON representation of the object, tightly packed
+
+    Raises:
+      ImplementationError: object has types that are not supported in JSON
     """
-    return BytesToEncoded(self.blob)
+    return json.dumps(self._json_dict, separators=(',', ':'))
+
+  @final
+  @property
+  def formatted_json(self) -> str:
+    """JSON representation of the object formatted for humans.
+
+    Returns:
+      str: JSON representation of the object formatted for humans
+
+    Raises:
+      ImplementationError: object has types that are not supported in JSON
+    """
+    return json.dumps(self._json_dict, indent=4, sort_keys=True)
+
+  @final
+  @classmethod
+  def _FromJSONDict(cls, json_dict: dict[str, Any], /) -> Self:
+    """Create object from JSON representation.
+
+    Args:
+      json_dict (dict[str, Any]): JSON dict
+
+    Returns:
+      a CryptoKey object ready for use
+
+    Raises:
+      InputError: unexpected type/fields
+    """
+    # check we got exactly the fields we needed
+    cls_fields: set[str] = set(f.name for f in dataclasses.fields(cls))
+    json_fields: set[str] = set(json_dict)
+    if cls_fields != json_fields:
+      raise InputError(f'JSON data decoded to unexpected fields: {cls_fields=} / {json_fields=}')
+    # reconstruct the types we meddled with inside self._json_dict
+    for field in dataclasses.fields(cls):
+      if field.type not in _JSON_DATACLASS_TYPES:
+        raise ImplementationError(
+            f'Unsupported JSON field {field.name!r}/{field.type} not in {_JSON_DATACLASS_TYPES}')
+      if field.type == 'bytes':
+        json_dict[field.name] = EncodedToBytes(json_dict[field.name])
+    # build the object
+    return cls(**json_dict)
+
+  @final
+  @classmethod
+  def FromJSON(cls, json_data: str, /) -> Self:
+    """Create object from JSON representation.
+
+    Args:
+      json_data (str): JSON string
+
+    Returns:
+      a CryptoKey object ready for use
+
+    Raises:
+      InputError: unexpected type/fields
+    """
+    # get the dict back
+    json_dict: dict[str, Any] = json.loads(json_data)
+    if not isinstance(json_dict, dict):  # type:ignore
+      raise InputError(f'JSON data decoded to unexpected type: {type(json_dict)}')
+    return cls._FromJSONDict(json_dict)
+
+  @final
+  @property
+  def blob(self) -> bytes:
+    """Serial (bytes) representation of the object.
+
+    Returns:
+      bytes, pickled, representation of the object
+    """
+    return self.Blob()
 
   @final
   def Blob(self, /, *, key: Encryptor | None = None, silent: bool = True) -> bytes:
@@ -655,7 +1015,17 @@ class CryptoKey(abc.ABC):
     Returns:
       bytes, pickled, representation of the object
     """
-    return Serialize(self, compress=-2, key=key, silent=silent)
+    return Serialize(self._json_dict, compress=-2, key=key, silent=silent, pickler=PickleJSON)
+
+  @final
+  @property
+  def encoded(self) -> str:
+    """Base-64 representation of the object.
+
+    Returns:
+      str, pickled, base64, representation of the object
+    """
+    return self.Encoded()
 
   @final
   def Encoded(self, /, *, key: Encryptor | None = None, silent: bool = True) -> str:
@@ -668,7 +1038,53 @@ class CryptoKey(abc.ABC):
     Returns:
       str, pickled, base64, representation of the object
     """
-    return BytesToEncoded(self.Blob(key=key, silent=silent))
+    return CryptoInputType.BASE64 + BytesToEncoded(self.Blob(key=key, silent=silent))
+
+  @final
+  @property
+  def hex(self) -> str:
+    """Hexadecimal representation of the object.
+
+    Returns:
+      str, pickled, hexadecimal, representation of the object
+    """
+    return self.Hex()
+
+  @final
+  def Hex(self, /, *, key: Encryptor | None = None, silent: bool = True) -> str:
+    """Hexadecimal representation of the object with more options, including encryption.
+
+    Args:
+      key (Encryptor, optional): if given will key.Encrypt() data before saving
+      silent (bool, optional): if True (default) will not log
+
+    Returns:
+      str, pickled, hexadecimal, representation of the object
+    """
+    return CryptoInputType.HEX + BytesToHex(self.Blob(key=key, silent=silent))
+
+  @final
+  @property
+  def raw(self) -> str:
+    """Raw escaped binary representation of the object.
+
+    Returns:
+      str, pickled, raw escaped binary, representation of the object
+    """
+    return self.Raw()
+
+  @final
+  def Raw(self, /, *, key: Encryptor | None = None, silent: bool = True) -> str:
+    """Raw escaped binary representation of the object with more options, including encryption.
+
+    Args:
+      key (Encryptor, optional): if given will key.Encrypt() data before saving
+      silent (bool, optional): if True (default) will not log
+
+    Returns:
+      str, pickled, raw escaped binary, representation of the object
+    """
+    return CryptoInputType.RAW + BytesToRaw(self.Blob(key=key, silent=silent))
 
   @final
   @classmethod
@@ -687,13 +1103,14 @@ class CryptoKey(abc.ABC):
     """
     # if this is a string, then we suppose it is base64
     if isinstance(data, str):
-      data = EncodedToBytes(data)
+      data = BytesFromInput(data)
     # we now have bytes and we suppose it came from CryptoKey.blob()/CryptoKey.CryptoBlob()
-    obj: CryptoKey = DeSerialize(data=data, key=key, silent=silent)
-    # make sure we've got an object that makes sense
-    if not isinstance(obj, CryptoKey):  # type:ignore
-      raise InputError(f'serialized data is not a CryptoKey: {type(obj)}')
-    return obj  # type:ignore
+    try:
+      json_dict: dict[str, Any] = DeSerialize(
+          data=data, key=key, silent=silent, unpickler=UnpickleJSON)
+      return cls._FromJSONDict(json_dict)
+    except Exception as err:
+      raise InputError(f'input decode error: {err}') from err
 
 
 @runtime_checkable
@@ -799,14 +1216,15 @@ class Signer(Protocol):  # pylint: disable=too-few-public-methods
     """
 
 
-def Serialize(
+def Serialize(  # pylint:disable=too-many-arguments
     python_obj: Any, /, *, file_path: str | None = None,
-    compress: int | None = 3, key: Encryptor | None = None, silent: bool = False) -> bytes:
+    compress: int | None = 3, key: Encryptor | None = None, silent: bool = False,
+    pickler: Callable[[Any], bytes] = PickleGeneric) -> bytes:
   """Serialize a Python object into a BLOB, optionally compress / encrypt / save to disk.
 
   Data path is:
 
-    `obj` => pickle => (compress) => (encrypt) => (save to `file_path`) => return
+    `obj` => [pickler] => (compress) => (encrypt) => (save to `file_path`) => return
 
   At every step of the data path the data will be measured, in bytes.
   Every data conversion will be timed. The measurements/times will be logged (once).
@@ -829,6 +1247,9 @@ def Serialize(
         None is no compression; default is 3, which is fast, see table above for other values
     key (Encryptor, optional): if given will key.Encrypt() data before saving
     silent (bool, optional): if True will not log; default is False (will log)
+    pickler (Callable[[Any], bytes], optional): if not given, will just be the `pickle` module;
+        if given will be a method to convert any Python object to its `bytes` representation;
+        PickleGeneric is the default, but another useful value is PickleJSON
 
   Returns:
     bytes: serialized binary data corresponding to obj + (compression) + (encryption)
@@ -837,7 +1258,7 @@ def Serialize(
   with Timer('Serialization complete', emit_log=False) as tm_all:
     # pickle
     with Timer('PICKLE', emit_log=False) as tm_pickle:
-      obj: bytes = pickle.dumps(python_obj, protocol=_PICKLE_PROTOCOL)
+      obj: bytes = pickler(python_obj)
     if not silent:
       messages.append(f'    {tm_pickle}, {HumanizedBytes(len(obj))}')
     # compress, if needed
@@ -869,12 +1290,13 @@ def Serialize(
 
 def DeSerialize(
     *, data: bytes | None = None, file_path: str | None = None,
-    key: Decryptor | None = None, silent: bool = False) -> Any:
+    key: Decryptor | None = None, silent: bool = False,
+    unpickler: Callable[[bytes], Any] = UnpickleGeneric) -> Any:
   """Loads (de-serializes) a BLOB back to a Python object, optionally decrypting / decompressing.
 
   Data path is:
 
-    `data` or `file_path` => (decrypt) => (decompress) => unpickle => return object
+    `data` or `file_path` => (decrypt) => (decompress) => [unpickler] => return object
 
   At every step of the data path the data will be measured, in bytes.
   Every data conversion will be timed. The measurements/times will be logged (once).
@@ -887,6 +1309,9 @@ def DeSerialize(
        if you use this option, `data` will be ignored
     key (Decryptor, optional): if given will key.Decrypt() data before decompressing/loading
     silent (bool, optional): if True will not log; default is False (will log)
+    pickler (Callable[[bytes], Any], optional): if not given, will just be the `pickle` module;
+        if given will be a method to convert a `bytes` representation back to a Python object;
+        UnpickleGeneric is the default, but another useful value is UnpickleJSON
 
   Returns:
     De-Serialized Python object corresponding to data
@@ -933,7 +1358,7 @@ def DeSerialize(
         messages.append('    (no compression detected)')
     # create the actual object = unpickle
     with Timer('UNPICKLE', emit_log=False) as tm_unpickle:
-      python_obj: Any = pickle.loads(obj)
+      python_obj: Any = unpickler(obj)
     if not silent:
       messages.append(f'    {tm_unpickle}')
   # log and return
@@ -1070,3 +1495,186 @@ class PrivateBid512(PublicBid512):
         public_hash=Hash512(public_key + private_key + secret),
         private_key=private_key,
         secret_bid=secret)
+
+
+def _FlagNames(a: argparse.Action, /) -> list[str]:
+  # Positional args have empty 'option_strings'; otherwise use them (e.g., ['-v','--verbose'])
+  if a.option_strings:
+    return list(a.option_strings)
+  if a.nargs:
+    if isinstance(a.metavar, str) and a.metavar:
+      # e.g., nargs=2, metavar='FILE'
+      return [a.metavar]
+    if isinstance(a.metavar, tuple):
+      # e.g., nargs=2, metavar=('FILE1', 'FILE2')
+      return list(a.metavar)
+  # Otherwise, it’s a positional arg with no flags, so return the destination name
+  return [a.dest]
+
+
+def _ActionIsSubparser(a: argparse.Action, /) -> bool:
+  return isinstance(a, argparse._SubParsersAction)  # type: ignore[attr-defined]  # pylint: disable=protected-access
+
+
+def _FormatDefault(a: argparse.Action, /) -> str:
+  if a.default is argparse.SUPPRESS:
+    return ''
+  if isinstance(a.default, bool):
+    return ' (default: on)' if a.default else ''
+  if a.default in (None, '', 0, False):
+    return ''
+  return f' (default: {a.default})'
+
+
+def _FormatChoices(a: argparse.Action, /) -> str:
+  return f' choices: {list(a.choices)}' if getattr(a, 'choices', None) else ''  # type:ignore
+
+
+def _FormatType(a: argparse.Action, /) -> str:
+  t: Any | None = getattr(a, 'type', None)
+  if t is None:
+    return ''
+  # Show clean type names (int, str, float); for callables, just say 'custom'
+  return f' type: {t.__name__ if hasattr(t, "__name__") else "custom"}'
+
+
+def _FormatNArgs(a: argparse.Action, /) -> str:
+  return f' nargs: {a.nargs}' if getattr(a, 'nargs', None) not in (None, 0) else ''
+
+
+def _RowsForActions(actions: Sequence[argparse.Action], /) -> list[tuple[str, str]]:
+  rows: list[tuple[str, str]] = []
+  for a in actions:
+    if _ActionIsSubparser(a):
+      continue
+    # skip the built-in help action; it’s implied
+    if getattr(a, 'help', '') == argparse.SUPPRESS or isinstance(a, argparse._HelpAction):  # type: ignore[attr-defined]  # pylint: disable=protected-access
+      continue
+    flags: str = ', '.join(_FlagNames(a))
+    meta: str = ''.join(
+        (_FormatType(a), _FormatNArgs(a), _FormatChoices(a), _FormatDefault(a))).strip()
+    desc: str = (a.help or '').strip()
+    if meta:
+      desc = f'{desc} [{meta}]' if desc else f'[{meta}]'
+    rows.append((flags, desc))
+  return rows
+
+
+def _MarkdownTable(
+    rows: Sequence[tuple[str, str]],
+    headers: tuple[str, str] = ('Option/Arg', 'Description'), /) -> str:
+  if not rows:
+    return ''
+  out: list[str] = ['| ' + headers[0] + ' | ' + headers[1] + ' |', '|---|---|']
+  for left, right in rows:
+    out.append(f'| `{left}` | {right} |')
+  return '\n'.join(out)
+
+
+def _WalkSubcommands(
+    parser: argparse.ArgumentParser, path: list[str] | None = None, /) -> list[
+    tuple[list[str], argparse.ArgumentParser, Any]]:
+  path = path or []
+  items: list[tuple[list[str], argparse.ArgumentParser, Any]] = []
+  # sub_action = None
+  name: str
+  sp: argparse.ArgumentParser
+  for action in parser._actions:  # type: ignore[attr-defined]  # pylint: disable=protected-access
+    if _ActionIsSubparser(action):
+      # sub_action = a  # type: ignore[assignment]
+      for name, sp in action.choices.items():              # type:ignore
+        items.append((path + [name], sp, action))          # type:ignore
+        items.extend(_WalkSubcommands(sp, path + [name]))  # type:ignore
+  return items
+
+
+def _HelpText(sub_parser: argparse.ArgumentParser, parent_sub_action: Any, /) -> str:
+  if parent_sub_action is not None:
+    for choice_action in parent_sub_action._choices_actions:  # type: ignore  # pylint: disable=protected-access
+      if choice_action.dest == sub_parser.prog.split()[-1]:
+        return choice_action.help or ''
+  return ''
+
+
+def GenerateCLIMarkdown(  # pylint:disable=too-many-locals,too-many-statements
+    prog: str, parser: argparse.ArgumentParser, /, *, description: str = '') -> str:  # pylint: disable=too-many-locals
+  """Return a Markdown doc section that reflects the current _BuildParser() tree.
+
+  Will treat epilog strings as examples, splitting on '$$' to get multiple examples.
+
+  Args:
+    prog (str): name of app, eg. 'transcrypto' or 'transcrypto.py'
+    parser (argparse.ArgumentParser): parser to use for data
+    description (str, optional): app description to use as intro
+
+  Returns:
+    str: markdown
+
+  Raises:
+    InputError: invalid app name
+  """
+  prog, description = prog.strip(), description.strip()
+  if not prog or prog not in parser.prog:
+    raise InputError(f'invalid prog/parser.prog: {prog=}, {parser.prog=}')
+  lines: list[str] = ['']
+  lines.append('<!-- cspell:disable -->')
+  lines.append('<!-- auto-generated; do not edit -->\n')
+  # Header + global flags
+  lines.append(f'# `{prog}` Command-Line Interface\n')
+  lines.append(description + '\n')
+  lines.append('Invoke with:\n')
+  lines.append('```bash')
+  lines.append(f'{parser.prog} <command> [sub-command] [options...]')
+  lines.append('```\n')
+  # Global options table
+  global_rows: list[tuple[str, str]] = _RowsForActions(parser._actions)  # type: ignore[attr-defined]  # pylint: disable=protected-access
+  if global_rows:
+    lines.append('## Global Options\n')
+    lines.append(_MarkdownTable(global_rows))
+    lines.append('')
+  # Top-level commands summary
+  lines.append('## Top-Level Commands\n')
+  # Find top-level subparsers to list available commands
+  top_subs: list[argparse.Action] = [a for a in parser._actions if _ActionIsSubparser(a)]  # type: ignore[attr-defined]  # pylint: disable=protected-access
+  for action in top_subs:
+    for name, sp in action.choices.items():  # type: ignore[union-attr]
+      help_text: str = (                     # type:ignore
+          sp.description or ' '.join(i.strip() for i in sp.format_usage().splitlines())).strip()  # type:ignore
+      short: str = (sp.help if hasattr(sp, 'help') else '') or ''  # type:ignore
+      help_text = short or help_text                               # type:ignore
+      help_text = help_text.replace('usage: ', '').strip()         # type:ignore
+      lines.append(f'- **`{name}`** — `{help_text}`')
+  lines.append('')
+  if parser.epilog:
+    lines.append('```bash')
+    lines.append(parser.epilog)
+    lines.append('```\n')
+  # Detailed sections per (sub)command
+  for path, sub_parser, parent_sub_action in _WalkSubcommands(parser):
+    if len(path) == 1:
+      lines.append('---\n')  # horizontal rule between top-level commands
+    header: str = ' '.join(path)
+    lines.append(f'##{"" if len(path) == 1 else "#"} `{header}`')  # (header level 3 or 4)
+    # Usage block
+    help_text = _HelpText(sub_parser, parent_sub_action)
+    if help_text:
+      lines.append(f'\n{help_text}')
+    usage: str = sub_parser.format_usage().replace('usage: ', '').strip()
+    lines.append('\n```bash')
+    lines.append(str(usage))
+    lines.append('```\n')
+    # Options/args table
+    rows: list[tuple[str, str]] = _RowsForActions(sub_parser._actions)  # type: ignore[attr-defined]  # pylint: disable=protected-access
+    if rows:
+      lines.append(_MarkdownTable(rows))
+      lines.append('')
+    # Examples (if any) - stored in epilog argument
+    epilog: str = sub_parser.epilog.strip() if sub_parser.epilog else ''
+    if epilog:
+      lines.append('**Example:**\n')
+      lines.append('```bash')
+      for epilog_line in epilog.split('$$'):
+        lines.append(f'$ {parser.prog} {epilog_line.strip()}')
+      lines.append('```\n')
+  # join all lines as the markdown string
+  return ('\n'.join(lines)).strip()