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

transcrypto/__init__.py

@@ -3,5 +3,5 @@
 """Basic cryptography primitives implementation."""
 
 __all__: list[str] = ['__author__', '__version__']
-__version__ = '1.7.0'  # remember to also update pyproject.toml
+__version__ = '1.8.0'  # remember to also update pyproject.toml
 __author__ = 'Daniel Balparda <balparda@github.com>'

transcrypto/base.py

@@ -15,12 +15,10 @@ import hashlib
 import json
 import logging
 import math
-import os
 import pathlib
 import pickle  # noqa: S403
 import secrets
 import sys
-import threading
 import time
 from collections import abc
 from types import TracebackType
@@ -28,23 +26,39 @@ from typing import (
   Any,
   Protocol,
   Self,
-  TypeVar,
   cast,
   final,
   runtime_checkable,
 )
 
-import click
 import numpy as np
-import typer
 import zstandard
-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
 
+# JSON types
+type JSONValue = bool | int | float | str | list[JSONValue] | dict[str, JSONValue] | None
+type JSONDict = dict[str, JSONValue]
+
+# Crypto types: add bytes for cryptographic data; has to be encoded for JSON serialization
+type CryptValue = bool | int | float | str | bytes | list[CryptValue] | dict[str, CryptValue] | None
+type CryptDict = dict[str, CryptValue]
+_JSON_DATACLASS_TYPES: set[str] = {
+  # native support
+  'int',
+  'float',
+  'str',
+  'bool',
+  # support for lists for now, but no nested lists or dicts yet
+  'list[int]',
+  'list[float]',
+  'list[str]',
+  'list[bool]',
+  # need conversion/encoding: see CryptValue/CryptDict
+  'bytes',
+}
+
 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')
@@ -67,26 +81,6 @@ TimeStr: abc.Callable[[int | float | None], str] = lambda tm: (
 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
@@ -109,29 +103,15 @@ _SI_PREFIXES: dict[int, str] = {
 _PICKLE_PROTOCOL = 4  # protocol 4 available since python v3.8 # do NOT ever change!
 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'))
+PickleJSON: abc.Callable[[JSONDict], bytes] = lambda d: json.dumps(d, separators=(',', ':')).encode(
+  'utf-8'
+)
+UnpickleJSON: abc.Callable[[bytes], JSONDict] = 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):
@@ -150,112 +130,6 @@ class ImplementationError(Error, NotImplementedError):
   """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
-
-  """
-  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).
 
@@ -562,18 +436,24 @@ class Timer:
   """
 
   def __init__(
-    self, label: str = '', /, *, emit_log: bool = True, emit_print: bool = False
+    self,
+    label: str = '',
+    /,
+    *,
+    emit_log: bool = True,
+    emit_print: abc.Callable[[str], None] | None = None,
   ) -> None:
     """Initialize the Timer.
 
     Args:
       label (str, optional): A description or name for the timed block or function
       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
+      emit_print (Callable[[str], None] | None, optional): Emit a print() message when
+          finished using the provided callable; default is None
 
     """
     self.emit_log: bool = emit_log
-    self.emit_print: bool = emit_print
+    self.emit_print: abc.Callable[[str], None] | None = emit_print
     self.label: str = label.strip()
     self.start: float | None = None
     self.end: float | None = None
@@ -647,8 +527,8 @@ class Timer:
     message: str = str(self)
     if self.emit_log:
       logging.info(message)
-    if self.emit_print:
-      Console().print(message)
+    if self.emit_print is not None:
+      self.emit_print(message)
 
   def __exit__(
     self,
@@ -659,9 +539,7 @@ class Timer:
     """Stop the timer when exiting the context."""
     self.Stop()
 
-  _F = TypeVar('_F', bound=abc.Callable[..., Any])
-
-  def __call__(self, func: Timer._F) -> Timer._F:
+  def __call__[**F, R](self, func: abc.Callable[F, R]) -> abc.Callable[F, R]:
     """Allow the Timer to be used as a decorator.
 
     Args:
@@ -673,11 +551,11 @@ class Timer:
     """
 
     @functools.wraps(func)
-    def _Wrapper(*args: Any, **kwargs: Any) -> Any:  # noqa: ANN401
+    def _Wrapper(*args: F.args, **kwargs: F.kwargs) -> R:
       with self.__class__(self.label, emit_log=self.emit_log, emit_print=self.emit_print):
         return func(*args, **kwargs)
 
-    return _Wrapper  # type:ignore
+    return _Wrapper
 
 
 def RandBits(n_bits: int, /) -> int:
@@ -731,7 +609,7 @@ def RandInt(min_int: int, max_int: int, /) -> int:
   return n
 
 
-def RandShuffle[T: Any](seq: abc.MutableSequence[T], /) -> None:
+def RandShuffle[T](seq: abc.MutableSequence[T], /) -> None:
   """In-place Crypto-random shuffle order for `seq` mutable sequence.
 
   Args:
@@ -1108,17 +986,17 @@ class CryptoKey(abstract.ABC):
 
   @final
   @property
-  def _json_dict(self) -> dict[str, Any]:
+  def _json_dict(self) -> JSONDict:
     """Dictionary representation of the object suitable for JSON conversion.
 
     Returns:
-      dict[str, Any]: representation of the object suitable for JSON conversion
+      JSONDict: representation of the object suitable for JSON conversion
 
     Raises:
       ImplementationError: object has types that are not supported in JSON
 
     """
-    self_dict: dict[str, Any] = dataclasses.asdict(self)
+    self_dict: CryptDict = dataclasses.asdict(self)
     for field in dataclasses.fields(self):
       # check the type is OK
       if field.type not in _JSON_DATACLASS_TYPES:
@@ -1127,8 +1005,8 @@ class CryptoKey(abstract.ABC):
         )
       # 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
+        self_dict[field.name] = BytesToEncoded(cast('bytes', self_dict[field.name]))
+    return cast('JSONDict', self_dict)
 
   @final
   @property
@@ -1154,11 +1032,11 @@ class CryptoKey(abstract.ABC):
 
   @final
   @classmethod
-  def _FromJSONDict(cls, json_dict: dict[str, Any], /) -> Self:
+  def _FromJSONDict(cls, json_dict: JSONDict, /) -> Self:
     """Create object from JSON representation.
 
     Args:
-      json_dict (dict[str, Any]): JSON dict
+      json_dict (JSONDict): JSON dict
 
     Returns:
       a CryptoKey object ready for use
@@ -1180,7 +1058,7 @@ class CryptoKey(abstract.ABC):
           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])
+        json_dict[field.name] = EncodedToBytes(json_dict[field.name])  # type: ignore[assignment, arg-type]
     # build the object
     return cls(**json_dict)
 
@@ -1200,7 +1078,7 @@ class CryptoKey(abstract.ABC):
 
     """
     # get the dict back
-    json_dict: dict[str, Any] = json.loads(json_data)
+    json_dict: JSONDict = json.loads(json_data)
     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)
@@ -1328,9 +1206,7 @@ class CryptoKey(abstract.ABC):
       data = BytesFromInput(data)
     # 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
-      )
+      json_dict: JSONDict = 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
@@ -1445,15 +1321,15 @@ class Signer(Protocol):
     """
 
 
-def Serialize(
-  python_obj: Any,  # noqa: ANN401
+def Serialize[T](
+  python_obj: T,
   /,
   *,
   file_path: str | None = None,
   compress: int | None = 3,
   key: Encryptor | None = None,
   silent: bool = False,
-  pickler: abc.Callable[[Any], bytes] = PickleGeneric,
+  pickler: abc.Callable[[T], bytes] = PickleGeneric,
 ) -> bytes:
   """Serialize a Python object into a BLOB, optionally compress / encrypt / save to disk.
 
@@ -1523,14 +1399,14 @@ def Serialize(
   return obj
 
 
-def DeSerialize(  # noqa: C901
+def DeSerialize[T](  # 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
+  unpickler: abc.Callable[[bytes], T] = UnpickleGeneric,
+) -> T:
   """Load (de-serializes) a BLOB back to a Python object, optionally decrypting / decompressing.
 
   Data path is:
@@ -1602,7 +1478,7 @@ def DeSerialize(  # noqa: C901
       messages.append('    (no compression detected)')
     # create the actual object = unpickle
     with Timer('UNPICKLE', emit_log=False) as tm_unpickle:
-      python_obj: Any = unpickler(obj)
+      python_obj: T = unpickler(obj)
     if not silent:
       messages.append(f'    {tm_unpickle}')
   # log and return
@@ -1759,160 +1635,3 @@ class PrivateBid512(PublicBid512):
       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:
-    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:
-    Markdown string.
-
-  """
-  # 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()

transcrypto/cli/__init__.py

@@ -0,0 +1,3 @@
+# SPDX-FileCopyrightText: Copyright 2026 Daniel Balparda <balparda@github.com>
+# SPDX-License-Identifier: Apache-2.0
+"""CLI logic."""