log21 3.6.0__tar.gz → 3.7.0__tar.gz

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

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

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

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

{log21-3.6.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.6.0'
+__version__ = '3.7.0'
 __github__ = 'https://GitHub.com/MPCodeWriter21/log21'
 __all__ = [
     'ColorizingStreamHandler', 'DecolorizingFileHandler', 'ColorizingFormatter',

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

@@ -720,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.
 
@@ -739,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()
@@ -764,11 +875,29 @@ 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,
@@ -837,7 +966,9 @@ def _add_arguments(
             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 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'
                 and not is_secret):
@@ -854,7 +985,8 @@ def _argumentify_one(
     func: Callable,
     mutually_exclusive: _Any = None,
     env_prefix: _Optional[str] = None,
-    secret_prompt: bool = True
+    secret_prompt: bool = True,
+    common: _Optional[_Dict[str, _Any]] = None
 ) -> None:
     """This function argumentifies one function as the entry point of the script.
 
@@ -864,6 +996,8 @@ def _argumentify_one(
         `{"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)
 
@@ -873,7 +1007,9 @@ 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)
@@ -1057,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):
@@ -1074,14 +1212,14 @@ 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
             )
 
 
@@ -1089,7 +1227,8 @@ def _argumentify(
     functions: _Dict[str, _Any],
     mutually_exclusive: _Any = None,
     env_prefix: _Optional[str] = None,
-    secret_prompt: bool = True
+    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.
@@ -1107,6 +1246,8 @@ def _argumentify(
         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)
@@ -1134,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 = []
@@ -1169,7 +1313,8 @@ def argumentify(
     entry_point: _Union[Callable, _List[Callable], _Dict[str, _Any]],
     mutually_exclusive: _Optional[_Any] = None,
     env_prefix: _Optional[str] = None,
-    secret_prompt: bool = True
+    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.
@@ -1260,19 +1405,33 @@ def argumentify(
         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, env_prefix, secret_prompt)
+        _argumentify_one(
+            entry_point, mutually_exclusive, env_prefix, secret_prompt, common
+        )
         return entry_point
     if isinstance(entry_point, _List):
         for func in entry_point:
@@ -1290,5 +1449,5 @@ def argumentify(
             "dictionary of functions."
         )
 
-    _argumentify(functions, mutually_exclusive, env_prefix, secret_prompt)
+    _argumentify(functions, mutually_exclusive, env_prefix, secret_prompt, common)
     return entry_point