log21 3.4.0__tar.gz → 3.5.0__tar.gz

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

@@ -1,6 +1,6 @@
 Metadata-Version: 2.3
 Name: log21
-Version: 3.4.0
+Version: 3.5.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.5.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.5.0}/pyproject.toml

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

{log21-3.4.0 → log21-3.5.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.5.0'
 __github__ = 'https://GitHub.com/MPCodeWriter21/log21'
 __all__ = [
     'ColorizingStreamHandler', 'DecolorizingFileHandler', 'ColorizingFormatter',

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

@@ -450,18 +450,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 +489,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 = [
@@ -678,12 +691,204 @@ 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
 ) -> 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
@@ -692,33 +897,39 @@ def _argumentify(
         mapping.
     :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:
@@ -742,9 +953,9 @@ def _argumentify(
 
 
 def argumentify(
-    entry_point: _Union[Callable, _List[Callable], _Dict[str, Callable]],
+    entry_point: _Union[Callable, _List[Callable], _Dict[str, _Any]],
     mutually_exclusive: _Optional[_Any] = None
-) -> _Union[Callable, _List[Callable], _Dict[str, Callable]]:
+) -> _Union[Callable, _List[Callable], _Dict[str, _Any]]:
     """This function argumentifies one or more functions as the entry point of the
     script.
 
@@ -787,7 +998,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,6 +1011,25 @@ 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`.
+
     :param entry_point: The function(s) to argumentify.
     :param mutually_exclusive: Mutually exclusive parameter groups.
     :raises TypeError: A function must be a function or a list of functions or a
@@ -819,12 +1051,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(