transcrypto 1.5.1__py3-none-any.whl → 1.7.0__py3-none-any.whl

transcrypto/base.py

@@ -1,13 +1,10 @@
-#!/usr/bin/env python3
-#
-# Copyright 2025 Daniel Balparda (balparda@github.com) - Apache-2.0 license
-#
+# SPDX-FileCopyrightText: Copyright 2026 Daniel Balparda <balparda@github.com>
+# SPDX-License-Identifier: Apache-2.0
 """Balparda's TransCrypto base library."""
 
 from __future__ import annotations
 
-import abc
-import argparse
+import abc as abstract
 import base64
 import codecs
 import dataclasses
@@ -18,72 +15,104 @@ import hashlib
 import json
 import logging
 import math
-import os.path
-import pickle
-# import pdb
+import os
+import pathlib
+import pickle  # noqa: S403
 import secrets
 import sys
+import threading
 import time
-from typing import Any, Callable, final, MutableSequence, Protocol, runtime_checkable
-from typing import Sequence, Self, TypeVar
-
+from collections import abc
+from types import TracebackType
+from typing import (
+  Any,
+  Protocol,
+  Self,
+  TypeVar,
+  cast,
+  final,
+  runtime_checkable,
+)
+
+import click
 import numpy as np
-from scipy import stats  # type:ignore
+import typer
 import zstandard
-
-__author__ = 'balparda@github.com'
-__version__ = '1.5.1'  # 2026-01-13, Tue
-__version_tuple__: tuple[int, ...] = tuple(int(v) for v in __version__.split('.'))
+from click import testing as click_testing
+from rich import console as rich_console
+from rich import logging as rich_logging
+from scipy import stats
 
 # Data conversion utils
 
-BytesToHex: Callable[[bytes], str] = lambda b: b.hex()
-BytesToInt: Callable[[bytes], int] = lambda b: int.from_bytes(b, 'big', signed=False)
-BytesToEncoded: Callable[[bytes], str] = lambda b: base64.urlsafe_b64encode(b).decode('ascii')
+BytesToHex: abc.Callable[[bytes], str] = lambda b: b.hex()
+BytesToInt: abc.Callable[[bytes], int] = lambda b: int.from_bytes(b, 'big', signed=False)
+BytesToEncoded: abc.Callable[[bytes], str] = lambda b: base64.urlsafe_b64encode(b).decode('ascii')
 
-HexToBytes: Callable[[str], bytes] = bytes.fromhex
-IntToFixedBytes: Callable[[int, int], bytes] = lambda i, n: i.to_bytes(n, 'big', signed=False)
-IntToBytes: Callable[[int], bytes] = lambda i: IntToFixedBytes(i, (i.bit_length() + 7) // 8)
-IntToEncoded: Callable[[int], str] = lambda i: BytesToEncoded(IntToBytes(i))
-EncodedToBytes: Callable[[str], bytes] = lambda e: base64.urlsafe_b64decode(e.encode('ascii'))
+HexToBytes: abc.Callable[[str], bytes] = bytes.fromhex
+IntToFixedBytes: abc.Callable[[int, int], bytes] = lambda i, n: i.to_bytes(n, 'big', signed=False)
+IntToBytes: abc.Callable[[int], bytes] = lambda i: IntToFixedBytes(i, (i.bit_length() + 7) // 8)
+IntToEncoded: abc.Callable[[int], str] = lambda i: BytesToEncoded(IntToBytes(i))
+EncodedToBytes: abc.Callable[[str], bytes] = lambda e: base64.urlsafe_b64decode(e.encode('ascii'))
 
-PadBytesTo: Callable[[bytes, int], bytes] = lambda b, i: b.rjust((i + 7) // 8, b'\x00')
+PadBytesTo: abc.Callable[[bytes, int], bytes] = lambda b, i: b.rjust((i + 7) // 8, b'\x00')
 
 # Time utils
 
-MIN_TM = int(
-    datetime.datetime(2000, 1, 1, 0, 0, 0).replace(tzinfo=datetime.timezone.utc).timestamp())
+MIN_TM = int(datetime.datetime(2000, 1, 1, 0, 0, 0, tzinfo=datetime.UTC).timestamp())
 TIME_FORMAT = '%Y/%b/%d-%H:%M:%S-UTC'
-TimeStr: Callable[[int | float | None], str] = lambda tm: (
-    time.strftime(TIME_FORMAT, time.gmtime(tm)) if tm else '-')
-Now: Callable[[], int] = lambda: int(time.time())
-StrNow: Callable[[], str] = lambda: TimeStr(Now())
+TimeStr: abc.Callable[[int | float | None], str] = lambda tm: (
+  time.strftime(TIME_FORMAT, time.gmtime(tm)) if tm else '-'
+)
+Now: abc.Callable[[], int] = lambda: int(time.time())
+StrNow: abc.Callable[[], str] = lambda: TimeStr(Now())
+
+# Logging
+_LOG_FORMAT_NO_PROCESS: str = '%(funcName)s: %(message)s'
+_LOG_FORMAT_WITH_PROCESS: str = '%(processName)s/' + _LOG_FORMAT_NO_PROCESS
+_LOG_FORMAT_DATETIME: str = '[%Y%m%d-%H:%M:%S]'  # e.g., [20240131-13:45:30]
+_LOG_LEVELS: dict[int, int] = {
+  0: logging.ERROR,
+  1: logging.WARNING,
+  2: logging.INFO,
+  3: logging.DEBUG,
+}
+_LOG_COMMON_PROVIDERS: set[str] = {
+  'werkzeug',
+  'gunicorn.error',
+  'gunicorn.access',
+  'uvicorn',
+  'uvicorn.error',
+  'uvicorn.access',
+  'django.server',
+}
 
 # 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
+  -6: 'a',  # atto
+  -5: 'f',  # femto
+  -4: 'p',  # pico
+  -3: 'n',  # nano
+  -2: 'µ',  # micro (unicode U+00B5)  # noqa: RUF001
+  -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'))
+PickleGeneric: abc.Callable[[Any], bytes] = lambda o: pickle.dumps(o, protocol=_PICKLE_PROTOCOL)
+UnpickleGeneric: abc.Callable[[bytes], Any] = pickle.loads  # noqa: S301
+PickleJSON: abc.Callable[[dict[str, Any]], bytes] = lambda d: json.dumps(
+  d, separators=(',', ':')
+).encode('utf-8')
+UnpickleJSON: abc.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
@@ -91,11 +120,17 @@ _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',
+  # native support
+  'int',
+  'float',
+  'str',
+  'bool',
+  'list[int]',
+  'list[float]',
+  'list[str]',
+  'list[bool]',
+  # need conversion/encoding
+  'bytes',
 }
 
 
@@ -112,10 +147,116 @@ class CryptoError(Error):
 
 
 class ImplementationError(Error, NotImplementedError):
-  """This feature is not implemented yet (TransCrypto)."""
+  """Feature is not implemented yet (TransCrypto)."""
+
 
+__console_lock: threading.RLock = threading.RLock()
+__console_singleton: rich_console.Console | None = None
+
+
+def Console() -> rich_console.Console:
+  """Get the global console instance.
+
+  Returns:
+    rich.console.Console: The global console instance.
+
+  """
+  with __console_lock:
+    if __console_singleton is None:
+      return rich_console.Console()  # fallback console if InitLogging hasn't been called yet
+    return __console_singleton
+
+
+def ResetConsole() -> None:
+  """Reset the global console instance."""
+  global __console_singleton  # noqa: PLW0603
+  with __console_lock:
+    __console_singleton = None
+
+
+def InitLogging(
+  verbosity: int,
+  /,
+  *,
+  include_process: bool = False,
+  soft_wrap: bool = False,
+  color: bool | None = False,
+) -> tuple[rich_console.Console, int, bool]:
+  """Initialize logger (with RichHandler) and get a rich.console.Console singleton.
+
+  This method will also return the actual decided values for verbosity and color use.
+  If you have a CLI app that uses this, its pytests should call `ResetConsole()` in a fixture, like:
+
+      from transcrypto import logging
+      @pytest.fixture(autouse=True)
+      def _reset_base_logging() -> Generator[None, None, None]:  # type: ignore
+        logging.ResetConsole()
+        yield  # stop
+
+  Args:
+    verbosity (int): Logging verbosity level: 0==ERROR, 1==WARNING, 2==INFO, 3==DEBUG
+    include_process (bool, optional): Whether to include process name in log output.
+    soft_wrap (bool, optional): Whether to enable soft wrapping in the console.
+        Default is False, and it means rich will hard-wrap long lines (by adding line breaks).
+    color (bool | None, optional): Whether to enable/disable color output in the console.
+        If None, respects NO_COLOR env var.
+
+  Returns:
+    tuple[rich_console.Console, int, bool]:
+        (The initialized console instance, actual log level, actual color use)
+
+  Raises:
+    RuntimeError: if you call this more than once
 
-def HumanizedBytes(inp_sz: int | float, /) -> str:  # pylint: disable=too-many-return-statements
+  """
+  global __console_singleton  # noqa: PLW0603
+  with __console_lock:
+    if __console_singleton is not None:
+      raise RuntimeError(
+        'calling InitLogging() more than once is forbidden; '
+        'use Console() to get a console after first creation'
+      )
+    # set level
+    logging_level: int = _LOG_LEVELS.get(min(verbosity, 3), logging.ERROR)
+    # respect NO_COLOR unless the caller has already decided (treat env presence as "disable color")
+    no_color: bool = (
+      False
+      if (os.getenv('NO_COLOR') is None and color is None)
+      else ((os.getenv('NO_COLOR') is not None) if color is None else (not color))
+    )
+    # create console and configure logging
+    console = rich_console.Console(soft_wrap=soft_wrap, no_color=no_color)
+    logging.basicConfig(
+      level=logging_level,
+      format=_LOG_FORMAT_WITH_PROCESS if include_process else _LOG_FORMAT_NO_PROCESS,
+      datefmt=_LOG_FORMAT_DATETIME,
+      handlers=[
+        rich_logging.RichHandler(  # we show name/line, but want time & level
+          console=console,
+          rich_tracebacks=True,
+          show_time=True,
+          show_level=True,
+          show_path=True,
+        ),
+      ],
+      force=True,  # force=True to override any previous logging config
+    )
+    # configure common loggers
+    logging.captureWarnings(True)
+    for name in _LOG_COMMON_PROVIDERS:
+      log: logging.Logger = logging.getLogger(name)
+      log.handlers.clear()
+      log.propagate = True
+      log.setLevel(logging_level)
+    __console_singleton = console  # need a global statement to re-bind this one
+    logging.info(
+      f'Logging initialized at level {logging.getLevelName(logging_level)} / '
+      f'{"NO " if no_color else ""}COLOR'
+    )
+    return (console, logging_level, not no_color)
+
+
+def HumanizedBytes(inp_sz: float, /) -> str:  # noqa: PLR0911
   """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
@@ -147,10 +288,11 @@ def HumanizedBytes(inp_sz: int | float, /) -> str:  # pylint: disable=too-many-r
     '2.00 KiB'
     >>> HumanizedBytes(5 * 1024**3)
     '5.00 GiB'
+
   """
   if inp_sz < 0:
     raise InputError(f'input should be >=0 and got {inp_sz}')
-  if inp_sz < 1024:
+  if inp_sz < 1024:  # noqa: PLR2004
     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.3f} KiB'
@@ -165,7 +307,7 @@ def HumanizedBytes(inp_sz: int | float, /) -> str:  # pylint: disable=too-many-r
   return f'{(inp_sz / (1024 * 1024 * 1024 * 1024 * 1024 * 1024)):0.3f} EiB'
 
 
-def HumanizedDecimal(inp_sz: int | float, /, *, unit: str = '') -> str:
+def HumanizedDecimal(inp_sz: 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
@@ -202,7 +344,8 @@ def HumanizedDecimal(inp_sz: int | float, /, *, unit: str = '') -> str:
 
   Raises:
     InputError: If `inp_sz` is not finite.
-  """
+
+  """  # noqa: RUF002
   if not math.isfinite(inp_sz):
     raise InputError(f'input should finite; got {inp_sz!r}')
   unit = unit.strip()
@@ -212,8 +355,7 @@ def HumanizedDecimal(inp_sz: int | float, /, *, unit: str = '') -> str:
   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: 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
@@ -221,12 +363,12 @@ def HumanizedDecimal(inp_sz: int | float, /, *, unit: str = '') -> str:
       return f'{neg}{int(inp_sz)}{pad_unit}'
     return f'{neg}{inp_sz:0.3f}{pad_unit}'
   # scaled
-  scaled: float = inp_sz / (1000 ** exp)
+  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
+def HumanizedSeconds(inp_secs: float, /) -> str:  # noqa: PLR0911
   """Convert a duration in seconds into a human-readable time string.
 
   Selects the appropriate time unit based on the duration's magnitude:
@@ -267,17 +409,18 @@ def HumanizedSeconds(inp_secs: int | float, /) -> str:  # pylint: disable=too-ma
     '42.00 s'
     >>> HumanizedSeconds(3661)
     '1.02 h'
-  """
+
+  """  # noqa: RUF002
   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.000 s'
   inp_secs = float(inp_secs)
-  if inp_secs < 0.001:
-    return f'{inp_secs * 1000 * 1000:0.3f} µs'
+  if inp_secs < 0.001:  # noqa: PLR2004
+    return f'{inp_secs * 1000 * 1000:0.3f} µs'  # noqa: RUF001
   if inp_secs < 1:
     return f'{inp_secs * 1000:0.3f} ms'
-  if inp_secs < 60:
+  if inp_secs < 60:  # noqa: PLR2004
     return f'{inp_secs:0.3f} s'
   if inp_secs < 60 * 60:
     return f'{(inp_secs / 60):0.3f} min'
@@ -287,8 +430,8 @@ def HumanizedSeconds(inp_secs: int | float, /) -> str:  # pylint: disable=too-ma
 
 
 def MeasurementStats(
-    data: list[int | float], /, *,
-    confidence: float = 0.95) -> tuple[int, float, float, float, tuple[float, float], float]:
+  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
@@ -317,12 +460,13 @@ def MeasurementStats(
 
   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:
+  if not 0.5 <= confidence < 1.0:  # noqa: PLR2004
     raise InputError(f'invalid confidence: {confidence=}')
   # solve trivial case
   if n == 1:
@@ -330,17 +474,22 @@ def MeasurementStats(
   # 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
+  sem = stats.sem(np_data)
+  ci = stats.t.interval(confidence, n - 1, loc=mean, scale=sem)
+  t_crit = stats.t.ppf((1.0 + confidence) / 2.0, n - 1)
+  error = t_crit * sem  # half-width of the CI
+  return (n, float(mean), float(sem), float(error), (float(ci[0]), float(ci[1])), confidence)
 
 
 def HumanizedMeasurements(
-    data: list[int | float], /, *,
-    unit: str = '', parser: Callable[[float], str] | None = None,
-    clip_negative: bool = True, confidence: float = 0.95) -> str:
+  data: list[int | float],
+  /,
+  *,
+  unit: str = '',
+  parser: abc.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
@@ -365,6 +514,7 @@ def HumanizedMeasurements(
 
   Returns:
     str: A formatted summary string, e.g.: '9.720 ± 1.831 ms [5.253 … 14.187]95%CI@5'
+
   """
   n: int
   mean: float
@@ -373,12 +523,14 @@ def HumanizedMeasurements(
   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)))
+  f: abc.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))
+  pct: int = round(conf * 100)
   return f'{f(mean)}{unit} ± {f(error)}{unit} [{f(ci[0])}{unit} … {f(ci[1])}{unit}]{pct}%CI@{n}'
 
 
@@ -386,7 +538,6 @@ class Timer:
   """An execution timing class that can be used as both a context manager and a decorator.
 
   Examples:
-
     # As a context manager
     with Timer('Block timing'):
       time.sleep(1.2)
@@ -407,11 +558,12 @@ class Timer:
     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 = '', /, *,
-      emit_log: bool = True, emit_print: bool = False) -> None:
+    self, label: str = '', /, *, emit_log: bool = True, emit_print: bool = False
+  ) -> None:
     """Initialize the Timer.
 
     Args:
@@ -419,8 +571,6 @@ class Timer:
       emit_log (bool, optional): Emit a log message when finished; default is True
       emit_print (bool, optional): Emit a print() message when finished; default is False
 
-    Raises:
-      InputError: empty label
     """
     self.emit_log: bool = emit_log
     self.emit_print: bool = emit_print
@@ -430,7 +580,15 @@ class Timer:
 
   @property
   def elapsed(self) -> float:
-    """Elapsed time. Will be zero until a measurement is available with start/end."""
+    """Elapsed time. Will be zero until a measurement is available with start/end.
+
+    Raises:
+        Error: negative elapsed time
+
+    Returns:
+        float: elapsed time, in seconds
+
+    """
     if self.start is None or self.end is None:
       return 0.0
     delta: float = self.end - self.start
@@ -439,27 +597,48 @@ class Timer:
     return delta
 
   def __str__(self) -> str:
-    """Current timer value."""
+    """Get current timer value.
+
+    Returns:
+        str: human-readable representation of current time value
+
+    """
     if self.start is None:
       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'<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."""
+    """Start the timer.
+
+    Raises:
+        Error: if you try to re-start the timer
+
+    """
     if self.start is not None:
       raise Error('Re-starting timer is forbidden')
     self.start = time.perf_counter()
 
-  def __enter__(self) -> Timer:
-    """Start the timer when entering the context."""
+  def __enter__(self) -> Self:
+    """Start the timer when entering the context.
+
+    Returns:
+        Timer: context object (self)
+
+    """
     self.Start()
     return self
 
   def Stop(self) -> None:
-    """Stop the timer and emit logging.info with timer message."""
+    """Stop the timer and emit logging.info with timer message.
+
+    Raises:
+        Error: trying to re-start timer or stop unstarted timer
+
+    """
     if self.start is None:
       raise Error('Stopping an unstarted timer')
     if self.end is not None:
@@ -469,21 +648,18 @@ class Timer:
     if self.emit_log:
       logging.info(message)
     if self.emit_print:
-      print(message)
+      Console().print(message)
 
   def __exit__(
-      self, unused_exc_type: type[BaseException] | None,
-      unused_exc_val: BaseException | None, exc_tb: Any) -> None:
-    """Stop the timer when exiting the context, emit logging.info and optionally print elapsed time.
-
-    Args:
-      exc_type (type | None): Exception type, if any.
-      exc_val (BaseException | None): Exception value, if any.
-      exc_tb (Any): Traceback object, if any.
-    """
+    self,
+    unused_exc_type: type[BaseException] | None,
+    unused_exc_val: BaseException | None,
+    exc_tb: TracebackType | None,
+  ) -> None:
+    """Stop the timer when exiting the context."""
     self.Stop()
 
-  _F = TypeVar('_F', bound=Callable[..., Any])
+  _F = TypeVar('_F', bound=abc.Callable[..., Any])
 
   def __call__(self, func: Timer._F) -> Timer._F:
     """Allow the Timer to be used as a decorator.
@@ -493,10 +669,11 @@ class Timer:
 
     Returns:
       The wrapped function with timing behavior.
+
     """
 
     @functools.wraps(func)
-    def _Wrapper(*args: Any, **kwargs: Any) -> Any:
+    def _Wrapper(*args: Any, **kwargs: Any) -> Any:  # noqa: ANN401
       with self.__class__(self.label, emit_log=self.emit_log, emit_print=self.emit_print):
         return func(*args, **kwargs)
 
@@ -518,9 +695,10 @@ def RandBits(n_bits: int, /) -> int:
 
   Raises:
     InputError: invalid n_bits
+
   """
   # test inputs
-  if n_bits < 8:
+  if n_bits < 8:  # noqa: PLR2004
     raise InputError(f'n_bits must be ≥ 8: {n_bits}')
   # call underlying method
   n: int = 0
@@ -541,6 +719,7 @@ def RandInt(min_int: int, max_int: int, /) -> int:
 
   Raises:
     InputError: invalid min/max
+
   """
   # test inputs
   if min_int < 0 or min_int >= max_int:
@@ -548,11 +727,11 @@ def RandInt(min_int: int, max_int: int, /) -> int:
   # uniform over [min_int, max_int]
   span: int = max_int - min_int + 1
   n: int = min_int + secrets.randbelow(span)
-  assert min_int <= n <= max_int, 'should never happen: generated number out of range'
+  assert min_int <= n <= max_int, 'should never happen: generated number out of range'  # noqa: S101
   return n
 
 
-def RandShuffle[T: Any](seq: MutableSequence[T], /) -> None:
+def RandShuffle[T: Any](seq: abc.MutableSequence[T], /) -> None:
   """In-place Crypto-random shuffle order for `seq` mutable sequence.
 
   Args:
@@ -560,11 +739,12 @@ def RandShuffle[T: Any](seq: MutableSequence[T], /) -> None:
 
   Raises:
     InputError: not enough elements
+
   """
   # test inputs
-  if (n_seq := len(seq)) < 2:
+  if (n_seq := len(seq)) < 2:  # noqa: PLR2004
     raise InputError(f'seq must have 2 or more elements: {n_seq}')
-  # cryptographically sound Fisher–Yates using secrets.randbelow
+  # cryptographically sound Fisher-Yates using secrets.randbelow
   for i in range(n_seq - 1, 0, -1):
     j: int = secrets.randbelow(i + 1)
     seq[i], seq[j] = seq[j], seq[i]
@@ -581,13 +761,14 @@ def RandBytes(n_bytes: int, /) -> bytes:
 
   Raises:
     InputError: invalid n_bytes
+
   """
   # test inputs
   if n_bytes < 1:
     raise InputError(f'n_bytes must be ≥ 1: {n_bytes}')
   # return from system call
   b: bytes = secrets.token_bytes(n_bytes)
-  assert len(b) == n_bytes, 'should never happen: generated bytes incorrect size'
+  assert len(b) == n_bytes, 'should never happen: generated bytes incorrect size'  # noqa: S101
   return b
 
 
@@ -605,6 +786,7 @@ def GCD(a: int, b: int, /) -> int:
 
   Raises:
     InputError: invalid inputs
+
   """
   # test inputs
   if a < 0 or b < 0 or (not a and not b):
@@ -634,6 +816,7 @@ def ExtendedGCD(a: int, b: int, /) -> tuple[int, int, int]:
 
   Raises:
     InputError: invalid inputs
+
   """
   # test inputs
   if a < 0 or b < 0 or (not a and not b):
@@ -665,6 +848,7 @@ def Hash256(data: bytes, /) -> bytes:
     32 bytes (256 bits) of SHA-256 hash;
     if converted to hexadecimal (with BytesToHex() or hex()) will be 64 chars of string;
     if converted to int (big-endian, unsigned, with BytesToInt()) will be 0 ≤ i < 2**256
+
   """
   return hashlib.sha256(data).digest()
 
@@ -679,6 +863,7 @@ def Hash512(data: bytes, /) -> bytes:
     64 bytes (512 bits) of SHA-512 hash;
     if converted to hexadecimal (with BytesToHex() or hex()) will be 128 chars of string;
     if converted to int (big-endian, unsigned, with BytesToInt()) will be 0 ≤ i < 2**512
+
   """
   return hashlib.sha512(data).digest()
 
@@ -697,17 +882,18 @@ def FileHash(full_path: str, /, *, digest: str = 'sha256') -> bytes:
 
   Raises:
     InputError: file could not be found
+
   """
   # test inputs
   digest = digest.lower().strip().replace('-', '')  # normalize so we can accept e.g. "SHA-256"
-  if digest not in ('sha256', 'sha512'):
+  if digest not in {'sha256', 'sha512'}:
     raise InputError(f'unrecognized digest: {digest!r}')
   full_path = full_path.strip()
-  if not full_path or not os.path.exists(full_path):
+  if not full_path or not pathlib.Path(full_path).exists():
     raise InputError(f'file {full_path!r} not found for hashing')
   # compute hash
   logging.info(f'Hashing file {full_path!r}')
-  with open(full_path, 'rb') as file_obj:
+  with pathlib.Path(full_path).open('rb') as file_obj:
     return hashlib.file_digest(file_obj, digest).digest()
 
 
@@ -721,31 +907,36 @@ def ObfuscateSecret(data: str | bytes | int, /) -> str:
   Args:
     data (str | bytes | int): Data to obfuscate
 
+  Raises:
+      InputError: _description_
+
   Returns:
-    obfuscated string, e.g. "aabbccdd…"
+      str: obfuscated string, e.g. "aabbccdd…"
+
   """
   if isinstance(data, str):
     data = data.encode('utf-8')
   elif isinstance(data, int):
     data = IntToBytes(data)
-  if not isinstance(data, bytes):
+  if not isinstance(data, bytes):  # pyright: ignore[reportUnnecessaryIsInstance]
     raise InputError(f'invalid type for data: {type(data)}')
   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
+  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)
+  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.
+  r"""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
@@ -755,21 +946,23 @@ def BytesToRaw(b: bytes, /) -> str:
 
   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'\"')}"'
+  return f'"{inner.replace('"', r"\"")}"'
 
 
 def RawToBytes(s: str, /) -> bytes:
-  """Convert double-quoted string with \\xNN escapes where needed to bytes.
+  r"""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] == '"':
+  if len(s) >= 2 and s[0] == s[-1] == '"':  # noqa: PLR2004
     s = s[1:-1]
   # decode backslash escapes to code points, then map 0..255 -> bytes
   return codecs.decode(s, 'unicode_escape').encode('latin1')
@@ -784,21 +977,23 @@ def DetectInputType(data_str: str, /) -> CryptoInputType | None:
   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):
+    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
+def BytesFromInput(data_str: str, /, *, expect: CryptoInputType | None = None) -> bytes:  # noqa: C901, PLR0911, PLR0912
   """Parse input `data_str` into `bytes`. May auto-detect or enforce a type of input.
 
   Can load from disk ('@'). Can load from stdin ('@-').
@@ -815,6 +1010,7 @@ def BytesFromInput(data_str: str, /, *, expect: CryptoInputType | None = None) -
 
   Raises:
     InputError: unexpected type or conversion error
+
   """
   data_str = data_str.strip()
   # auto-detect
@@ -824,8 +1020,8 @@ def BytesFromInput(data_str: str, /, *, expect: CryptoInputType | None = None) -
     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
+  assert expect is not None, 'should never happen: type should be known here'  # noqa: S101
+  data_str = data_str.removeprefix(expect)
   # for every type something different will happen now
   try:
     match expect:
@@ -835,18 +1031,17 @@ def BytesFromInput(data_str: str, /, *, expect: CryptoInputType | None = None) -
         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')
+          if not isinstance(text, str):  # pyright: ignore[reportUnnecessaryIsInstance]
+            raise InputError('sys.stdin.read() produced non-text data')  # noqa: TRY301
           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')
+        if not isinstance(data, bytes):  # pyright: ignore[reportUnnecessaryIsInstance]
+          raise InputError('sys.stdin.buffer.read() produced non-binary data')  # noqa: TRY301
         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()
+        if not pathlib.Path(data_str).exists():
+          raise InputError(f'cannot find file {data_str!r}')  # noqa: TRY301
+        return pathlib.Path(data_str).read_bytes()
       case CryptoInputType.STR:
         return data_str.encode('utf-8')
       case CryptoInputType.HEX:
@@ -856,24 +1051,27 @@ def BytesFromInput(data_str: str, /, *, expect: CryptoInputType | None = None) -
       case CryptoInputType.RAW:
         return RawToBytes(data_str)
       case _:
-        raise InputError(f'invalid type {expect!r}')
+        raise InputError(f'invalid type {expect!r}')  # noqa: TRY301
   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):
+class CryptoKey(abstract.ABC):
   """A cryptographic key."""
 
+  @abstract.abstractmethod
   def __post_init__(self) -> None:
     """Check data."""
+    # every sub-class of CryptoKey has to implement its own version of __post_init__()
 
-  @abc.abstractmethod
+  @abstract.abstractmethod
   def __str__(self) -> str:
     """Safe (no secrets) string representation of the key.
 
     Returns:
       string representation of the key without leaking secrets
+
     """
     # every sub-class of CryptoKey has to implement its own version of __str__()
 
@@ -883,6 +1081,7 @@ class CryptoKey(abc.ABC):
 
     Returns:
       string representation of the key without leaking secrets
+
     """
     # concrete __repr__() delegates to the (abstract) __str__():
     # this avoids marking __repr__() abstract while still unifying behavior
@@ -898,12 +1097,13 @@ class CryptoKey(abc.ABC):
 
     Returns:
       string with all the object's fields explicit values
+
     """
     cls: str = type(self).__name__
     parts: list[str] = []
     for field in dataclasses.fields(self):
       val: Any = getattr(self, field.name)  # getattr is fine with frozen/slots
-      parts.append(f'{field.name}={repr(val)}')
+      parts.append(f'{field.name}={val!r}')
     return f'{cls}({", ".join(parts)})'
 
   @final
@@ -916,13 +1116,15 @@ class CryptoKey(abc.ABC):
 
     Raises:
       ImplementationError: object has types that are not supported in JSON
+
     """
     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}')
+          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])
@@ -936,8 +1138,6 @@ class CryptoKey(abc.ABC):
     Returns:
       str: JSON representation of the object, tightly packed
 
-    Raises:
-      ImplementationError: object has types that are not supported in JSON
     """
     return json.dumps(self._json_dict, separators=(',', ':'))
 
@@ -949,8 +1149,6 @@ class CryptoKey(abc.ABC):
     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)
 
@@ -967,9 +1165,11 @@ class CryptoKey(abc.ABC):
 
     Raises:
       InputError: unexpected type/fields
+      ImplementationError: unsupported JSON field
+
     """
     # check we got exactly the fields we needed
-    cls_fields: set[str] = set(f.name for f in dataclasses.fields(cls))
+    cls_fields: set[str] = {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=}')
@@ -977,7 +1177,8 @@ class CryptoKey(abc.ABC):
     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}')
+          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
@@ -996,10 +1197,11 @@ class CryptoKey(abc.ABC):
 
     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
+    if not isinstance(json_dict, dict):  # pyright: ignore[reportUnnecessaryIsInstance]
       raise InputError(f'JSON data decoded to unexpected type: {type(json_dict)}')
     return cls._FromJSONDict(json_dict)
 
@@ -1010,12 +1212,13 @@ class CryptoKey(abc.ABC):
 
     Returns:
       bytes, pickled, representation of the object
+
     """
     return self.Blob()
 
   @final
   def Blob(self, /, *, key: Encryptor | None = None, silent: bool = True) -> bytes:
-    """Serial (bytes) representation of the object with more options, including encryption.
+    """Get serial (bytes) representation of the object with more options, including encryption.
 
     Args:
       key (Encryptor, optional): if given will key.Encrypt() data before saving
@@ -1023,6 +1226,7 @@ class CryptoKey(abc.ABC):
 
     Returns:
       bytes, pickled, representation of the object
+
     """
     return Serialize(self._json_dict, compress=-2, key=key, silent=silent, pickler=PickleJSON)
 
@@ -1033,6 +1237,7 @@ class CryptoKey(abc.ABC):
 
     Returns:
       str, pickled, base64, representation of the object
+
     """
     return self.Encoded()
 
@@ -1046,6 +1251,7 @@ class CryptoKey(abc.ABC):
 
     Returns:
       str, pickled, base64, representation of the object
+
     """
     return CryptoInputType.BASE64 + BytesToEncoded(self.Blob(key=key, silent=silent))
 
@@ -1056,6 +1262,7 @@ class CryptoKey(abc.ABC):
 
     Returns:
       str, pickled, hexadecimal, representation of the object
+
     """
     return self.Hex()
 
@@ -1069,6 +1276,7 @@ class CryptoKey(abc.ABC):
 
     Returns:
       str, pickled, hexadecimal, representation of the object
+
     """
     return CryptoInputType.HEX + BytesToHex(self.Blob(key=key, silent=silent))
 
@@ -1079,6 +1287,7 @@ class CryptoKey(abc.ABC):
 
     Returns:
       str, pickled, raw escaped binary, representation of the object
+
     """
     return self.Raw()
 
@@ -1092,13 +1301,13 @@ class CryptoKey(abc.ABC):
 
     Returns:
       str, pickled, raw escaped binary, representation of the object
+
     """
     return CryptoInputType.RAW + BytesToRaw(self.Blob(key=key, silent=silent))
 
   @final
   @classmethod
-  def Load(
-      cls, data: str | bytes, /, *, key: Decryptor | None = None, silent: bool = True) -> Self:
+  def Load(cls, data: str | bytes, /, *, key: Decryptor | None = None, silent: bool = True) -> Self:
     """Load (create) object from serialized bytes or string.
 
     Args:
@@ -1109,6 +1318,10 @@ class CryptoKey(abc.ABC):
 
     Returns:
       a CryptoKey object ready for use
+
+    Raises:
+      InputError: decode error
+
     """
     # if this is a string, then we suppose it is base64
     if isinstance(data, str):
@@ -1116,15 +1329,16 @@ class CryptoKey(abc.ABC):
     # we now have bytes and we suppose it came from CryptoKey.blob()/CryptoKey.CryptoBlob()
     try:
       json_dict: dict[str, Any] = DeSerialize(
-          data=data, key=key, silent=silent, unpickler=UnpickleJSON)
+        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
-class Encryptor(Protocol):  # pylint: disable=too-few-public-methods
-  """Abstract interface for a class that has encryption
+class Encryptor(Protocol):
+  """Abstract interface for a class that has encryption.
 
   Contract:
     - If algorithm accepts a `nonce` or `tag` these have to be handled internally by the
@@ -1137,9 +1351,10 @@ class Encryptor(Protocol):  # pylint: disable=too-few-public-methods
     Metadata like nonce/tag may be:
       - returned alongside `ciphertext`/`signature`, or
       - bundled/serialized into `ciphertext`/`signature` by the implementation.
+
   """
 
-  @abc.abstractmethod
+  @abstract.abstractmethod
   def Encrypt(self, plaintext: bytes, /, *, associated_data: bytes | None = None) -> bytes:
     """Encrypt `plaintext` and return `ciphertext`.
 
@@ -1155,14 +1370,15 @@ class Encryptor(Protocol):  # pylint: disable=too-few-public-methods
     Raises:
       InputError: invalid inputs
       CryptoError: internal crypto failures
+
     """
 
 
 @runtime_checkable
-class Decryptor(Protocol):  # pylint: disable=too-few-public-methods
+class Decryptor(Protocol):
   """Abstract interface for a class that has decryption (see contract/notes in Encryptor)."""
 
-  @abc.abstractmethod
+  @abstract.abstractmethod
   def Decrypt(self, ciphertext: bytes, /, *, associated_data: bytes | None = None) -> bytes:
     """Decrypt `ciphertext` and return the original `plaintext`.
 
@@ -1176,16 +1392,18 @@ class Decryptor(Protocol):  # pylint: disable=too-few-public-methods
     Raises:
       InputError: invalid inputs
       CryptoError: internal crypto failures, authentication failure, key mismatch, etc
+
     """
 
 
 @runtime_checkable
-class Verifier(Protocol):  # pylint: disable=too-few-public-methods
+class Verifier(Protocol):
   """Abstract interface for asymmetric signature verify. (see contract/notes in Encryptor)."""
 
-  @abc.abstractmethod
+  @abstract.abstractmethod
   def Verify(
-      self, message: bytes, signature: bytes, /, *, associated_data: bytes | None = None) -> bool:
+    self, message: bytes, signature: bytes, /, *, associated_data: bytes | None = None
+  ) -> bool:
     """Verify a `signature` for `message`. True if OK; False if failed verification.
 
     Args:
@@ -1199,14 +1417,15 @@ class Verifier(Protocol):  # pylint: disable=too-few-public-methods
     Raises:
       InputError: invalid inputs
       CryptoError: internal crypto failures, authentication failure, key mismatch, etc
+
     """
 
 
 @runtime_checkable
-class Signer(Protocol):  # pylint: disable=too-few-public-methods
+class Signer(Protocol):
   """Abstract interface for asymmetric signing. (see contract/notes in Encryptor)."""
 
-  @abc.abstractmethod
+  @abstract.abstractmethod
   def Sign(self, message: bytes, /, *, associated_data: bytes | None = None) -> bytes:
     """Sign `message` and return the `signature`.
 
@@ -1222,13 +1441,20 @@ class Signer(Protocol):  # pylint: disable=too-few-public-methods
     Raises:
       InputError: invalid inputs
       CryptoError: internal crypto failures
+
     """
 
 
-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,
-    pickler: Callable[[Any], bytes] = PickleGeneric) -> bytes:
+def Serialize(
+  python_obj: Any,  # noqa: ANN401
+  /,
+  *,
+  file_path: str | None = None,
+  compress: int | None = 3,
+  key: Encryptor | None = None,
+  silent: bool = False,
+  pickler: abc.Callable[[Any], bytes] = PickleGeneric,
+) -> bytes:
   """Serialize a Python object into a BLOB, optionally compress / encrypt / save to disk.
 
   Data path is:
@@ -1240,14 +1466,14 @@ def Serialize(  # pylint:disable=too-many-arguments
 
   Compression levels / speed can be controlled by `compress`. Use this as reference:
 
-  | Level    | Speed       | Compression ratio                 | Typical use case                        |
-  | -------- | ------------| --------------------------------- | --------------------------------------- |
-  | -5 to -1 | Fastest     | Poor (better than no compression) | Real-time or very latency-sensitive     |
-  | 0…3      | Very fast   | Good ratio                        | Default CLI choice, safe baseline       |
-  | 4…6      | Moderate    | Better ratio                      | Good compromise for general persistence |
-  | 7…10     | Slower      | Marginally better ratio           | Only if storage space is precious       |
-  | 11…15    | Much slower | Slight gains                      | Large archives, not for runtime use     |
-  | 16…22    | Very slow   | Tiny gains                        | Archival-only, multi-GB datasets        |
+  | Level    | Speed       | Compression ratio       | Typical use case                        |
+  | -------- | ------------| ------------------------| --------------------------------------- |
+  | -5 to -1 | Fastest     | Poor (better than none) | Real-time / very latency-sensitive      |
+  | 0…3      | Very fast   | Good ratio              | Default CLI choice, safe baseline       |
+  | 4…6      | Moderate    | Better ratio            | Good compromise for general persistence |
+  | 7…10     | Slower      | Marginally better ratio | Only if storage space is precious       |
+  | 11…15    | Much slower | Slight gains            | Large archives, not for runtime use     |
+  | 16…22    | Very slow   | Tiny gains              | Archival-only, multi-GB datasets        |
 
   Args:
     python_obj (Any): serializable Python object
@@ -1262,6 +1488,7 @@ def Serialize(  # pylint:disable=too-many-arguments
 
   Returns:
     bytes: serialized binary data corresponding to obj + (compression) + (encryption)
+
   """
   messages: list[str] = []
   with Timer('Serialization complete', emit_log=False) as tm_all:
@@ -1272,8 +1499,8 @@ def Serialize(  # pylint:disable=too-many-arguments
       messages.append(f'    {tm_pickle}, {HumanizedBytes(len(obj))}')
     # compress, if needed
     if compress is not None:
-      compress = -22 if compress < -22 else compress
-      compress = 22 if compress > 22 else compress
+      compress = max(compress, -22)
+      compress = min(compress, 22)
       with Timer(f'COMPRESS@{compress}', emit_log=False) as tm_compress:
         obj = zstandard.ZstdCompressor(level=compress).compress(obj)
       if not silent:
@@ -1287,21 +1514,24 @@ def Serialize(  # pylint:disable=too-many-arguments
     # optionally save to disk
     if file_path is not None:
       with Timer('SAVE', emit_log=False) as tm_save:
-        with open(file_path, 'wb') as file_obj:
-          file_obj.write(obj)
+        pathlib.Path(file_path).write_bytes(obj)
       if not silent:
         messages.append(f'    {tm_save}, to {file_path!r}')
   # log and return
   if not silent:
-    logging.info(f'{tm_all}; parts:\n' + '\n'.join(messages))
+    logging.info(f'{tm_all}; parts:\n{"\n".join(messages)}')
   return obj
 
 
-def DeSerialize(
-    *, data: bytes | None = None, file_path: str | None = None,
-    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.
+def DeSerialize(  # noqa: C901
+  *,
+  data: bytes | None = None,
+  file_path: str | None = None,
+  key: Decryptor | None = None,
+  silent: bool = False,
+  unpickler: abc.Callable[[bytes], Any] = UnpickleGeneric,
+) -> Any:  # noqa: ANN401
+  """Load (de-serializes) a BLOB back to a Python object, optionally decrypting / decompressing.
 
   Data path is:
 
@@ -1312,15 +1542,17 @@ def DeSerialize(
   Compression versus no compression will be automatically detected.
 
   Args:
-    data (bytes, optional): if given, use this as binary data string (input);
-       if you use this option, `file_path` will be ignored
-    file_path (str, optional): if given, use this as file path to load binary data string (input);
-       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;
+    data (bytes | None, optional): if given, use this as binary data string (input);
+        if you use this option, `file_path` will be ignored
+    file_path (str | None, optional): if given, use this as file path to load binary data
+        string (input); if you use this option, `data` will be ignored. Defaults to None.
+    key (Decryptor | None, optional): if given will key.Decrypt() data before decompressing/loading.
+        Defaults to None.
+    silent (bool, optional): if True will not log; default is False (will log). Defaults to False.
+    unpickler (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
+        UnpickleGeneric is the default, but another useful value is UnpickleJSON.
+        Defaults to UnpickleGeneric.
 
   Returns:
     De-Serialized Python object corresponding to data
@@ -1328,24 +1560,24 @@ def DeSerialize(
   Raises:
     InputError: invalid inputs
     CryptoError: internal crypto failures, authentication failure, key mismatch, etc
-  """
+
+  """  # noqa: DOC502
   # test inputs
   if (data is None and file_path is None) or (data is not None and file_path is not None):
     raise InputError('you must provide only one of either `data` or `file_path`')
-  if file_path and not os.path.exists(file_path):
+  if file_path and not pathlib.Path(file_path).exists():
     raise InputError(f'invalid file_path: {file_path!r}')
-  if data and len(data) < 4:
+  if data and len(data) < 4:  # noqa: PLR2004
     raise InputError('invalid data: too small')
   # start the pipeline
-  obj: bytes = data if data else b''
+  obj: bytes = data or b''
   messages: list[str] = [f'DATA: {HumanizedBytes(len(obj))}'] if data and not silent else []
   with Timer('De-Serialization complete', emit_log=False) as tm_all:
     # optionally load from disk
     if file_path:
-      assert not obj, 'should never happen: if we have a file obj should be empty'
+      assert not obj, 'should never happen: if we have a file obj should be empty'  # noqa: S101
       with Timer('LOAD', emit_log=False) as tm_load:
-        with open(file_path, 'rb') as file_obj:
-          obj = file_obj.read()
+        obj = pathlib.Path(file_path).read_bytes()
       if not silent:
         messages.append(f'    {tm_load}, {HumanizedBytes(len(obj))}, from {file_path!r}')
     # decrypt, if needed
@@ -1355,16 +1587,19 @@ def DeSerialize(
       if not silent:
         messages.append(f'    {tm_crypto}, {HumanizedBytes(len(obj))}')
     # decompress: we try to detect compression to determine if we must call zstandard
-    if (len(obj) >= 4 and
-        (((magic := int.from_bytes(obj[:4], 'little')) == _ZSTD_MAGIC_FRAME) or
-         (_ZSTD_MAGIC_SKIPPABLE_MIN <= magic <= _ZSTD_MAGIC_SKIPPABLE_MAX))):
+    if (
+      len(obj) >= 4  # noqa: PLR2004
+      and (
+        ((magic := int.from_bytes(obj[:4], 'little')) == _ZSTD_MAGIC_FRAME)
+        or (_ZSTD_MAGIC_SKIPPABLE_MIN <= magic <= _ZSTD_MAGIC_SKIPPABLE_MAX)
+      )
+    ):
       with Timer('DECOMPRESS', emit_log=False) as tm_decompress:
         obj = zstandard.ZstdDecompressor().decompress(obj)
       if not silent:
         messages.append(f'    {tm_decompress}, {HumanizedBytes(len(obj))}')
-    else:
-      if not silent:
-        messages.append('    (no compression detected)')
+    elif not silent:
+      messages.append('    (no compression detected)')
     # create the actual object = unpickle
     with Timer('UNPICKLE', emit_log=False) as tm_unpickle:
       python_obj: Any = unpickler(obj)
@@ -1372,7 +1607,7 @@ def DeSerialize(
       messages.append(f'    {tm_unpickle}')
   # log and return
   if not silent:
-    logging.info(f'{tm_all}; parts:\n' + '\n'.join(messages))
+    logging.info(f'{tm_all}; parts:\n{"\n".join(messages)}')
   return python_obj
 
 
@@ -1390,6 +1625,7 @@ class PublicBid512(CryptoKey):
   Attributes:
     public_key (bytes): 512-bits random value
     public_hash (bytes): SHA-512 hash of (public_key || private_key || secret_bid)
+
   """
 
   public_key: bytes
@@ -1400,9 +1636,9 @@ class PublicBid512(CryptoKey):
 
     Raises:
       InputError: invalid inputs
+
     """
-    super(PublicBid512, self).__post_init__()  # pylint: disable=super-with-arguments  # needed here b/c: dataclass
-    if len(self.public_key) != 64 or len(self.public_hash) != 64:
+    if len(self.public_key) != 64 or len(self.public_hash) != 64:  # noqa: PLR2004
       raise InputError(f'invalid public_key or public_hash: {self}')
 
   def __str__(self) -> str:
@@ -1410,10 +1646,13 @@ class PublicBid512(CryptoKey):
 
     Returns:
       string representation of PublicBid
+
     """
-    return ('PublicBid512('
-            f'public_key={BytesToEncoded(self.public_key)}, '
-            f'public_hash={BytesToHex(self.public_hash)})')
+    return (
+      'PublicBid512('
+      f'public_key={BytesToEncoded(self.public_key)}, '
+      f'public_hash={BytesToHex(self.public_hash)})'
+    )
 
   def VerifyBid(self, private_key: bytes, secret: bytes, /) -> bool:
     """Verify a bid. True if OK; False if failed verification.
@@ -1425,21 +1664,30 @@ class PublicBid512(CryptoKey):
     Returns:
       True if bid is valid, False otherwise
 
-    Raises:
-      InputError: invalid inputs
     """
     try:
       # creating the PrivateBid object will validate everything; InputError we allow to propagate
       PrivateBid512(
-          public_key=self.public_key, public_hash=self.public_hash,
-          private_key=private_key, secret_bid=secret)
+        public_key=self.public_key,
+        public_hash=self.public_hash,
+        private_key=private_key,
+        secret_bid=secret,
+      )
       return True  # if we got here, all is good
     except CryptoError:
       return False  # bid does not match the public commitment
 
   @classmethod
   def Copy(cls, other: PublicBid512, /) -> Self:
-    """Initialize a public bid by taking the public parts of a public/private bid."""
+    """Initialize a public bid by taking the public parts of a public/private bid.
+
+    Args:
+        other (PublicBid512): the bid to copy from
+
+    Returns:
+        Self: an initialized PublicBid512
+
+    """
     return cls(public_key=other.public_key, public_hash=other.public_hash)
 
 
@@ -1450,6 +1698,7 @@ class PrivateBid512(PublicBid512):
   Attributes:
     private_key (bytes): 512-bits random value
     secret_bid (bytes): Any number of bytes (≥1) to bid on (e.g., UTF-8 encoded string)
+
   """
 
   private_key: bytes
@@ -1461,9 +1710,10 @@ class PrivateBid512(PublicBid512):
     Raises:
       InputError: invalid inputs
       CryptoError: bid does not match the public commitment
+
     """
-    super(PrivateBid512, self).__post_init__()  # pylint: disable=super-with-arguments  # needed here b/c: dataclass
-    if len(self.private_key) != 64 or len(self.secret_bid) < 1:
+    super(PrivateBid512, self).__post_init__()
+    if len(self.private_key) != 64 or len(self.secret_bid) < 1:  # noqa: PLR2004
       raise InputError(f'invalid private_key or secret_bid: {self}')
     if self.public_hash != Hash512(self.public_key + self.private_key + self.secret_bid):
       raise CryptoError(f'inconsistent bid: {self}')
@@ -1473,11 +1723,14 @@ class PrivateBid512(PublicBid512):
 
     Returns:
       string representation of PrivateBid without leaking secrets
+
     """
-    return ('PrivateBid512('
-            f'{super(PrivateBid512, self).__str__()}, '  # pylint: disable=super-with-arguments
-            f'private_key={ObfuscateSecret(self.private_key)}, '
-            f'secret_bid={ObfuscateSecret(self.secret_bid)})')
+    return (
+      'PrivateBid512('
+      f'{super(PrivateBid512, self).__str__()}, '
+      f'private_key={ObfuscateSecret(self.private_key)}, '
+      f'secret_bid={ObfuscateSecret(self.secret_bid)})'
+    )
 
   @classmethod
   def New(cls, secret: bytes, /) -> Self:
@@ -1491,199 +1744,175 @@ class PrivateBid512(PublicBid512):
 
     Raises:
       InputError: invalid inputs
+
     """
     # test inputs
     if len(secret) < 1:
       raise InputError(f'invalid secret length: {len(secret)}')
     # generate random values
-    public_key: bytes = RandBytes(64)   # 512 bits
+    public_key: bytes = RandBytes(64)  # 512 bits
     private_key: bytes = RandBytes(64)  # 512 bits
     # build object
     return cls(
-        public_key=public_key,
-        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.
+      public_key=public_key,
+      public_hash=Hash512(public_key + private_key + secret),
+      private_key=private_key,
+      secret_bid=secret,
+    )
+
+
+@dataclasses.dataclass(kw_only=True, slots=True, frozen=True)
+class CLIConfig:
+  """CLI global context, storing the configuration."""
+
+  console: rich_console.Console
+  verbose: int
+  color: bool | None
+
+
+def CLIErrorGuard[**P](fn: abc.Callable[P, None], /) -> abc.Callable[P, None]:
+  """Guard CLI command functions.
+
+  Returns:
+    A wrapped function that catches expected user-facing errors and prints them consistently.
+
+  """
+
+  @functools.wraps(fn)
+  def _Wrapper(*args: P.args, **kwargs: P.kwargs) -> None:
+    try:
+      # call the actual function
+      fn(*args, **kwargs)
+    except (Error, ValueError) as err:
+      # get context
+      ctx: object | None = dict(kwargs).get('ctx')
+      if not isinstance(ctx, typer.Context):
+        ctx = next((a for a in args if isinstance(a, typer.Context)), None)
+      # print error nicely
+      if isinstance(ctx, typer.Context):
+        # we have context
+        obj: CLIConfig = cast('CLIConfig', ctx.obj)
+        if obj.verbose >= 2:  # verbose >= 2 means INFO level or more verbose  # noqa: PLR2004
+          obj.console.print_exception()  # print full traceback
+        else:
+          obj.console.print(str(err))  # print only error message
+      # no context
+      elif logging.getLogger().getEffectiveLevel() < logging.INFO:
+        Console().print(str(err))  # print only error message (DEBUG level is verbose already)
+      else:
+        Console().print_exception()  # print full traceback (less verbose mode needs it)
+
+  return _Wrapper
+
+
+def _ClickWalk(
+  command: click.Command,
+  ctx: typer.Context,
+  path: list[str],
+  /,
+) -> abc.Iterator[tuple[list[str], click.Command, typer.Context]]:
+  """Recursively walk Click commands/groups.
+
+  Yields:
+    tuple[list[str], click.Command, typer.Context]: path, command, ctx
+
+  """
+  yield (path, command, ctx)  # yield self
+  # now walk subcommands, if any
+  sub_cmd: click.Command | None
+  sub_ctx: typer.Context
+  # prefer the explicit `.commands` mapping when present; otherwise fall back to
+  # click's `list_commands()`/`get_command()` for dynamic groups
+  if not isinstance(command, click.Group):
+    return
+  # explicit commands mapping
+  if command.commands:
+    for name, sub_cmd in sorted(command.commands.items()):
+      sub_ctx = typer.Context(sub_cmd, info_name=name, parent=ctx)
+      yield from _ClickWalk(sub_cmd, sub_ctx, [*path, name])
+    return
+  # dynamic commands
+  for name in sorted(command.list_commands(ctx)):
+    sub_cmd = command.get_command(ctx, name)
+    if sub_cmd is None:
+      continue  # skip invalid subcommands
+    sub_ctx = typer.Context(sub_cmd, info_name=name, parent=ctx)
+    yield from _ClickWalk(sub_cmd, sub_ctx, [*path, name])
+
+
+def GenerateTyperHelpMarkdown(
+  typer_app: typer.Typer,
+  /,
+  *,
+  prog_name: str,
+  heading_level: int = 1,
+  code_fence_language: str = 'text',
+) -> str:
+  """Capture `--help` for a Typer CLI and all subcommands as Markdown.
+
+  This function converts a Typer app to its underlying Click command tree and then:
+  - invokes `--help` for the root ("Main") command
+  - walks commands/subcommands recursively
+  - invokes `--help` for each command path
+
+  It emits a Markdown document with a heading per command and a fenced block
+  containing the exact `--help` output.
+
+  Notes:
+    - This uses Click's `CliRunner().invoke(...)` for faithful output.
+    - The walk is generic over Click `MultiCommand`/`Group` structures.
+    - If a command cannot be loaded, it is skipped.
 
   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
+    typer_app: The Typer app (e.g. `app`).
+    prog_name: Program name used in usage strings (e.g. "profiler").
+    heading_level: Markdown heading level for each command section.
+    code_fence_language: Language tag for fenced blocks (default: "text").
 
   Returns:
-    str: markdown
+    Markdown string.
 
-  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()
+  # prepare Click root command and context
+  click_root: click.Command = typer.main.get_command(typer_app)
+  root_ctx: typer.Context = typer.Context(click_root, info_name=prog_name)
+  runner = click_testing.CliRunner()
+  parts: list[str] = []
+  for path, _, _ in _ClickWalk(click_root, root_ctx, []):
+    # build command path
+    command_path: str = ' '.join([prog_name, *path]).strip()
+    heading_prefix: str = '#' * max(1, heading_level + len(path))
+    ResetConsole()  # ensure clean state for each command (also it raises on duplicate loggers)
+    # invoke --help for this command path
+    result: click_testing.Result = runner.invoke(
+      click_root,
+      [*path, '--help'],
+      prog_name=prog_name,
+      color=False,
+    )
+    if result.exit_code != 0 and not result.output:
+      continue  # skip invalid commands
+    # build markdown section
+    global_prefix: str = (  # only for the top-level command
+      (
+        '<!-- cspell:disable -->\n'
+        '<!-- auto-generated; DO NOT EDIT! see base.GenerateTyperHelpMarkdown() -->\n\n'
+      )
+      if not path
+      else ''
+    )
+    extras: str = (  # type of command, by level
+      ('Command-Line Interface' if not path else 'Command') if len(path) <= 1 else 'Sub-Command'
+    )
+    parts.extend(
+      (
+        f'{global_prefix}{heading_prefix} `{command_path}` {extras}',
+        '',
+        f'```{code_fence_language}',
+        result.output.strip(),
+        '```',
+        '',
+      )
+    )
+  # join all parts and return
+  return '\n'.join(parts).rstrip()