log21 3.4.0__tar.gz → 3.6.0__tar.gz

{log21-3.4.0 → log21-3.6.0}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.3
 Name: log21
-Version: 3.4.0
+Version: 3.6.0
 Summary: A simple logging package
 Keywords: python,log,colorize,color,logging,Python3,CodeWriter21
 Author: CodeWriter21(Mehrad Pooryoussof)
@@ -29,7 +29,6 @@ log21
 
 ![version](https://img.shields.io/pypi/v/log21)
 [![pipeline status](https://gitlab.com/CodeWriter21/log21/badges/master/pipeline.svg)](https://gitlab.com/CodeWriter21/log21/-/commits/master)
-[![repo size](https://img.shields.io/gitlab/repo-size/CodeWriter21/log21)](https://gitlab.com/CodeWriter21/log21)
 
 A simple logging package that helps you log colorized messages in Windows console and
 other operating systems.

{log21-3.4.0 → log21-3.6.0}/README.md

@@ -3,7 +3,6 @@ log21
 
 ![version](https://img.shields.io/pypi/v/log21)
 [![pipeline status](https://gitlab.com/CodeWriter21/log21/badges/master/pipeline.svg)](https://gitlab.com/CodeWriter21/log21/-/commits/master)
-[![repo size](https://img.shields.io/gitlab/repo-size/CodeWriter21/log21)](https://gitlab.com/CodeWriter21/log21)
 
 A simple logging package that helps you log colorized messages in Windows console and
 other operating systems.

{log21-3.4.0 → log21-3.6.0}/pyproject.toml

@@ -23,7 +23,7 @@ dependencies = [
     "webcolors",
     "docstring-parser"
 ]
-version = "3.4.0"
+version = "3.6.0"
 
 [build-system]
 requires = ["uv_build>=0.8.15,<0.9.0"]

{log21-3.4.0 → log21-3.6.0}/src/log21/__init__.py

@@ -33,7 +33,7 @@ from .stream_handler import StreamHandler, ColorizingStreamHandler
 # yapf: enable
 
 __author__ = 'CodeWriter21 (Mehrad Pooryoussof)'
-__version__ = '3.4.0'
+__version__ = '3.6.0'
 __github__ = 'https://GitHub.com/MPCodeWriter21/log21'
 __all__ = [
     'ColorizingStreamHandler', 'DecolorizingFileHandler', 'ColorizingFormatter',

{log21-3.4.0 → log21-3.6.0}/src/log21/argumentify.py

@@ -4,11 +4,13 @@
 # yapf: disable
 
 import re as _re
+import os as _os
 import string as _string
 import asyncio as _asyncio
 import inspect as _inspect
 import types as _stdlib_types
 import collections.abc as _collections_abc
+from getpass import getpass as _stdlib_getpass
 from typing import (Any as _Any, Set as _Set, Dict as _Dict, List as _List,
                     Tuple as _Tuple, Union as _Union, Callable as _Callable,
                     Optional as _Optional, Awaitable as _Awaitable,
@@ -18,6 +20,8 @@ from dataclasses import field as _field, dataclass as _dataclass
 from docstring_parser import Docstring as _Docstring, parse as _parse
 
 import log21.argparse as _argparse
+import log21._argparse as _vendored_argparse
+from log21.helper_types import Secret as _Secret
 
 # yapf: enable
 
@@ -228,6 +232,7 @@ class Argument:
     annotation: _Any = _inspect._empty
     default: _Any = _inspect._empty
     help: _Optional[str] = None
+    has_default: bool = False
 
     def __post_init__(self) -> None:
         """Sets the some values to None if they are empty."""
@@ -262,6 +267,7 @@ class FunctionInfo:
                 kind=parameter.kind,
                 default=parameter.default,
                 annotation=parameter.annotation,
+                has_default=parameter.default is not _inspect._empty,
             )
 
         self.docstring = _parse(self.function.__doc__ or '')
@@ -384,6 +390,168 @@ def _is_repeatable_flag(argument: Argument) -> bool:
     return is_list
 
 
+def _secret_params(
+    annotation: _Any
+) -> _Tuple[bool, _Any, _Optional[str], _Optional[bool], bool]:
+    """Inspect an annotation for `Secret` parameters.
+
+    Unwraps `Optional[...]` / `... | None` spellings first, so
+    `Secret[str] | None` behaves like `Optional[Secret[str]]`.
+
+    :param annotation: The parameter annotation to inspect.
+    :return: An `(is_secret, value_type, env_var, prompt, optional)` tuple.
+    """
+    if annotation is None:
+        return False, str, None, None, False
+    optional = False
+    args = getattr(annotation, '__args__', None)
+    none_type = getattr(_stdlib_types, 'NoneType', None)
+    if (args is not None and none_type is not None and len(args) == 2
+            and (args[0] is none_type or args[1] is none_type)):
+        optional = True
+        annotation = args[1] if args[0] is none_type else args[0]
+    # Parameterized secrets are `Secret` subclasses, so `Optional[...]` and
+    # `... | None` keep working natively.
+    if isinstance(annotation, type) and issubclass(annotation, _Secret):
+        return (
+            True, annotation.value_type, annotation.env_var, annotation.prompt,
+            optional
+        )
+    return False, str, None, None, optional
+
+
+def _is_required_secret(argument: Argument) -> bool:
+    """Check whether a secret parameter must resolve to a value.
+
+    Only bare `Secret[...]` annotations without a declared default are
+    required; `Optional` spellings and declared defaults make them optional.
+    """
+    is_secret, _, _, _, optional = _secret_params(argument.annotation)
+    return is_secret and not optional and not argument.has_default
+
+
+def _secret_converter(value_type: type) -> _Callable[[str], _Secret]:
+    """Build an `argparse` type converter producing `Secret` values.
+
+    Conversion failures raise `ArgumentTypeError` with a fixed message, so
+    neither `argparse` nor tracebacks ever echo the secret value.
+
+    :param value_type: The type each raw value is converted to.
+    """
+
+    def convert(raw: str) -> _Secret:
+        try:
+            return _Secret(raw, value_type=value_type)
+        except (ValueError, TypeError):
+            raise _vendored_argparse.ArgumentTypeError('invalid Secret value') from None
+
+    convert.__name__ = 'Secret'
+    return convert
+
+
+def _prompt_secret(prompt_text: str) -> _Optional[str]:
+    """Securely prompt for a secret value (hidden input).
+
+    Separated for testability; returns `None` when input is unavailable
+    instead of raising.
+
+    :param prompt_text: The prompt to display.
+    :return: The entered value, or `None` on end-of-file / OS errors.
+    """
+    try:
+        return _stdlib_getpass(prompt_text)
+    except (EOFError, OSError):
+        return None
+
+
+def _env_var_for(
+    argument_name: str, params_env_var: _Optional[str],
+    env_prefix: _Optional[str]
+) -> _Optional[str]:
+    """Derive the environment variable for a secret parameter.
+
+    A per-parameter override wins; otherwise `{PREFIX}_{NAME}` is derived
+    from the app-wide prefix. With neither, no environment lookup happens.
+    """
+    if params_env_var:
+        return params_env_var
+    if env_prefix:
+        return f'{env_prefix}_{argument_name.upper()}'
+    return None
+
+
+def _resolve_secrets(
+    cli_args: _Any,
+    info: FunctionInfo,
+    parser: _Any,
+    env_prefix: _Optional[str] = None,
+    secret_prompt: bool = True
+) -> None:
+    """Resolve secret parameters: flag value, environment, prompt, default.
+
+    For every `Secret`-annotated parameter still `None` after parsing (flag
+    absent), consult the environment variable, then a secure prompt (unless
+    disabled globally or per-parameter), then the declared default. Required
+    secrets missing after the whole chain are parser errors. Values are
+    always wrapped as `Secret`, and no error message ever includes one.
+
+    Repeatable (`list[Secret[str]]`) flags only get per-item conversion at
+    parse time; the chain does not apply to them.
+
+    :param cli_args: The parsed arguments namespace.
+    :param info: The function info.
+    :param parser: The parser (for redacted errors).
+    :param env_prefix: App-wide environment prefix, e.g. `"PDF_HELPER"`.
+    :param secret_prompt: Whether missing secrets may prompt securely.
+    """
+    for argument in info.arguments.values():
+        if _is_repeatable_flag(argument):
+            continue
+        is_secret, value_type, params_env, params_prompt, _ = _secret_params(
+            argument.annotation
+        )
+        if not is_secret:
+            continue
+        value = getattr(cli_args, argument.name, None)
+        if value is not None:
+            if not isinstance(value, _Secret):
+                try:
+                    value = _Secret(value, value_type=value_type)
+                    setattr(cli_args, argument.name, value)
+                except (ValueError, TypeError):
+                    parser.error('invalid Secret value')
+            continue
+        env_name = _env_var_for(argument.name, params_env, env_prefix)
+        env_value = _os.environ.get(env_name) if env_name else None
+        if env_value is not None:
+            try:
+                value = _Secret(env_value, value_type=value_type)
+            except (ValueError, TypeError):
+                parser.error('invalid Secret value')
+        else:
+            want_prompt = params_prompt if params_prompt is not None else secret_prompt
+            if want_prompt:
+                given = _prompt_secret(f'Enter {argument.name}: ')
+                if given is not None:
+                    try:
+                        value = _Secret(given, value_type=value_type)
+                    except (ValueError, TypeError):
+                        parser.error('invalid Secret value')
+            if value is None:
+                if argument.default is not None:
+                    try:
+                        value = _Secret(argument.default, value_type=value_type)
+                    except (ValueError, TypeError):
+                        parser.error('invalid Secret value')
+                elif _is_required_secret(argument):
+                    hint = f' (or set {env_name})' if env_name else ''
+                    parser.error(
+                        'the following arguments are required: '
+                        f'{argument.name}{hint}'
+                    )
+        setattr(cli_args, argument.name, value)
+
+
 def _normalize_exclusive_groups(
     mutually_exclusive: _Any
 ) -> _List[_Tuple[_List[str], bool]]:
@@ -450,18 +618,21 @@ def _normalize_exclusive_groups(
 
 def _resolve_command_groups(
     mutually_exclusive: _Any, command: _Optional[str],
-    argument_names: _Set[str]
+    argument_names: _Set[str], strict: bool = True
 ) -> _List[_Tuple[_List[str], bool]]:
     """Resolve which exclusive groups apply to a single command parser.
 
     `mutually_exclusive` may be a plain list of groups (broadcast to every
     command that defines all named parameters) or a `{command_name: groups}`
     mapping for targeted groups. Unknown parameter names and groups that
-    match no command raise `ValueError`.
+    match no command raise `ValueError` (unless `strict` is disabled, in
+    which case non-matching groups are silently skipped for this command —
+    used for nested trees where a global check runs instead).
 
     :param mutually_exclusive: The raw `mutually_exclusive` value.
     :param command: The command name, or `None` for a single-function parser.
     :param argument_names: The parameter names of the command.
+    :param strict: Raise when a broadcast list matches this command nowhere.
     :raises ValueError: If a group references unknown parameters.
     :return: The groups applying to this command.
     """
@@ -486,12 +657,22 @@ def _resolve_command_groups(
                 )
         _check_group_overlap(groups, command)
         return groups
+    return _resolve_broadcast_groups(
+        mutually_exclusive, command, argument_names, strict=strict
+    )
+
+
+def _resolve_broadcast_groups(
+    mutually_exclusive: _Any, command: _Optional[str],
+    argument_names: _Set[str], strict: bool = True
+) -> _List[_Tuple[_List[str], bool]]:
+    """Resolve broadcast groups against one command's parameters."""
     groups = _normalize_exclusive_groups(mutually_exclusive)
     applicable = [
         group for group in groups
         if all(name in argument_names for name in group[0])
     ]
-    if groups and not applicable:
+    if strict and groups and not applicable:
         # A broadcast list that matches nowhere is almost certainly a typo:
         # fail fast instead of silently ignoring it.
         missing = [
@@ -594,13 +775,26 @@ def _add_arguments(
             'help': argument.help
         }
         flags = generate_flag(argument, reserved_flags=reserved_flags)
+        is_secret, secret_type, _, _, _ = _secret_params(argument.annotation)
         if argument.annotation is bool:
             config['action'] = 'store_true'
+        elif is_secret and not _is_repeatable_flag(argument):
+            # Direct secret: converted with redacted errors. Registered with
+            # an internal `None` default; flag value, environment, prompt and
+            # declared default are resolved by `_resolve_secrets` after
+            # parsing, so secrets are never argparse-required (a required
+            # flag would pre-empt the environment/prompt fallbacks).
+            config['type'] = _secret_converter(secret_type)
+            config['default'] = None
         elif _is_repeatable_flag(argument):
             _, element = _list_element_type(argument.annotation)
             config['action'] = 'append'
             if element is not None:
-                config['type'] = element
+                element_secret, element_type, _, _, _ = _secret_params(element)
+                if element_secret:
+                    config['type'] = _secret_converter(element_type)
+                else:
+                    config['type'] = element
             # Registered with an internal `None` default so `argparse` never
             # mutates the signature's default list; the declared default is
             # restored by `_apply_repeatable_defaults` after parsing.
@@ -609,11 +803,25 @@ def _add_arguments(
             config['type'] = argument.annotation
         if argument.kind == _inspect._ParameterKind.POSITIONAL_ONLY:
             flags = [config.pop('dest')]
-            is_list, _ = _list_element_type(argument.annotation)
-            if is_list and config.get('nargs') is None and argument.default is not None:
-                # A declared default (e.g. `= []`) makes the multi-value
-                # positional optional instead of requiring 1+ values.
-                config['nargs'] = '*'
+            is_list, element = _list_element_type(argument.annotation)
+            if is_list:
+                element_secret, element_type, _, _, _ = _secret_params(element)
+                if element_secret:
+                    # `list[Secret[T]]` positionals: convert each item with
+                    # redacted errors. The converter replaces the annotation,
+                    # so nargs is set here instead of `_validate_func_type`.
+                    config['type'] = _secret_converter(element_type)
+                    if config.get('nargs') is None:
+                        config['nargs'] = '*' if argument.default is not None else '+'
+                elif config.get('nargs') is None and argument.default is not None:
+                    # A declared default (e.g. `= []`) makes the multi-value
+                    # positional optional instead of requiring 1+ values.
+                    config['nargs'] = '*'
+            if is_secret:
+                # Secret positionals accept zero values so the
+                # environment/prompt chain in `_resolve_secrets` can fire;
+                # missing required secrets become parser errors there.
+                config['nargs'] = '?'
             if any(argument.name in names for names, _ in exclusive_groups or []):
                 # `argparse` only accepts optional actions in mutually
                 # exclusive groups: single-value positionals become `nargs='?'`
@@ -626,9 +834,13 @@ def _add_arguments(
         if argument.kind == _inspect._ParameterKind.VAR_POSITIONAL:
             config['nargs'] = '*'
             flags = [config.pop('dest')]
-        if argument.kind == _inspect._ParameterKind.POSITIONAL_OR_KEYWORD and keyword_only_exists:
+            if is_secret:
+                config['type'] = _secret_converter(secret_type)
+        if (argument.kind == _inspect._ParameterKind.POSITIONAL_OR_KEYWORD
+                and keyword_only_exists and not is_secret):
             config['required'] = True
-        if argument.default is not None and config.get('action') != 'append':
+        if (argument.default is not None and config.get('action') != 'append'
+                and not is_secret):
             config['default'] = argument.default
         target = parser
         for index, (names, _) in enumerate(exclusive_groups or []):
@@ -639,7 +851,10 @@ def _add_arguments(
 
 
 def _argumentify_one(
-    func: Callable, mutually_exclusive: _Any = None
+    func: Callable,
+    mutually_exclusive: _Any = None,
+    env_prefix: _Optional[str] = None,
+    secret_prompt: bool = True
 ) -> None:
     """This function argumentifies one function as the entry point of the script.
 
@@ -647,6 +862,8 @@ def _argumentify_one(
     :param mutually_exclusive: A list of mutually exclusive groups. Each
         group is a list of parameter names or a
         `{"names": [...], "required": bool}` mapping.
+    :param env_prefix: App-wide environment prefix for `Secret` parameters.
+    :param secret_prompt: Whether missing secrets may prompt securely.
     """
     info = FunctionInfo(func)
 
@@ -659,6 +876,7 @@ def _argumentify_one(
     _add_arguments(parser, info, exclusive_groups=groups)
     cli_args = parser.parse_args()
     _apply_repeatable_defaults(cli_args, info)
+    _resolve_secrets(cli_args, info, parser, env_prefix, secret_prompt)
     args = []
     kwargs = {}
     for argument in info.arguments.values():
@@ -678,52 +896,258 @@ def _argumentify_one(
         parser.error(error.message)
 
 
+def _normalize_command_node(node: _Any, path: _Tuple[str, ...] = ()) -> _Dict[str, _Any]:
+    """Validate an entry-point node and normalize it to a command tree.
+
+    Leaves are callables, inner nodes are (possibly nested) mappings or lists
+    of callables. Returns `{name: callable-or-mapping}` with lists converted
+    to mappings keyed by function name.
+
+    :param node: The mapping, list or callable to normalize.
+    :param path: The dotted path of `node` within the tree (for errors).
+    :raises TypeError: If a value is neither a function nor a mapping/list.
+    :raises ValueError: If a group defines no subcommands.
+    :return: The normalized `{name: ...}` mapping.
+    """
+    label = '.'.join(path) if path else '<root>'
+    if isinstance(node, _List):
+        normalized: _Dict[str, _Any] = {}
+        for func in node:
+            if not callable(func):
+                raise TypeError(
+                    "argumentify: func must be a function or a list of functions or a "
+                    "dictionary of functions."
+                )
+            normalized[func.__name__] = func
+        return normalized
+    if isinstance(node, _Dict):
+        normalized = {}
+        for name, child in node.items():
+            if callable(child):
+                normalized[name] = child
+            elif isinstance(child, (_Dict, _List)):
+                sub = _normalize_command_node(child, (*path, name))
+                if not sub:
+                    raise ValueError(
+                        f'Command group {".".join((*path, name))!r} defines '
+                        'no subcommands.'
+                    )
+                normalized[name] = sub
+            else:
+                raise TypeError(
+                    "argumentify: func must be a function or a list of functions or a "
+                    "dictionary of functions."
+                )
+        return normalized
+    raise TypeError(
+        "argumentify: func must be a function or a list of functions or a "
+        f"dictionary of functions (got {label!r})."
+    )
+
+
+def _collect_leaves(
+    node: _Dict[str, _Any], path: _Tuple[str, ...] = ()
+) -> _List[_Tuple[str, str, Callable]]:
+    """Collect `(dotted_path, name, function)` leaves of a command tree."""
+    leaves: _List[_Tuple[str, str, Callable]] = []
+    for name, child in node.items():
+        if callable(child):
+            leaves.append(('.'.join((*path, name)), name, child))
+        else:
+            leaves.extend(_collect_leaves(child, (*path, name)))
+    return leaves
+
+
+def _validate_mutex_keys(mutually_exclusive: _Any, leaf_paths: _List[str]) -> None:
+    """Reject mutex mapping keys that match no leaf command.
+
+    Keys may be full dotted paths (`"metadata.edit"`) or plain leaf names
+    (`"edit"`).
+
+    :param mutually_exclusive: The raw `mutually_exclusive` value.
+    :param leaf_paths: Dotted paths of all leaf commands.
+    :raises ValueError: If a key matches nothing.
+    """
+    if not isinstance(mutually_exclusive, _Dict):
+        return
+    leaf_names = {path.split('.')[-1] for path in leaf_paths}
+    for key in mutually_exclusive:
+        if key in leaf_paths or key in leaf_names:
+            continue
+        raise ValueError(
+            f'mutually_exclusive references unknown command {key!r} '
+            f'(known commands: {sorted(leaf_paths)}).'
+        )
+
+
+def _resolve_leaf_groups(
+    mutually_exclusive: _Any, dotted: str, leaf: str, argument_names: _Set[str],
+    leaf_paths: _List[str]
+) -> _List[_Tuple[_List[str], bool]]:
+    """Resolve the exclusive groups applying to one leaf command.
+
+    Plain lists broadcast to every leaf defining all named parameters. For
+    mappings, an exact dotted-path key wins; otherwise a leaf-name key
+    applies when it is unique across the tree (ambiguous leaf names raise
+    `ValueError` suggesting dotted paths).
+
+    :param mutually_exclusive: The raw `mutually_exclusive` value.
+    :param dotted: The dotted path of the leaf (e.g. `"metadata.edit"`).
+    :param leaf: The leaf command name.
+    :param argument_names: The parameter names of the leaf.
+    :param leaf_paths: Dotted paths of all leaf commands.
+    :raises ValueError: If a group references unknown parameters.
+    :return: The groups applying to this leaf.
+    """
+    if mutually_exclusive is None:
+        return []
+    if isinstance(mutually_exclusive, _Dict):
+        if dotted in mutually_exclusive:
+            raw = mutually_exclusive[dotted]
+        elif leaf in mutually_exclusive:
+            same = sorted(p for p in leaf_paths if p.split('.')[-1] == leaf)
+            if len(same) > 1:
+                raise ValueError(
+                    f'Mutually exclusive key {leaf!r} is ambiguous between '
+                    f'commands {same}; use dotted paths instead.'
+                )
+            raw = mutually_exclusive[leaf]
+        else:
+            return []
+        groups = _normalize_exclusive_groups(raw)
+        for names, _ in groups:
+            unknown = [name for name in names if name not in argument_names]
+            if unknown:
+                raise ValueError(
+                    f'Mutually exclusive group {names!r} references unknown '
+                    f'parameters of command {dotted!r}: {unknown!r}'
+                )
+        _check_group_overlap(groups, dotted)
+        return groups
+    return _resolve_broadcast_groups(
+        mutually_exclusive, dotted, argument_names, strict=False
+    )
+
+
+def _validate_broadcast_groups(
+    mutually_exclusive: _Any, leaf_infos: _Dict[str, FunctionInfo]
+) -> None:
+    """Reject broadcast groups that match no leaf command at all.
+
+    Called once per tree (nested parsers skip non-matching groups silently,
+    so without this a typo'd group would vanish without a trace).
+
+    :param mutually_exclusive: The raw `mutually_exclusive` value.
+    :param leaf_infos: `{dotted_path: FunctionInfo}` for every leaf.
+    :raises ValueError: If a group matches nowhere.
+    """
+    if mutually_exclusive is None or isinstance(mutually_exclusive, _Dict):
+        return
+    arg_sets = [set(info.arguments) for info in leaf_infos.values()]
+    for names, _ in _normalize_exclusive_groups(mutually_exclusive):
+        if not any(all(name in arg_set for name in names) for arg_set in arg_sets):
+            raise ValueError(
+                f'Mutually exclusive group {names!r} matches no command.'
+            )
+
+
+def _add_command_level(
+    subparsers: _Any,
+    node: _Dict[str, _Any],
+    path: _Tuple[str, ...],
+    leaf_infos: _Dict[str, FunctionInfo],
+    mutually_exclusive: _Any = None,
+    leaf_paths: _Optional[_List[str]] = None
+) -> None:
+    """Add one command-tree level to a subparsers action (recursively).
+
+    Leaf commands get annotation-driven arguments (plus any applicable
+    mutually exclusive groups); group nodes get a nested `add_subparsers`
+    level of their own, so `prog group --help` lists the group's commands.
+    """
+    for name, child in node.items():
+        if callable(child):
+            dotted = '.'.join((*path, name))
+            info = leaf_infos[dotted]
+            subparser = subparsers.add_parser(name, help=info.docstring.description)
+            groups = _resolve_leaf_groups(
+                mutually_exclusive, dotted, name, set(info.arguments),
+                leaf_paths or [dotted]
+            )
+            _add_arguments(subparser, info, exclusive_groups=groups)
+            subparser.set_defaults(func=info.function)
+        else:
+            group_parser = subparsers.add_parser(name)
+            nested = group_parser.add_subparsers(required=True)
+            _add_command_level(
+                nested, child, (*path, name), leaf_infos, mutually_exclusive,
+                leaf_paths
+            )
+
+
 def _argumentify(
-    functions: _Dict[str, Callable], mutually_exclusive: _Any = None
+    functions: _Dict[str, _Any],
+    mutually_exclusive: _Any = None,
+    env_prefix: _Optional[str] = None,
+    secret_prompt: bool = True
 ) -> None:
     """This function argumentifies one or more functions as the entry point of the
     script.
 
+    `functions` is a command tree: values are either callables (leaf commands)
+    or nested mappings/lists (command groups), at any depth.
+
     :param functions: A dictionary of functions to argumentify.
     :param mutually_exclusive: A list of mutually exclusive groups broadcast
         to every command defining all named parameters, or a
         `{command_name: groups}` mapping for targeted groups. Each group is a
         list of parameter names or a `{"names": [...], "required": bool}`
         mapping.
+    :param env_prefix: App-wide environment prefix for `Secret` parameters,
+        e.g. `"PDF_HELPER"` derives `PDF_HELPER_PASSWORD` from `--password`.
+    :param secret_prompt: Whether missing secrets may fall back to a secure
+        prompt (per-parameter `Secret[..., prompt]` overrides this).
     :raises RuntimeError:
     """
-    functions_info: _Dict[str, _Tuple[Callable, FunctionInfo]] = {}
-    for name, function in functions.items():
-        functions_info[name] = (function, FunctionInfo(function))
+    tree = _normalize_command_node(functions)
+    if not tree:
+        raise ValueError('argumentify: no entry points defined.')
+    leaves = _collect_leaves(tree)
+    leaf_infos: _Dict[str, FunctionInfo] = {}
+    ordered: _List[_Tuple[Callable, FunctionInfo]] = []
+    for dotted, name, function in leaves:
+        info = FunctionInfo(function)
+        leaf_infos[dotted] = info
 
         # Check if the function has a VAR_KEYWORD argument
         # Raises a ArgumentTypeError if it does
-        for argument in functions_info[name][1].arguments.values():
+        for argument in info.arguments.values():
             if argument.kind == _inspect._ParameterKind.VAR_KEYWORD:
                 raise ArgumentTypeError(
-                    f"Function {name} has `**{argument.name}` argument, "
+                    f"Function {dotted} has `**{argument.name}` argument, "
                     "which is not supported.",
                     unsupported_arg=argument.name
                 )
+        ordered.append((function, info))
     parser = _argparse.ColorizingArgumentParser()
     subparsers = parser.add_subparsers(required=True)
-    for name, (_, info) in functions_info.items():
-        subparser = subparsers.add_parser(name, help=info.docstring.description)
-        groups = _resolve_command_groups(
-            mutually_exclusive, name, set(info.arguments)
-        )
-        _add_arguments(subparser, info, exclusive_groups=groups)
-        subparser.set_defaults(func=info.function)
+    leaf_paths = [dotted for dotted, _, _ in leaves]
+    _validate_mutex_keys(mutually_exclusive, leaf_paths)
+    _validate_broadcast_groups(mutually_exclusive, leaf_infos)
+    _add_command_level(
+        subparsers, tree, (), leaf_infos, mutually_exclusive, leaf_paths
+    )
     cli_args = parser.parse_args()
     args = []
     kwargs = {}
     info = None
-    for _name, (function, info) in functions_info.items():  # noqa: B007
+    for function, info in ordered:
         if function == cli_args.func:
             break
     else:
         raise RuntimeError('No function found for the given arguments.')
     _apply_repeatable_defaults(cli_args, info)
+    _resolve_secrets(cli_args, info, parser, env_prefix, secret_prompt)
     for argument in info.arguments.values():
         if argument.kind in (_inspect._ParameterKind.POSITIONAL_ONLY,
                              _inspect._ParameterKind.POSITIONAL_OR_KEYWORD):
@@ -742,9 +1166,11 @@ def _argumentify(
 
 
 def argumentify(
-    entry_point: _Union[Callable, _List[Callable], _Dict[str, Callable]],
-    mutually_exclusive: _Optional[_Any] = None
-) -> _Union[Callable, _List[Callable], _Dict[str, Callable]]:
+    entry_point: _Union[Callable, _List[Callable], _Dict[str, _Any]],
+    mutually_exclusive: _Optional[_Any] = None,
+    env_prefix: _Optional[str] = None,
+    secret_prompt: bool = True
+) -> _Union[Callable, _List[Callable], _Dict[str, _Any]]:
     """This function argumentifies one or more functions as the entry point of the
     script.
 
@@ -787,7 +1213,9 @@ def argumentify(
 
     For multiple entry points, pass a `{command_name: groups}` mapping, or a
     plain list of groups which applies to every command defining all named
-    parameters. Positional parameters in a group accept zero values (single
+    parameters. With nested commands, mapping keys may be dotted paths
+    (`"metadata.edit"`) or — when unique across the tree — plain leaf names.
+    Positional parameters in a group accept zero values (single
     ones behave like `nargs='?'`, multi-value ones like `nargs='*'`) and
     receive their default (or `None`) when omitted; pass
     `{"names": [...], "required": True}` when exactly one of them must be
@@ -798,8 +1226,44 @@ def argumentify(
             mutually_exclusive={"run-recipe": [["recipe_path", "builtin"]]},
         )
 
+    Related commands can be grouped under a group verb by nesting mappings
+    (to any depth), giving `git`-style `prog <group> <action>` interfaces
+    where each level gets its own subcommands and `--help`:
+
+        argumentify({
+            "bundle": bundle_entry_point,
+            "metadata": {
+                "show": show_entry_point,
+                "clear": clear_entry_point,
+                "edit": edit_entry_point,
+            },
+        })
+
+    $ pdf-helper metadata edit in.pdf out.pdf --title "Report"
+
+    Group nodes take no function: nothing executes until a leaf command is
+    chosen. A list of functions may be used wherever a mapping is expected;
+    empty groups raise `ValueError`.
+
+    Parameters annotated with `Secret[T]` (`log21.helper_types.Secret`) are
+    secrets: values resolve from the flag, then an environment variable, then
+    a secure (hidden-input) prompt, then the declared default. The variable
+    is a per-parameter override (`Secret[str, "PDF_HELPER_PASSWORD"]`) or
+    derived from `env_prefix` (`argumentify(..., env_prefix="PDF_HELPER")`
+    derives `PDF_HELPER_PASSWORD` from `--password`). Prompting happens for
+    missing secrets unless disabled globally (`secret_prompt=False`) or
+    per-parameter (`Secret[str, "ENV", False]`); required secrets missing
+    after the whole chain are errors. Secrets never appear in log21 errors:
+
+        from log21.helper_types import Secret
+
+        def encrypt(in_path, out_path, /, password: Secret[str] | None = None): ...
+        argumentify(encrypt, env_prefix="PDF_HELPER")
+
     :param entry_point: The function(s) to argumentify.
     :param mutually_exclusive: Mutually exclusive parameter groups.
+    :param env_prefix: App-wide environment prefix for `Secret` parameters.
+    :param secret_prompt: Whether missing secrets may prompt securely.
     :raises TypeError: A function must be a function or a list of functions or a
         dictionary of functions.
     :raises ValueError: A group is malformed or references unknown parameters.
@@ -808,7 +1272,7 @@ def argumentify(
     functions = {}
     # Check the types
     if callable(entry_point):
-        _argumentify_one(entry_point, mutually_exclusive)
+        _argumentify_one(entry_point, mutually_exclusive, env_prefix, secret_prompt)
         return entry_point
     if isinstance(entry_point, _List):
         for func in entry_point:
@@ -819,12 +1283,6 @@ def argumentify(
                 )
             functions[func.__name__] = func
     elif isinstance(entry_point, _Dict):
-        for func in entry_point.values():
-            if not callable(func):
-                raise TypeError(
-                    "argumentify: func must be a function or a list of functions or a "
-                    "dictionary of functions."
-                )
         functions = entry_point
     else:
         raise TypeError(
@@ -832,5 +1290,5 @@ def argumentify(
             "dictionary of functions."
         )
 
-    _argumentify(functions, mutually_exclusive)
+    _argumentify(functions, mutually_exclusive, env_prefix, secret_prompt)
     return entry_point

log21-3.6.0/src/log21/helper_types.py

@@ -0,0 +1,252 @@
+# log21.helper_types.py
+# CodeWriter21
+"""A collection of useful types meant for using with argument parser to parse CLI
+arguments to more usable formats.
+
++ FileSize: Can take `str` and `int` values. Will convert human inputs such as "121 KB",
+  "21MiB", or "4.56 GB" to bytes. Can also be used to represent bytes value in more
+  human-readable formats.
++ Secret: Wraps a sensitive value (e.g. a password) so it is never echoed back:
+  `str()` and `repr()` are redacted and conversion errors never include the value.
+  `Secret[T]`, `Secret[T, "ENV_VAR"]` and `Secret[T, "ENV_VAR", prompt]` describe
+  the value type, an environment-variable fallback and prompting for `argumentify`.
+"""
+
+# yapf: disable
+
+import re as _re
+from math import log as _log
+from functools import lru_cache as _lru_cache
+from typing import Union as _Union, SupportsInt as _SupportsInt, Any as _Any
+
+# yapf: enable
+
+__all__ = ["FileSize", "Secret"]
+
+POWERS = "KMGTPEZYRQ"
+FILE_SIZE_PATTERN = _re.compile(rf"^([+-]?[0-9]+(?:\.[0-9]+)?)\s*(|[{POWERS}])(i?)B$")
+
+
+class FileSize:
+
+    def __init__(self, value: _Union[int, str]) -> None:
+        """An interface for converting different inputs to file-size (bytes).
+
+        :param value: int value in bytes or a string such as "100 KB", "20MiB", or "1.23
+            GB"
+        :raises TypeError: If the value is not of type int or str
+        :raises ValueError: If the str value does not match the file-size pattern:
+            ^([+-]?[0-9]+(?:\\.[0-9]+)?)\\s*(|[KMGTPEZYRQ])(i?)B$
+        """
+        if isinstance(value, int):
+            self.bytes = value
+        elif isinstance(value, str):
+            match = FILE_SIZE_PATTERN.match(value)
+            if not match:
+                raise ValueError(f"Input does not match the file-size pattern: {value}")
+            val, prefix, binary = match.groups()
+            power = POWERS.index(prefix) + 1
+            assert power is not None
+            self.bytes = int(float(val) * (1024 if binary else 1000)**power)
+        else:
+            raise TypeError(f"Input to FileSize() can be int or str, not {type(value)}")
+
+    def humanize(
+        self,
+        binary: bool = False,
+        gnu: bool = False,
+        fmt: str = "%.2f",
+    ) -> str:
+        """Returns the size in a human readable way."""
+        base = 1024 if (gnu or binary) else 1000
+        abs_bytes = abs(self.bytes)
+
+        if abs_bytes == 1 and not gnu:
+            return f"{self.bytes} Byte"
+
+        if abs_bytes < base:
+            return f"{self.bytes}B" if gnu else f"{self.bytes} Bytes"
+
+        power = int(min(_log(abs_bytes, base), len(POWERS)))
+        result: str = fmt % (self.bytes / (base**power))
+        if gnu:
+            return result + POWERS[power - 1]
+        result += " " + POWERS[power - 1]
+        if binary:
+            result += "i"
+        result += "B"
+        return result
+
+    @property
+    def KB(self) -> float:
+        return self.bytes / 1000
+
+    @property
+    def MB(self) -> float:
+        return self.bytes / 1000_000
+
+    @property
+    def GB(self) -> float:
+        return self.bytes / 1000_000_000
+
+    @property
+    def KiB(self) -> float:
+        return self.bytes / 1024
+
+    @property
+    def MiB(self) -> float:
+        return self.bytes / 1048576
+
+    @property
+    def GiB(self) -> float:
+        return self.bytes / 1073741824
+
+    def __int__(self) -> int:
+        return self.bytes
+
+    def __eq__(self, value: object) -> bool:
+        if not isinstance(value, _SupportsInt):
+            return False
+        return self.bytes == int(value)
+
+    def __lt__(self, value: _SupportsInt) -> bool:
+        return self.bytes < int(value)
+
+    def __le__(self, value: _SupportsInt) -> bool:
+        return self.bytes <= int(value)
+
+    def __gt__(self, value: _SupportsInt) -> bool:
+        return int(value) < self.bytes
+
+    def __ge__(self, value: _SupportsInt) -> bool:
+        return int(value) <= self.bytes
+
+    def __add__(self, value: _SupportsInt) -> "FileSize":
+        return FileSize(self.bytes + int(value))
+
+    def __str__(self) -> str:
+        return self.humanize(binary=True)
+
+    def __repr__(self) -> str:
+        return f"<{self.__class__.__name__}: '{self!s}'>"
+
+
+class Secret:
+    """A sensitive value (e.g. a password) that is never echoed back.
+
+    `str(secret)` and `repr(secret)` are redacted, and conversion errors never
+    include the value, so the secret cannot leak through logs, tracebacks, or
+    `argparse` error messages. Read the value via the `value` attribute.
+
+    Subscription describes a secret parameter and returns a `Secret`
+    subclass, so `Optional[...]` and `... | None` keep working natively:
+    `Secret[T]`, `Secret[T, "ENV_VAR"]` or `Secret[T, "ENV_VAR", prompt]`,
+    where `prompt` (default `None`, meaning "inherit the global setting")
+    controls whether a missing value falls back to a secure prompt.
+    """
+
+    value_type: type = str
+    env_var: _Union[str, None] = None
+    prompt: _Union[bool, None] = None
+
+    def __init__(
+        self, value: _Any = '', value_type: _Union[type, None] = None
+    ) -> None:
+        """Wrap a value as a secret, converting it to `value_type`.
+
+        :param value: The secret value (usually a string from the CLI).
+        :param value_type: The type to convert the value to (default: the
+            class-level `value_type`, i.e. `str` for plain `Secret`).
+        :raises ValueError: If the value cannot be converted. The message
+            never includes the value itself.
+        """
+        if value_type is None:
+            value_type = type(self).value_type
+        if isinstance(value, Secret):
+            value = value.value
+        try:
+            self._value = value if isinstance(value, value_type) else value_type(value)
+        except (ValueError, TypeError) as error:
+            raise ValueError('invalid Secret value') from error
+        self._value_type = value_type
+
+    def __class_getitem__(cls, params: _Any) -> type:
+        """Describe a secret parameter: `Secret[T]`, `Secret[T, "ENV_VAR"]` or
+        `Secret[T, "ENV_VAR", prompt]`.
+
+        Returns a `Secret` subclass carrying the parameters, so the result
+        stays a real type (`Optional[...]`, `... | None`, `isinstance` and
+        `issubclass` all keep working).
+        """
+        if not isinstance(params, tuple):
+            params = (params, )
+        if len(params) > 3:
+            raise TypeError(
+                'Secret accepts at most a value type, an environment variable '
+                'name and a prompt flag: Secret[T], Secret[T, "ENV_VAR"] or '
+                'Secret[T, "ENV_VAR", prompt].'
+            )
+        value_type = params[0] if len(params) > 0 else str
+        env_var = params[1] if len(params) > 1 else None
+        prompt = params[2] if len(params) > 2 else None
+        if not isinstance(value_type, type):
+            raise TypeError(
+                'Secret value type must be a type, '
+                f'not {type(value_type).__name__}.'
+            )
+        if env_var is not None and not isinstance(env_var, str):
+            raise TypeError(
+                'Secret environment variable name must be a string or None, '
+                f'not {type(env_var).__name__}.'
+            )
+        if prompt is not None and not isinstance(prompt, bool):
+            raise TypeError(
+                'Secret prompt flag must be a bool or None, '
+                f'not {type(prompt).__name__}.'
+            )
+        return _secret_subclass(value_type, env_var, prompt)
+
+    @property
+    def value(self) -> _Any:
+        """The wrapped (converted) secret value."""
+        return self._value
+
+    def __str__(self) -> str:
+        return '***'
+
+    def __repr__(self) -> str:
+        return "Secret('***')"
+
+    def __bool__(self) -> bool:
+        return bool(self._value)
+
+    def __eq__(self, other: object) -> bool:
+        if isinstance(other, Secret):
+            return self._value == other._value
+        return self._value == other
+
+    def __hash__(self) -> int:
+        return hash((self._value_type, self._value))
+
+
+@_lru_cache(maxsize=None)
+def _secret_subclass(
+    value_type: type, env_var: _Union[str, None], prompt: _Union[bool, None]
+) -> type:
+    """Build (and cache) the `Secret` subclass for one parameter shape.
+
+    Cached so identical subscriptions return the identical class.
+    """
+    parts = [value_type.__name__]
+    if env_var is not None or prompt is not None:
+        parts.append(repr(env_var))
+    if prompt is not None:
+        parts.append(repr(prompt))
+    name = f"Secret[{', '.join(parts)}]"
+    namespace = {
+        'value_type': value_type,
+        'env_var': env_var,
+        'prompt': prompt,
+        '__module__': __name__,
+    }
+    return type(name, (Secret, ), namespace)

log21-3.4.0/src/log21/helper_types.py

@@ -1,126 +0,0 @@
-# log21.helper_types.py
-# CodeWriter21
-"""A collection of useful types meant for using with argument parser to parse CLI
-arguments to more usable formats.
-
-+ FileSize: Can take `str` and `int` values. Will convert human inputs such as "121 KB",
-  "21MiB", or "4.56 GB" to bytes. Can also be used to represent bytes value in more
-  human-readable formats.
-"""
-
-# yapf: disable
-
-import re as _re
-from math import log as _log
-from typing import Union as _Union, SupportsInt as _SupportsInt
-
-# yapf: enable
-
-__all__ = ["FileSize"]
-
-POWERS = "KMGTPEZYRQ"
-FILE_SIZE_PATTERN = _re.compile(rf"^([+-]?[0-9]+(?:\.[0-9]+)?)\s*(|[{POWERS}])(i?)B$")
-
-
-class FileSize:
-
-    def __init__(self, value: _Union[int, str]) -> None:
-        """An interface for converting different inputs to file-size (bytes).
-
-        :param value: int value in bytes or a string such as "100 KB", "20MiB", or "1.23
-            GB"
-        :raises TypeError: If the value is not of type int or str
-        :raises ValueError: If the str value does not match the file-size pattern:
-            ^([+-]?[0-9]+(?:\\.[0-9]+)?)\\s*(|[KMGTPEZYRQ])(i?)B$
-        """
-        if isinstance(value, int):
-            self.bytes = value
-        elif isinstance(value, str):
-            match = FILE_SIZE_PATTERN.match(value)
-            if not match:
-                raise ValueError(f"Input does not match the file-size pattern: {value}")
-            val, prefix, binary = match.groups()
-            power = POWERS.index(prefix) + 1
-            assert power is not None
-            self.bytes = int(float(val) * (1024 if binary else 1000)**power)
-        else:
-            raise TypeError(f"Input to FileSize() can be int or str, not {type(value)}")
-
-    def humanize(
-        self,
-        binary: bool = False,
-        gnu: bool = False,
-        fmt: str = "%.2f",
-    ) -> str:
-        """Returns the size in a human readable way."""
-        base = 1024 if (gnu or binary) else 1000
-        abs_bytes = abs(self.bytes)
-
-        if abs_bytes == 1 and not gnu:
-            return f"{self.bytes} Byte"
-
-        if abs_bytes < base:
-            return f"{self.bytes}B" if gnu else f"{self.bytes} Bytes"
-
-        power = int(min(_log(abs_bytes, base), len(POWERS)))
-        result: str = fmt % (self.bytes / (base**power))
-        if gnu:
-            return result + POWERS[power - 1]
-        result += " " + POWERS[power - 1]
-        if binary:
-            result += "i"
-        result += "B"
-        return result
-
-    @property
-    def KB(self) -> float:
-        return self.bytes / 1000
-
-    @property
-    def MB(self) -> float:
-        return self.bytes / 1000_000
-
-    @property
-    def GB(self) -> float:
-        return self.bytes / 1000_000_000
-
-    @property
-    def KiB(self) -> float:
-        return self.bytes / 1024
-
-    @property
-    def MiB(self) -> float:
-        return self.bytes / 1048576
-
-    @property
-    def GiB(self) -> float:
-        return self.bytes / 1073741824
-
-    def __int__(self) -> int:
-        return self.bytes
-
-    def __eq__(self, value: object) -> bool:
-        if not isinstance(value, _SupportsInt):
-            return False
-        return self.bytes == int(value)
-
-    def __lt__(self, value: _SupportsInt) -> bool:
-        return self.bytes < int(value)
-
-    def __le__(self, value: _SupportsInt) -> bool:
-        return self.bytes <= int(value)
-
-    def __gt__(self, value: _SupportsInt) -> bool:
-        return int(value) < self.bytes
-
-    def __ge__(self, value: _SupportsInt) -> bool:
-        return int(value) <= self.bytes
-
-    def __add__(self, value: _SupportsInt) -> "FileSize":
-        return FileSize(self.bytes + int(value))
-
-    def __str__(self) -> str:
-        return self.humanize(binary=True)
-
-    def __repr__(self) -> str:
-        return f"<{self.__class__.__name__}: '{self!s}'>"