log21 3.3.3__tar.gz → 3.4.0__tar.gz

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

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

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

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

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

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

{log21-3.3.3 → log21-3.4.0}/src/log21/argparse.py

@@ -612,13 +612,17 @@ class _ActionsContainer(_argparse._ActionsContainer):  # novm
             else:
                 func_type = func_type.__args__  # type: ignore
 
-        # Handle `List` as a type (e.g. `List[int]`)
+        # Handle `List` as a type (e.g. `List[int]` and builtin `list[int]`)
         elif (hasattr(_typing, '_GenericAlias')
               and isinstance(func_type, _typing._GenericAlias)  # type: ignore
               and func_type.__origin__ is list) or (
                   hasattr(_typing, '_GenericAlias')
                   and isinstance(func_type, _typing._GenericAlias)  # type: ignore
-                  and func_type.__origin__ is collections.abc.Sequence):
+                  and func_type.__origin__ is collections.abc.Sequence) or (
+                      hasattr(_types, 'GenericAlias')
+                      and isinstance(func_type, _types.GenericAlias)
+                      and getattr(func_type, '__origin__', None) in
+                      (list, collections.abc.Sequence)):
             func_type = func_type.__args__[0]
             if kwargs.get('nargs') is None:
                 action.nargs = '+'
@@ -668,6 +672,15 @@ class _ActionsContainer(_argparse._ActionsContainer):  # novm
                       _types.UnionType,
                   ))):
             func_type = self._validate_func_type(action, func_type, kwargs, level + 1)
+        elif (hasattr(_types, 'GenericAlias')
+              and isinstance(func_type, _types.GenericAlias)
+              and getattr(func_type, '__origin__', None) in
+              (list, collections.abc.Sequence)):
+            # Builtin `list[T]` unwrapped from a PEP 604 optional (e.g.
+            # `list[str] | None`): route it through the `List` branch above.
+            # Restricted to list/Sequence origins so other generics (e.g.
+            # `dict[str, int]`) cannot recurse forever.
+            func_type = self._validate_func_type(action, func_type, kwargs, level + 1)
         else:
             func_type = (func_type, )
 

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

@@ -7,6 +7,8 @@ import re as _re
 import string as _string
 import asyncio as _asyncio
 import inspect as _inspect
+import types as _stdlib_types
+import collections.abc as _collections_abc
 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,
@@ -331,16 +333,231 @@ def generate_flag(  # pylint: disable=too-many-branches
     return flags
 
 
+def _list_element_type(annotation: _Any) -> _Tuple[bool, _Any]:
+    """Check whether an annotation is a `list[T]` and return its element type.
+
+    Handles `list[T]`, `typing.List[T]`, `Sequence[T]` as well as
+    `Optional[...]` / `X | None` wrapped variants of those. Bare `list`
+    (without a subscript) returns `(True, None)`, meaning no per-item
+    conversion.
+
+    :param annotation: The parameter annotation to inspect.
+    :return: A `(is_list, element_type)` tuple.
+    """
+    if annotation is None:
+        return False, None
+    # Unwrap `Optional[X]` / `X | None` (both `typing` and PEP 604 spellings).
+    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)):
+        annotation = args[1] if args[0] is none_type else args[0]
+        args = getattr(annotation, '__args__', None)
+    if annotation is list:
+        return True, None
+    origin = getattr(annotation, '__origin__', None)
+    if origin is list or origin is _collections_abc.Sequence:
+        if args:
+            return True, args[0]
+        return True, None
+    if (hasattr(_stdlib_types, 'GenericAlias')
+            and isinstance(annotation, _stdlib_types.GenericAlias)
+            and getattr(annotation, '__origin__', None) in
+            (list, _collections_abc.Sequence)):
+        args = getattr(annotation, '__args__', None) or ()
+        return True, args[0] if args else None
+    return False, None
+
+
+def _is_repeatable_flag(argument: Argument) -> bool:
+    """Check whether an argument maps to a repeatable `--flag` option.
+
+    Only non-positional parameters annotated with `list[T]` are repeatable
+    flags. Positional-only `list[T]` parameters become multi-value
+    positionals instead, and `*args` is handled separately.
+    """
+    if argument.kind in (_inspect._ParameterKind.POSITIONAL_ONLY,
+                         _inspect._ParameterKind.VAR_POSITIONAL,
+                         _inspect._ParameterKind.VAR_KEYWORD):
+        return False
+    is_list, _ = _list_element_type(argument.annotation)
+    return is_list
+
+
+def _normalize_exclusive_groups(
+    mutually_exclusive: _Any
+) -> _List[_Tuple[_List[str], bool]]:
+    """Normalize the `mutually_exclusive` argument into `(names, required)` groups.
+
+    Each group is either a list/tuple of parameter names (an optional group)
+    or a `{"names": [...], "required": bool}` mapping. Groups must name at
+    least two parameters.
+
+    :param mutually_exclusive: The raw `mutually_exclusive` value.
+    :raises ValueError: If a group is malformed.
+    :return: A list of `(names, required)` tuples.
+    """
+    if mutually_exclusive is None:
+        return []
+    if isinstance(mutually_exclusive, _Dict):
+        if 'names' in mutually_exclusive:
+            # A single group passed without a wrapping list.
+            mutually_exclusive = [mutually_exclusive]
+        else:
+            raise ValueError(
+                'mutually_exclusive must be a list of groups, not a mapping. '
+                'To target groups at specific commands, pass a '
+                '{command_name: groups} mapping as documented in `argumentify`.'
+            )
+    groups: _List[_Tuple[_List[str], bool]] = []
+    if all(isinstance(item, str) for item in mutually_exclusive):
+        raise ValueError(
+            'mutually_exclusive must be a list of groups, e.g. '
+            f'[{list(mutually_exclusive)!r}], not a bare list of names.'
+        )
+    for group in mutually_exclusive:
+        required = False
+        if isinstance(group, _Dict):
+            names = group.get('names', [])
+            required = bool(group.get('required', False))
+        elif isinstance(group, (list, tuple)):
+            names = list(group)
+        else:
+            raise ValueError(
+                'Each mutually exclusive group must be a list of parameter '
+                f'names or a {{"names": [...], "required": bool}} mapping, '
+                f'got: {group!r}'
+            )
+        names = list(names)
+        if any(not isinstance(name, str) for name in names):
+            raise ValueError(
+                'Mutually exclusive group members must be parameter names '
+                f'(strings), got: {names!r}'
+            )
+        if len(names) < 2:
+            raise ValueError(
+                'Each mutually exclusive group must name at least two '
+                f'parameters, got: {names!r}'
+            )
+        if len(set(names)) != len(names):
+            raise ValueError(
+                'Duplicate parameter names in mutually exclusive group: '
+                f'{names!r}'
+            )
+        groups.append((names, required))
+    return groups
+
+
+def _resolve_command_groups(
+    mutually_exclusive: _Any, command: _Optional[str],
+    argument_names: _Set[str]
+) -> _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`.
+
+    :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.
+    :raises ValueError: If a group references unknown parameters.
+    :return: The groups applying to this command.
+    """
+    if mutually_exclusive is None:
+        return []
+    if isinstance(mutually_exclusive, _Dict):
+        if command is None:
+            raise ValueError(
+                'mutually_exclusive as a {command_name: groups} mapping is '
+                'only supported for multiple entry points; pass a plain list '
+                'of groups for a single function.'
+            )
+        if command not in mutually_exclusive:
+            return []
+        groups = _normalize_exclusive_groups(mutually_exclusive[command])
+        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 {command!r}: {unknown!r}'
+                )
+        _check_group_overlap(groups, command)
+        return groups
+    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:
+        # A broadcast list that matches nowhere is almost certainly a typo:
+        # fail fast instead of silently ignoring it.
+        missing = [
+            name for names, _ in groups for name in names
+            if name not in argument_names
+        ]
+        label = f'command {command!r} ' if command is not None else ''
+        raise ValueError(
+            f'Mutually exclusive groups reference unknown parameters for '
+            f'{label}: {sorted(set(missing))!r}'
+        )
+    _check_group_overlap(applicable, command)
+    return applicable
+
+
+def _check_group_overlap(
+    groups: _List[_Tuple[_List[str], bool]], command: _Optional[str]
+) -> None:
+    """Reject parameters shared between two groups of the same parser."""
+    seen: _Dict[str, _List[str]] = {}
+    for names, _ in groups:
+        for name in names:
+            seen.setdefault(name, []).append(names)
+    for name, owners in seen.items():
+        if len(owners) > 1:
+            label = f'command {command!r} ' if command is not None else ''
+            raise ValueError(
+                f'Parameter {name!r} for {label}is in more than one mutually '
+                'exclusive group.'
+            )
+
+
+def _apply_repeatable_defaults(cli_args: _Any, info: FunctionInfo) -> None:
+    """Restore declared `list[T]` defaults for absent repeatable flags.
+
+    Repeatable flags are registered with an internal `None` default (so
+    `argparse` never mutates the function signature's default list via
+    `action="append"`). When the flag was not used and the parameter declares
+    a default, substitute it back here.
+    """
+    for argument in info.arguments.values():
+        if _is_repeatable_flag(argument) and getattr(
+            cli_args, argument.name, None
+        ) is None and argument.default is not None:
+            setattr(cli_args, argument.name, argument.default)
+
+
 def _add_arguments(
     parser: _Union[_argparse.ColorizingArgumentParser, _argparse._ArgumentGroup],
     info: FunctionInfo,
-    reserved_flags: _Optional[_Set[str]] = None
+    reserved_flags: _Optional[_Set[str]] = None,
+    exclusive_groups: _Optional[_List[_Tuple[_List[str], bool]]] = None
 ) -> None:
     """Add the arguments to the parser.
 
+    `list[T]` parameters become multi-value arguments: positional-only ones
+    accept several values (`nargs='+'`, or `'*'` when a default is declared),
+    while other parameters become repeatable `--flag` options
+    (`action="append"`, each occurrence converted to `T`). Parameters listed
+    in `exclusive_groups` are added to `argparse` mutually exclusive groups.
+
     :param parser: The parser to add the arguments to.
     :param info: The function info.
     :param reserved_flags: The reserved flags.
+    :param exclusive_groups: Normalized `(names, required)` groups applying
+        to this parser.
     """
     if reserved_flags is None:
         reserved_flags = RESERVED_FLAGS.copy()
@@ -367,6 +584,9 @@ def _add_arguments(
             )
 
     # Add the arguments
+    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():
         config: _Dict[str, _Any] = {
             'action': 'store',
@@ -376,32 +596,69 @@ def _add_arguments(
         flags = generate_flag(argument, reserved_flags=reserved_flags)
         if argument.annotation is bool:
             config['action'] = 'store_true'
+        elif _is_repeatable_flag(argument):
+            _, element = _list_element_type(argument.annotation)
+            config['action'] = 'append'
+            if element is not None:
+                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.
+            config['default'] = None
         elif argument.annotation:
             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'] = '*'
+            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='?'`
+                # and multi-value ones `nargs='*'` (group-level `required`
+                # still enforces "exactly one" when requested).
+                if config.get('nargs') is None:
+                    config['nargs'] = '?'
+                elif config.get('nargs') == '+':
+                    config['nargs'] = '*'
         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:
             config['required'] = True
-        if argument.default is not None:
+        if argument.default is not None and config.get('action') != 'append':
             config['default'] = argument.default
-        parser.add_argument(*flags, **config)
+        target = parser
+        for index, (names, _) in enumerate(exclusive_groups or []):
+            if argument.name in names:
+                target = containers[index]
+                break
+        target.add_argument(*flags, **config)
 
 
-def _argumentify_one(func: Callable) -> None:
+def _argumentify_one(
+    func: Callable, mutually_exclusive: _Any = None
+) -> None:
     """This function argumentifies one function as the entry point of the script.
 
     :param function: The function to argumentify.
+    :param mutually_exclusive: A list of mutually exclusive groups. Each
+        group is a list of parameter names or a
+        `{"names": [...], "required": bool}` mapping.
     """
     info = FunctionInfo(func)
 
     # Create the parser
     parser = _argparse.ColorizingArgumentParser(description=info.docstring.description)
     # Add the arguments
-    _add_arguments(parser, info)
+    groups = _resolve_command_groups(
+        mutually_exclusive, None, set(info.arguments)
+    )
+    _add_arguments(parser, info, exclusive_groups=groups)
     cli_args = parser.parse_args()
+    _apply_repeatable_defaults(cli_args, info)
     args = []
     kwargs = {}
     for argument in info.arguments.values():
@@ -421,11 +678,18 @@ def _argumentify_one(func: Callable) -> None:
         parser.error(error.message)
 
 
-def _argumentify(functions: _Dict[str, Callable]) -> None:
+def _argumentify(
+    functions: _Dict[str, Callable], mutually_exclusive: _Any = None
+) -> None:
     """This function argumentifies one or more functions as the entry point of the
     script.
 
     :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.
     :raises RuntimeError:
     """
     functions_info: _Dict[str, _Tuple[Callable, FunctionInfo]] = {}
@@ -445,7 +709,10 @@ def _argumentify(functions: _Dict[str, Callable]) -> None:
     subparsers = parser.add_subparsers(required=True)
     for name, (_, info) in functions_info.items():
         subparser = subparsers.add_parser(name, help=info.docstring.description)
-        _add_arguments(subparser, info)
+        groups = _resolve_command_groups(
+            mutually_exclusive, name, set(info.arguments)
+        )
+        _add_arguments(subparser, info, exclusive_groups=groups)
         subparser.set_defaults(func=info.function)
     cli_args = parser.parse_args()
     args = []
@@ -456,6 +723,7 @@ def _argumentify(functions: _Dict[str, Callable]) -> None:
             break
     else:
         raise RuntimeError('No function found for the given arguments.')
+    _apply_repeatable_defaults(cli_args, info)
     for argument in info.arguments.values():
         if argument.kind in (_inspect._ParameterKind.POSITIONAL_ONLY,
                              _inspect._ParameterKind.POSITIONAL_OR_KEYWORD):
@@ -474,7 +742,8 @@ def _argumentify(functions: _Dict[str, Callable]) -> None:
 
 
 def argumentify(
-    entry_point: _Union[Callable, _List[Callable], _Dict[str, Callable]]
+    entry_point: _Union[Callable, _List[Callable], _Dict[str, Callable]],
+    mutually_exclusive: _Optional[_Any] = None
 ) -> _Union[Callable, _List[Callable], _Dict[str, Callable]]:
     """This function argumentifies one or more functions as the entry point of the
     script.
@@ -498,15 +767,48 @@ def argumentify(
     $ python argumentified.py Mehrad Pooryoussof
     Mehrad Pooryoussof is not yet born.
 
+    Parameters annotated with `list[T]` accept multiple values:
+    positional-only ones take several values (`items: list[str], /` called as
+    `prog a b c`), while other parameters become repeatable `--flag` options
+    (`defines: list[str]` called as `prog --defines a=1 --defines b=2`, each
+    occurrence converted to `T`). A declared default (e.g. `= []`) is used
+    when the argument is omitted. As with other parameters, if the function
+    also defines keyword-only parameters, positional-or-keyword `list[T]`
+    parameters become required flags; declare them keyword-only (after `*`)
+    to keep them optional.
+
+    Mutually exclusive parameters can be declared with `mutually_exclusive`.
+    Each group is a list of parameter names or a
+    `{"names": [...], "required": bool}` mapping (`required=True` means
+    exactly one of them must be given):
+
+        def run(recipe_path: str = None, /, *, builtin: str = None) -> None: ...
+        argumentify(run, mutually_exclusive=[["recipe_path", "builtin"]])
+
+    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
+    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
+    given:
+
+        argumentify(
+            {"run-recipe": run_recipe},
+            mutually_exclusive={"run-recipe": [["recipe_path", "builtin"]]},
+        )
+
     :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
         dictionary of functions.
+    :raises ValueError: A group is malformed or references unknown parameters.
     """
 
     functions = {}
     # Check the types
     if callable(entry_point):
-        _argumentify_one(entry_point)
+        _argumentify_one(entry_point, mutually_exclusive)
         return entry_point
     if isinstance(entry_point, _List):
         for func in entry_point:
@@ -530,5 +832,5 @@ def argumentify(
             "dictionary of functions."
         )
 
-    _argumentify(functions)
+    _argumentify(functions, mutually_exclusive)
     return entry_point