log21 3.5.0__tar.gz → 3.7.0__tar.gz

{log21-3.5.0 → log21-3.7.0}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.3
 Name: log21
-Version: 3.5.0
+Version: 3.7.0
 Summary: A simple logging package
 Keywords: python,log,colorize,color,logging,Python3,CodeWriter21
 Author: CodeWriter21(Mehrad Pooryoussof)

{log21-3.5.0 → log21-3.7.0}/pyproject.toml

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

{log21-3.5.0 → log21-3.7.0}/src/log21/__init__.py

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

{log21-3.5.0 → log21-3.7.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]]:
@@ -552,11 +720,114 @@ def _apply_repeatable_defaults(cli_args: _Any, info: FunctionInfo) -> None:
             setattr(cli_args, argument.name, argument.default)
 
 
+def _normalize_common(common: _Any) -> _Dict[str, Argument]:
+    """Normalize the `common` mapping into synthetic flag arguments.
+
+    Each entry is either a plain default (`{"force": False}`, type inferred
+    as `bool`/`str`/`int`/`float`, `None` for untyped) or a spec mapping with
+    `default`, `annotation` (`type` accepted as an alias), and `help` keys.
+    Every entry becomes an optional `--flag` on leaves that don't declare the
+    name themselves.
+
+    :param common: The raw `common` value.
+    :raises TypeError: If `common` is not a mapping.
+    :raises ValueError: If a name or spec is malformed, or a spec is
+        `Secret`-typed (declare `Secret[...]` in the entry-point signatures
+        that need it; `env_prefix` already applies globally).
+    :return: `{name: Argument}` shared flag definitions.
+    """
+    if common is None:
+        return {}
+    if not isinstance(common, _Dict):
+        raise TypeError(
+            'common must be a mapping of parameter name to default or spec '
+            f'mapping, not {type(common).__name__}.'
+        )
+    normalized: _Dict[str, Argument] = {}
+    for name, spec in common.items():
+        if not isinstance(name, str) or not name.isidentifier():
+            raise ValueError(
+                'Common parameter names must be valid identifiers, '
+                f'got: {name!r}'
+            )
+        if isinstance(spec, _Dict):
+            unknown = set(spec) - {'default', 'annotation', 'type', 'help'}
+            if unknown:
+                raise ValueError(
+                    f'Unknown keys for common parameter {name!r}: '
+                    f'{sorted(unknown)!r} (allowed: default, annotation, help).'
+                )
+            annotation = spec.get('annotation', spec.get('type'))
+            if 'annotation' in spec and 'type' in spec and spec['annotation'] is not spec['type']:
+                raise ValueError(
+                    f"Common parameter {name!r} sets both 'annotation' and "
+                    "'type' to different values."
+                )
+            default = spec.get('default')
+            has_default = 'default' in spec
+            help_text = spec.get('help')
+        else:
+            if isinstance(spec, list):
+                raise ValueError(
+                    f'Common parameter {name!r} needs a dict spec with an '
+                    "'annotation' for list values, e.g. "
+                    f'{{"{name}": {{"annotation": list[str], "default": []}}}}.'
+                )
+            if spec is not None and not isinstance(spec, (bool, str, int, float)):
+                raise ValueError(
+                    f'Unsupported default for common parameter {name!r}: '
+                    f'{type(spec).__name__} (use a bool/str/int/float/None '
+                    'default or a dict spec).'
+                )
+            annotation = None if spec is None else type(spec)
+            default, has_default, help_text = spec, True, None
+        is_secret, _, _, _, _ = _secret_params(annotation)
+        if not is_secret:
+            _, element = _list_element_type(annotation)
+            is_secret = _secret_params(element)[0] if element is not None else False
+        if is_secret:
+            raise ValueError(
+                f'Common parameter {name!r} must not be Secret-typed: declare '
+                'Secret[...] in the entry-point signatures that need it '
+                '(they take precedence, and env_prefix applies globally).'
+            )
+        normalized[name] = Argument(
+            name=name,
+            kind=_inspect._ParameterKind.POSITIONAL_OR_KEYWORD,
+            annotation=annotation,
+            default=default,
+            help=help_text,
+            has_default=has_default,
+        )
+    return normalized
+
+
+def _validate_common_names(
+    common: _Dict[str, Argument], leaf_infos: _Dict[str, FunctionInfo]
+) -> None:
+    """Reject common parameters declared by no leaf command at all.
+
+    Without this, a typo'd (or not-yet-adopted) name would silently do
+    nothing everywhere.
+
+    :param common: Normalized common flag definitions.
+    :param leaf_infos: `{dotted_path: FunctionInfo}` for every leaf.
+    :raises ValueError: If a name matches no command.
+    """
+    for name in common:
+        if not any(name in info.arguments for info in leaf_infos.values()):
+            raise ValueError(
+                f'Common parameter {name!r} matches no command: no entry '
+                'point declares it.'
+            )
+
+
 def _add_arguments(
     parser: _Union[_argparse.ColorizingArgumentParser, _argparse._ArgumentGroup],
     info: FunctionInfo,
     reserved_flags: _Optional[_Set[str]] = None,
-    exclusive_groups: _Optional[_List[_Tuple[_List[str], bool]]] = None
+    exclusive_groups: _Optional[_List[_Tuple[_List[str], bool]]] = None,
+    common: _Optional[_Dict[str, Argument]] = None
 ) -> None:
     """Add the arguments to the parser.
 
@@ -571,6 +842,14 @@ def _add_arguments(
     :param reserved_flags: The reserved flags.
     :param exclusive_groups: Normalized `(names, required)` groups applying
         to this parser.
+    :param common: Normalized shared flag definitions. Entries whose name the
+        function declares itself are skipped (the local declaration wins);
+        the rest are added first, in mapping order, so shared flags claim
+        stable short forms across commands and per-command parameters fall
+        back deterministically. Common flags are always optional and never
+        join mutually exclusive groups; values for undeclared names are
+        accepted but not delivered (functions only receive declared keyword
+        arguments).
     """
     if reserved_flags is None:
         reserved_flags = RESERVED_FLAGS.copy()
@@ -596,24 +875,55 @@ def _add_arguments(
                 unsupported_arg=argument.name
             )
 
-    # Add the arguments
+    # Add the arguments. Shared flags go first, in mapping order, so they
+    # claim stable short forms across commands; explicitly declared
+    # parameters with the same names keep precedence and follow in mapping
+    # order too. Positional parameters always stay in signature order
+    # (`argparse` positionals are order-sensitive). The rest follows in
+    # signature order. Without `common`, this is exactly signature order.
+    common = common or {}
+    declared = [
+        info.arguments[name] for name in common if name in info.arguments
+        and info.arguments[name].kind
+        not in (_inspect._ParameterKind.POSITIONAL_ONLY,
+                _inspect._ParameterKind.VAR_POSITIONAL)
+    ]
+    missing = [spec for name, spec in common.items() if name not in info.arguments]
+    common_names = {spec.name for spec in missing}
+    rest = [
+        argument for argument in info.arguments.values()
+        if argument not in declared
+    ]
     containers: _Dict[int, _Any] = {}
     for index, (_, required) in enumerate(exclusive_groups or []):
         containers[index] = parser.add_mutually_exclusive_group(required=required)
-    for argument in info.arguments.values():
+    for argument in declared + missing + rest:
         config: _Dict[str, _Any] = {
             'action': 'store',
             'dest': argument.name,
             '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.
@@ -622,11 +932,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='?'`
@@ -639,9 +963,15 @@ 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
+                and argument.name not in common_names):
+            # Shared flags are always optional (non-breaking adoption).
             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 []):
@@ -652,7 +982,11 @@ 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,
+    common: _Optional[_Dict[str, _Any]] = None
 ) -> None:
     """This function argumentifies one function as the entry point of the script.
 
@@ -660,6 +994,10 @@ 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.
+    :param common: Shared `{name: default-or-spec}` flags added unless the
+        function declares the name itself.
     """
     info = FunctionInfo(func)
 
@@ -669,9 +1007,12 @@ def _argumentify_one(
     groups = _resolve_command_groups(
         mutually_exclusive, None, set(info.arguments)
     )
-    _add_arguments(parser, info, exclusive_groups=groups)
+    shared = _normalize_common(common)
+    _validate_common_names(shared, {'': info})
+    _add_arguments(parser, info, exclusive_groups=groups, common=shared)
     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():
@@ -852,13 +1193,15 @@ def _add_command_level(
     path: _Tuple[str, ...],
     leaf_infos: _Dict[str, FunctionInfo],
     mutually_exclusive: _Any = None,
-    leaf_paths: _Optional[_List[str]] = None
+    leaf_paths: _Optional[_List[str]] = None,
+    common: _Optional[_Dict[str, Argument]] = 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.
+    mutually exclusive groups and shared `common` flags); 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):
@@ -869,19 +1212,23 @@ def _add_command_level(
                 mutually_exclusive, dotted, name, set(info.arguments),
                 leaf_paths or [dotted]
             )
-            _add_arguments(subparser, info, exclusive_groups=groups)
+            _add_arguments(subparser, info, exclusive_groups=groups, common=common)
             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
+                leaf_paths, common
             )
 
 
 def _argumentify(
-    functions: _Dict[str, _Any], mutually_exclusive: _Any = None
+    functions: _Dict[str, _Any],
+    mutually_exclusive: _Any = None,
+    env_prefix: _Optional[str] = None,
+    secret_prompt: bool = True,
+    common: _Optional[_Dict[str, _Any]] = None
 ) -> None:
     """This function argumentifies one or more functions as the entry point of the
     script.
@@ -895,6 +1242,12 @@ def _argumentify(
         `{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).
+    :param common: Shared `{name: default-or-spec}` flags added to every leaf
+        that doesn't declare the name itself.
     :raises RuntimeError:
     """
     tree = _normalize_command_node(functions)
@@ -922,8 +1275,11 @@ def _argumentify(
     leaf_paths = [dotted for dotted, _, _ in leaves]
     _validate_mutex_keys(mutually_exclusive, leaf_paths)
     _validate_broadcast_groups(mutually_exclusive, leaf_infos)
+    shared = _normalize_common(common)
+    _validate_common_names(shared, leaf_infos)
     _add_command_level(
-        subparsers, tree, (), leaf_infos, mutually_exclusive, leaf_paths
+        subparsers, tree, (), leaf_infos, mutually_exclusive, leaf_paths,
+        shared
     )
     cli_args = parser.parse_args()
     args = []
@@ -935,6 +1291,7 @@ def _argumentify(
     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):
@@ -954,7 +1311,10 @@ def _argumentify(
 
 def argumentify(
     entry_point: _Union[Callable, _List[Callable], _Dict[str, _Any]],
-    mutually_exclusive: _Optional[_Any] = None
+    mutually_exclusive: _Optional[_Any] = None,
+    env_prefix: _Optional[str] = None,
+    secret_prompt: bool = True,
+    common: _Optional[_Dict[str, _Any]] = None
 ) -> _Union[Callable, _List[Callable], _Dict[str, _Any]]:
     """This function argumentifies one or more functions as the entry point of the
     script.
@@ -1030,17 +1390,48 @@ def argumentify(
     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")
+
+    Flags shared by every command can be declared once with `common`
+    (`{name: default}` or `{name: {"default": ..., "annotation": ...,
+    "help": ...}}`). Each flag is added to every leaf that doesn't declare
+    the name itself (an explicit local declaration always wins), claims a
+    stable short form across commands, and is always optional. Values reach
+    only functions declaring a matching parameter; the rest accept the flag
+    but ignore it, so adopting `common` never breaks a command:
+
+        argumentify(tree, common={"force": False, "verbose": False})
+
     :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.
+    :param common: Shared `{name: default-or-spec}` flags.
     :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.
+        dictionary of functions, or `common` is not a mapping.
+    :raises ValueError: A group is malformed or references unknown parameters,
+        or a `common` name/spec is malformed or matches no command.
     """
 
     functions = {}
     # Check the types
     if callable(entry_point):
-        _argumentify_one(entry_point, mutually_exclusive)
+        _argumentify_one(
+            entry_point, mutually_exclusive, env_prefix, secret_prompt, common
+        )
         return entry_point
     if isinstance(entry_point, _List):
         for func in entry_point:
@@ -1058,5 +1449,5 @@ def argumentify(
             "dictionary of functions."
         )
 
-    _argumentify(functions, mutually_exclusive)
+    _argumentify(functions, mutually_exclusive, env_prefix, secret_prompt, common)
     return entry_point

log21-3.7.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.5.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}'>"