cli-command-parser 2025.6.14__tar.gz → 2025.7.13__tar.gz

{cli_command_parser-2025.6.14/lib/cli_command_parser.egg-info → cli_command_parser-2025.7.13}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: cli_command_parser
-Version: 2025.6.14
+Version: 2025.7.13
 Summary: CLI Command Parser
 Home-page: https://github.com/dskrypa/cli_command_parser
 Author: Doug Skrypa
@@ -58,11 +58,11 @@ CLI Command Parser is a class-based CLI argument parser that defines parameters
 tools to quickly and easily get started with basic CLIs, and it scales well to support even very large and complex
 CLIs while remaining readable and easy to maintain.
 
-The primary goals of this project:
-  - Make it easy to define subcommands and actions in an clean and organized manner
-  - Allow for inheritance so that common parameters don't need to be repeated
-  - Make it easy to handle common initialization tasks for all actions / subcommands once
-  - Reduce the amount of boilerplate code that is necessary for setting up parsing and handling argument values
+Some of the primary goals and key features of this project:
+  - Minimal boilerplate code is necessary to define CLI parameters and access their parsed values
+  - Easy to use type annotations for CLI parameters
+  - Subcommands can inherit common parameters so they don't need to be repeated
+  - Easy to handle common initialization tasks for all actions / subcommands once
 
 
 Example Program

{cli_command_parser-2025.6.14 → cli_command_parser-2025.7.13}/lib/cli_command_parser/__version__.py

@@ -1,7 +1,7 @@
 __title__ = 'cli_command_parser'
 __description__ = 'CLI Command Parser'
 __url__ = 'https://github.com/dskrypa/cli_command_parser'
-__version__ = '2025.06.14'
+__version__ = '2025.07.13'
 __author__ = 'Doug Skrypa'
 __author_email__ = 'dskrypa@gmail.com'
 __license__ = 'Apache 2.0'

{cli_command_parser-2025.6.14 → cli_command_parser-2025.7.13}/lib/cli_command_parser/context.py

@@ -24,7 +24,7 @@ from .utils import Terminal, _NotSet
 if TYPE_CHECKING:
     from .command_parameters import CommandParameters
     from .commands import Command
-    from .parameters import ActionFlag, Option, Parameter
+    from .parameters import ActionFlag, BaseOption, Option, Parameter
     from .typing import AnyConfig, Bool, CommandObj, CommandType, OptStr, ParamOrGroup, PathLike, StrSeq  # noqa
 
 __all__ = ['Context', 'ctx', 'get_current_context', 'get_or_create_context', 'get_context', 'get_parsed', 'get_raw_arg']
@@ -250,9 +250,11 @@ class Context(AbstractContextManager):  # Extending AbstractContextManager to ma
         """Not intended to be called by users.  Used during parsing to determine if any Parameters are missing."""
         return [p for p in self.params.required_check_params() if not self._provided[p]]
 
-    def missing_options_with_env_var(self) -> Iterator[Option]:
+    def missing_options_with_env_var(self) -> Iterator[BaseOption]:
         """Yields Option parameters that have an environment variable configured, and did not have any CLI values."""
-        yield from (p for p in self.params.options if p.env_var and not self._provided[p])
+        for param in self.params.options:
+            if param.env_var and not self._provided[param]:
+                yield param
 
     # endregion
 

{cli_command_parser-2025.6.14 → cli_command_parser-2025.7.13}/lib/cli_command_parser/inputs/choices.py

@@ -36,7 +36,12 @@ class _ChoicesBase(InputType[T], ABC):
         return True
 
     def _type_str(self) -> str:
-        return f'type={self.type.__name__}, ' if self.type is not None else ''
+        if self.type is not None:
+            try:
+                return f'type={self.type.__name__}, '
+            except AttributeError:  # type is not a class
+                pass
+        return ''
 
     def __repr__(self) -> str:
         cls_name = self.__class__.__name__
@@ -100,7 +105,10 @@ class Choices(_ChoicesBase[T]):
         self.case_sensitive = case_sensitive
 
     def _choices_repr(self, delim: str = ',') -> str:
-        return delim.join(map(repr, sorted(self.choices)))
+        try:
+            return delim.join(map(repr, sorted(self.choices)))
+        except TypeError:  # The choice values are not sortable
+            return delim.join(sorted(map(repr, self.choices)))
 
     def __call__(self, value: str) -> T:
         choices = self.choices

{cli_command_parser-2025.6.14 → cli_command_parser-2025.7.13}/lib/cli_command_parser/nargs.py

@@ -6,9 +6,9 @@ Helpers for handling ``nargs=...`` for Parameters.
 
 from __future__ import annotations
 
-from typing import Any, Collection, FrozenSet, Iterable, Optional, Sequence, Set, Tuple, Union
+from typing import Any, Collection, FrozenSet, Optional, Sequence, Set, Tuple, Union
 
-__all__ = ['Nargs', 'NargsValue', 'REMAINDER', 'nargs_min_and_max_sums']
+__all__ = ['Nargs', 'NargsValue', 'REMAINDER']
 
 REMAINDER = type('REMAINDER', (), {})()
 _UNBOUND = (None, REMAINDER)
@@ -177,20 +177,3 @@ class Nargs:
     @property
     def upper_bound(self) -> Union[int, float]:
         return self.max if self._has_upper_bound else float('inf')
-
-
-def nargs_min_and_max_sums(nargs_objects: Iterable[Nargs]) -> tuple[int, Union[int, float]]:
-    min_sum, max_sum = 0, 0
-    iter_nargs = iter(nargs_objects)
-    for obj in iter_nargs:
-        min_sum += obj.min
-        if obj._has_upper_bound:
-            max_sum += obj.max
-        else:
-            max_sum = float('inf')
-            break
-
-    for obj in iter_nargs:  # If any had no upper bound, then this loop will complete the min total
-        min_sum += obj.min  # Otherwise, it will not have anything to iterate over
-
-    return min_sum, max_sum

{cli_command_parser-2025.6.14 → cli_command_parser-2025.7.13}/lib/cli_command_parser/parameters/actions.py

@@ -6,7 +6,7 @@ variables.
 from __future__ import annotations
 
 from abc import ABC, abstractmethod
-from typing import TYPE_CHECKING, Callable, Iterable, Iterator, NoReturn, Sequence, TypeVar, Union
+from typing import TYPE_CHECKING, Callable, Generic, Iterable, Iterator, NoReturn, Sequence, TypeVar, Union
 
 from ..context import ctx
 from ..exceptions import BadArgument, InvalidChoice, MissingArgument, ParamConflict, ParamUsageError, TooManyArguments
@@ -15,7 +15,8 @@ from ..nargs import Nargs
 from ..utils import _NotSet, camel_to_snake_case
 
 if TYPE_CHECKING:
-    from ..typing import Bool, CommandObj, Param, T_co
+    from .base import Parameter  # noqa
+    from ..typing import Bool, CommandObj, T_co
 
 __all__ = [
     'ParamAction',
@@ -31,20 +32,19 @@ __all__ = [
 
 _PANotSet = object()
 
-TD = TypeVar('TD')
+Param = TypeVar('Param', bound='Parameter')
 Found = Union[int, NoReturn]
 
 
-class ParamAction(ABC):
+class ParamAction(ABC, Generic[Param]):
     __slots__ = ('param',)
     name: str
-    default: TD = _NotSet
+    param: Param
+    default = _NotSet
     accepts_values: bool = False
     accepts_consts: bool = False
 
-    def __init_subclass__(
-        cls, default: TD = _PANotSet, accepts_values: bool = None, accepts_consts: bool = None, **kwargs
-    ):
+    def __init_subclass__(cls, default=_PANotSet, accepts_values: bool = None, accepts_consts: bool = None, **kwargs):
         super().__init_subclass__(**kwargs)
         cls.name = camel_to_snake_case(cls.__name__)
         if default is not _PANotSet:
@@ -111,6 +111,15 @@ class ParamAction(ABC):
             return False
         return self.param.is_valid_arg(normalized)
 
+    def would_accept_all(self, values: list[str], combo: bool = False) -> bool:
+        prepare_validation_value, is_valid_arg = self.param.prepare_validation_value, self.param.is_valid_arg
+        try:
+            valid_values = all(is_valid_arg(prepare_validation_value(value, combo)) for value in values)
+        except BadArgument:  # Potentially raised by prepare_validation_value; is_valid_arg handles exceptions
+            return False
+        else:
+            return valid_values and len(values) in self.param.nargs
+
     # Note: Not used yet
     # def _prep_and_validate(self, values: Sequence[str], combo: bool) -> Iterator[T_co]:
     #     prepare_value, validate = self.param.prepare_value, self.param.validate
@@ -123,10 +132,10 @@ class ParamAction(ABC):
 
     # region Backtracking
 
-    def get_maybe_poppable_counts(self) -> list[int]:
+    def get_maybe_poppable_values(self) -> list[list[str]]:
         """
-        :return: The indexes on which the parsed values may be split such that the remaining number of values will
-          still be acceptable for the Parameter's nargs.
+        Groups of args that may be removed from this Parameter's parsed values such that the remaining number will
+        still be acceptable for its nargs.
         """
         return []
 
@@ -162,7 +171,7 @@ class ParamAction(ABC):
 
 class ValueMixin:
     __slots__ = ()
-    param: Param
+    param: Param  # noqa
     get_default: Callable
 
     def set_value(self, value):
@@ -195,7 +204,7 @@ class ValueMixin:
 
 class ConstMixin:
     __slots__ = ()
-    param: Param
+    param: Param  # noqa
     get_default: Callable
     add_const: Callable
     add_value: Callable
@@ -264,8 +273,8 @@ class Store(ValueMixin, ParamAction, default=None, accepts_values=True):
     #     ctx.record_action(self.param)
     #     if not values:
     #         raise MissingArgument(self.param)
-    #     elif (val_count := len(values)) not in (nargs := self.param.nargs):
-    #         raise BadArgument(self.param, f'expected {nargs=} values but found {val_count}')
+    #     elif (val_count := len(values)) not in self.param.nargs:
+    #         raise BadArgument(self.param, f'expected nargs={self.param.nargs} values but found {val_count}')
     #
     #     self.set_value([value for value in self._prep_and_validate(values, combo)])
     #     return val_count
@@ -320,17 +329,13 @@ class Append(ValueMixin, ParamAction, accepts_values=True):
 
     # region Backtracking
 
-    def get_maybe_poppable_counts(self) -> list[int]:
-        """
-        :return: The indexes on which the parsed values may be split such that the remaining number of values will
-          still be acceptable for the Parameter's nargs.
-        """
+    def get_maybe_poppable_values(self) -> list[list[str]]:
         if not self.param.nargs.variable or self.param.type not in (None, str):
             return []
         elif (values := ctx.get_parsed_value(self.param)) is not _NotSet:
             n_values = len(values)
             satisfied = self.param.nargs.satisfied
-            return [i for i in range(1, n_values) if satisfied(n_values - i)]
+            return [values[-i:] for i in range(1, n_values) if satisfied(n_values - i)]
         else:
             return []
 
@@ -398,6 +403,9 @@ class BasicConstAction(ConstMixin, ParamAction, ABC, accepts_consts=True):
     def would_accept(self, value: str, combo: bool = False) -> bool:
         return False
 
+    def would_accept_all(self, values: list[str], combo: bool = False) -> bool:
+        return False
+
     # endregion
 
 
@@ -507,6 +515,13 @@ class Concatenate(Append):
 
     # endregion
 
+    # region Parsing
+
+    def would_accept_all(self, values: list[str], combo: bool = False) -> bool:
+        return self.param.is_valid_arg(values)
+
+    # endregion
+
     # region Parsed Value / Default Finalization
 
     def finalize_default(self, value):

{cli_command_parser-2025.6.14 → cli_command_parser-2025.7.13}/lib/cli_command_parser/parameters/base.py

@@ -96,6 +96,14 @@ class ParamBase(ABC):
 
     # endregion
 
+    def __eq__(self, other: ParamBase) -> bool:
+        return (
+            self.__class__ == other.__class__
+            and self._attr_name == other._attr_name
+            and self._name == other._name
+            and self.command == other.command
+        )
+
     def __hash__(self) -> int:
         return hash(self.__class__) ^ hash(self._attr_name) ^ hash(self._name) ^ hash(self.command)
 

{cli_command_parser-2025.6.14 → cli_command_parser-2025.7.13}/lib/cli_command_parser/parameters/choice_map.py

@@ -9,13 +9,13 @@ from __future__ import annotations
 from functools import partial
 from string import printable, whitespace
 from types import MethodType
-from typing import TYPE_CHECKING, Callable, Collection, Generic, Mapping, NoReturn, Optional, Type, TypeVar, Union
+from typing import TYPE_CHECKING, Callable, Collection, Generic, Mapping, NoReturn, Sequence, Type, TypeVar
 
 from ..context import ctx
 from ..exceptions import BadArgument, CommandDefinitionError, InvalidChoice, ParameterDefinitionError
 from ..formatting.utils import format_help_entry
 from ..nargs import Nargs
-from ..typing import Bool, CommandCls, CommandObj
+from ..typing import CommandCls
 from ..utils import _NotSet, camel_to_snake_case, short_repr
 from .actions import Concatenate
 from .base import BasePositional
@@ -23,12 +23,12 @@ from .base import BasePositional
 if TYPE_CHECKING:
     from ..formatting.params import ChoiceMapHelpFormatter
     from ..metadata import ProgramMetadata
+    from ..typing import Bool, CommandObj, OptStr
 
 __all__ = ['SubCommand', 'Action', 'Choice', 'ChoiceMap']
 
 T = TypeVar('T')
 TD = TypeVar('TD')
-OptStr = Optional[str]
 # TODO: Combine SubCommand and Action, replacing `local_choices` with stackable decorators on the target method,
 #  optionally injecting the selected choice into positional args for the decorated method, which may be main?
 
@@ -142,7 +142,7 @@ class ChoiceMap(BasePositional[str], Generic[T], actions=(Concatenate,)):
     def _register_choice(
         self,
         choice: OptStr,
-        target: Optional[T] = _NotSet,
+        target: T | None = _NotSet,
         help: str = None,  # noqa
         local: bool = False,
     ):
@@ -162,21 +162,26 @@ class ChoiceMap(BasePositional[str], Generic[T], actions=(Concatenate,)):
 
     # region Argument Handling
 
-    def validate(self, value: str, joined: Bool = False):
+    def validate(self, value: str | Sequence[str], joined: Bool = False):
         if not self.choices:
             self._no_choices_error()
 
         parsed = ctx.get_parsed_value(self)
-        values = (value,) if parsed is _NotSet else (*parsed, value)
+        if parsed is _NotSet:
+            values = (value,) if isinstance(value, str) else value
+        else:
+            values = (*parsed, value) if isinstance(value, str) else (*parsed, *value)
+
         if (choice := ' '.join(values)) in self.choices:
             return
         elif len(values) > self.nargs.max:
             raise BadArgument(self, 'too many values')
+
         prefix = choice + ' '
         if not any(c.startswith(prefix) for c in self.choices if c):
             raise InvalidChoice(self, prefix[:-1], self.choices)
 
-    def result(self, command: CommandObj | None = None, missing_default: TD = _NotSet) -> Union[OptStr, TD]:
+    def result(self, command: CommandObj | None = None, missing_default: TD = _NotSet) -> OptStr | TD:
         if not self.choices:
             self._no_choices_error()
         return super().result(command, missing_default)
@@ -211,7 +216,7 @@ class SubCommand(ChoiceMap[CommandCls], title='Subcommands', choice_validation_e
         *,
         required: Bool = True,
         default_help: str = None,
-        local_choices: Optional[Union[Mapping[str, str], Collection[str]]] = None,
+        local_choices: Mapping[str, str] | Collection[str] | None = None,
         **kwargs,
     ):
         """
@@ -237,7 +242,7 @@ class SubCommand(ChoiceMap[CommandCls], title='Subcommands', choice_validation_e
     def has_local_choices(self) -> bool:
         return None in self.choices or any(c.target is None for c in self.choices.values())
 
-    def _register_local_choices(self, local_choices: Union[Mapping[str, str], Collection[str]]):
+    def _register_local_choices(self, local_choices: Mapping[str, str] | Collection[str]):
         try:
             choice_help_iter = local_choices.items()
         except AttributeError:
@@ -273,7 +278,7 @@ class SubCommand(ChoiceMap[CommandCls], title='Subcommands', choice_validation_e
 
     def register(
         self,
-        command_or_choice: Union[str, CommandCls] = None,
+        command_or_choice: str | CommandCls | None = None,
         *,
         choice: str = None,
         help: str = None,  # noqa
@@ -344,12 +349,12 @@ class Action(ChoiceMap[MethodType], title='Actions'):
 
     def register(
         self,
-        method_or_choice: Union[str, MethodType] = None,
+        method_or_choice: str | MethodType | None = None,
         *,
         choice: str = None,
         help: str = None,  # noqa
         default: Bool = False,
-    ) -> Union[MethodType, Callable[[MethodType], MethodType]]:
+    ) -> MethodType | Callable[[MethodType], MethodType]:
         """
         Decorator that registers the wrapped method to be called when the given choice is specified for this parameter.
         Methods may also be registered by decorating them with the instantiated Action parameter directly - doing so

{cli_command_parser-2025.6.14 → cli_command_parser-2025.7.13}/lib/cli_command_parser/parameters/options.py

@@ -7,9 +7,8 @@ Optional Parameters
 from __future__ import annotations
 
 import logging
-from abc import ABC
 from functools import partial, update_wrapper
-from typing import TYPE_CHECKING, Any, Callable, Literal, NoReturn, Optional, TypeVar, Union
+from typing import TYPE_CHECKING, Any, Callable, Literal, NoReturn, TypeVar, Union
 
 from ..exceptions import BadArgument, CommandDefinitionError, ParameterDefinitionError, ParamUsageError, ParserExit
 from ..inputs import normalize_input_type
@@ -188,7 +187,7 @@ class Flag(BaseOption[Union[TD, TC]], actions=(StoreConst, AppendConst)):
     def register_default_cb(self, method):
         raise ParameterDefinitionError(f'{self.__class__.__name__}s do not support default callback methods')
 
-    def get_env_const(self, value: str, env_var: str) -> tuple[Union[TC, TD], bool]:
+    def get_env_const(self, value: str, env_var: str) -> tuple[TC | TD, bool]:
         try:
             parsed = self.type(value)
         except Exception as e:
@@ -198,7 +197,7 @@ class Flag(BaseOption[Union[TD, TC]], actions=(StoreConst, AppendConst)):
         return parsed, self.use_env_value
 
 
-class TriFlag(BaseOption[Union[TD, TC, TA]], ABC, actions=(StoreConst, AppendConst)):
+class TriFlag(BaseOption[Union[TD, TC, TA]], actions=(StoreConst, AppendConst)):
     """
     A trinary / ternary Flag.  While :class:`.Flag` only supports 1 constant when provided, with 1 default if not
     provided, this class accepts a pair of constants for the primary and alternate values to store, along with a
@@ -298,13 +297,13 @@ class TriFlag(BaseOption[Union[TD, TC, TA]], ABC, actions=(StoreConst, AppendCon
             self.default = _NotSet  # The default was set by __init__ - remove it so the method can be registered
         return super().register_default_cb(method)
 
-    def get_const(self, opt_str: OptStr = None) -> Union[TC, TA]:
+    def get_const(self, opt_str: OptStr = None) -> TC | TA:
         if opt_str in self.option_strs.alt_allowed:
             return self.consts[1]
         else:
             return self.consts[0]
 
-    def get_env_const(self, value: str, env_var: str) -> tuple[Union[TC, TA, TD], bool]:
+    def get_env_const(self, value: str, env_var: str) -> tuple[TC | TA | TD, bool]:
         try:
             parsed = self.type(value)
         except Exception as e:
@@ -342,7 +341,7 @@ class ActionFlag(Flag, repr_attrs=('order', 'before_main')):
     def __init__(
         self,
         *option_strs: str,
-        order: Union[int, float] = 1,
+        order: int | float = 1,
         func: Callable = None,
         before_main: Bool = True,  # noqa  # pylint: disable=W0621
         always_available: Bool = False,
@@ -364,7 +363,7 @@ class ActionFlag(Flag, repr_attrs=('order', 'before_main')):
         return self._func
 
     @func.setter
-    def func(self, func: Optional[Callable]):
+    def func(self, func: Callable | None):
         self._func = func
         if func is not None:
             if self.help is None:
@@ -403,7 +402,7 @@ class ActionFlag(Flag, repr_attrs=('order', 'before_main')):
         self.func = func
         return self
 
-    def __get__(self, command: Optional[CommandObj], owner: CommandCls) -> Union[ActionFlag, Callable]:
+    def __get__(self, command: CommandObj | None, owner: CommandCls) -> ActionFlag | Callable:
         # Allow the method to be called, regardless of whether it was specified
         if command is None:
             return self
@@ -424,12 +423,12 @@ class ActionFlag(Flag, repr_attrs=('order', 'before_main')):
 action_flag = ActionFlag  # pylint: disable=C0103
 
 
-def before_main(*option_strs: str, order: Union[int, float] = 1, func: Callable = None, **kwargs) -> ActionFlag:
+def before_main(*option_strs: str, order: int | float = 1, func: Callable = None, **kwargs) -> ActionFlag:
     """An ActionFlag that will be executed before :meth:`.Command.main`"""
     return ActionFlag(*option_strs, order=order, func=func, before_main=True, **kwargs)
 
 
-def after_main(*option_strs: str, order: Union[int, float] = 1, func: Callable = None, **kwargs) -> ActionFlag:
+def after_main(*option_strs: str, order: int | float = 1, func: Callable = None, **kwargs) -> ActionFlag:
     """An ActionFlag that will be executed after :meth:`.Command.main`"""
     return ActionFlag(*option_strs, order=order, func=func, before_main=False, **kwargs)
 
@@ -500,7 +499,7 @@ class Counter(BaseOption[int], actions=(Count,)):
             self.default_cb = None
         return super().register_default_cb(method)
 
-    def prepare_value(self, value: Optional[str], short_combo: bool = False, env_var: str = None) -> int:
+    def prepare_value(self, value: str | None, short_combo: bool = False, env_var: str = None) -> int:
         try:
             return self.type(value)
         except (ValueError, TypeError) as e:
@@ -516,7 +515,7 @@ class Counter(BaseOption[int], actions=(Count,)):
         if value is None or isinstance(value, self.type):
             return
         try:
-            value = self.type(value)
+            self.type(value)
         except (ValueError, TypeError) as e:
             raise BadArgument(self, f'invalid {value=} (expected an integer)') from e
         else:

{cli_command_parser-2025.6.14 → cli_command_parser-2025.7.13}/lib/cli_command_parser/parse_tree.py

@@ -7,7 +7,6 @@ from __future__ import annotations
 from typing import TYPE_CHECKING, Collection, Iterable, Iterator, MutableMapping, Optional, Union
 
 from .exceptions import AmbiguousParseTree
-from .nargs import nargs_min_and_max_sums
 from .utils import _parse_tree_target_repr
 
 if TYPE_CHECKING:
@@ -89,9 +88,6 @@ class PosNode(MutableMapping[Word, 'PosNode']):
             for node in self.values():
                 yield from node._link_params(_has_upper_bound(node))
 
-    def nargs_min_and_max(self) -> tuple[int, Union[int, float]]:
-        return nargs_min_and_max_sums(p.nargs for p in self.link_params(True))
-
     # region AnyWord Methods
 
     @property

{cli_command_parser-2025.6.14 → cli_command_parser-2025.7.13}/lib/cli_command_parser/parser.py

@@ -9,7 +9,7 @@ from __future__ import annotations
 import logging
 from collections import deque
 from os import environ
-from typing import TYPE_CHECKING, Deque, Iterable, Optional
+from typing import TYPE_CHECKING, Deque, Sequence
 
 from .context import ActionPhase, Context
 from .core import get_parent
@@ -22,7 +22,7 @@ from .exceptions import (
     ParamUsageError,
     UsageError,
 )
-from .nargs import REMAINDER, nargs_min_and_max_sums
+from .nargs import REMAINDER
 from .parameters.base import BaseOption, BasePositional, Parameter
 from .parse_tree import PosNode
 
@@ -45,12 +45,12 @@ class CommandParser:
 
     __slots__ = ('_last', 'arg_deque', 'ctx', 'config', 'deferred', 'params', 'positionals')
 
-    arg_deque: Optional[Deque[str]]
+    arg_deque: Deque[str] | None
     config: CommandConfig
-    deferred: Optional[list[str]]
+    deferred: list[str] | None
     params: CommandParameters
     positionals: list[BasePositional]
-    _last: Optional[Parameter]
+    _last: Parameter | None
 
     def __init__(self, ctx: Context, params: CommandParameters, config: CommandConfig):
         self._last = None
@@ -62,7 +62,7 @@ class CommandParser:
             PosNode.build_tree(ctx.command_cls)
 
     @classmethod
-    def parse_args_and_get_next_cmd(cls, ctx: Context) -> Optional[CommandType]:
+    def parse_args_and_get_next_cmd(cls, ctx: Context) -> CommandType | None:
         try:
             return cls(ctx, ctx.params, ctx.config).get_next_cmd(ctx)
         except UsageError:
@@ -70,7 +70,7 @@ class CommandParser:
                 raise
             return None
 
-    def get_next_cmd(self, ctx: Context) -> Optional[CommandType]:
+    def get_next_cmd(self, ctx: Context) -> CommandType | None:
         self._parse_args(ctx)
         self._validate_groups()
         missing = ctx.get_missing()
@@ -273,7 +273,7 @@ class CommandParser:
             if len(self.positionals) == 1 and 0 in self.positionals[0].nargs:
                 raise NextCommand
             else:
-                raise ParamUsageError(param, 'subcommand arguments must be provided after the subcommand')
+                raise ParamUsageError(param, 'subcommand arguments must be provided after the subcommand')  # noqa
 
     # region Backtracking
 
@@ -287,26 +287,58 @@ class CommandParser:
         :param found: The number of values that were consumed by the given Parameter
         :return: The updated found count, if backtracking was possible, otherwise the unmodified found count
         """
-        if self.positionals:
-            can_pop = param.action.get_maybe_poppable_counts()
-            if rollback_count := _to_pop(self.positionals, can_pop, found - 1):
-                self.arg_deque.extendleft(reversed(self.ctx.roll_back_parsed_values(param, rollback_count)))
-                return found - rollback_count
-        return found
+        if not self.positionals:
+            return found
+        elif rollback_count := self._get_backtrack_count(param):
+            self.arg_deque.extendleft(reversed(self.ctx.roll_back_parsed_values(param, rollback_count)))
+            return found - rollback_count
+        else:
+            return found
+
+    def _get_backtrack_count(
+        self, param: Parameter, extras: Sequence[str] = (), positionals: Sequence[BasePositional] = ()
+    ) -> int:
+        if poppable_groups := param.action.get_maybe_poppable_values():
+            return next((len(g) for g in poppable_groups if self._should_backtrack(g, extras, positionals)), 0)
+        return 0
+
+    def _should_backtrack(
+        self, group: list[str], extras: Sequence[str] = (), positionals: Sequence[BasePositional] = ()
+    ) -> bool:
+        args = [*group, *extras, *self.arg_deque]
+        for pos_param in positionals or self.positionals:
+            n = pos_param.nargs.min
+            if not n and 1 in pos_param.nargs:
+                n = 1
+
+            param_args = args[:n]
+            if len(param_args) != n or not pos_param.action.would_accept_all(param_args):
+                return False
+
+            args = args[n:]
 
-    def _maybe_backtrack_last(self, param: BasePositional, found: int):
+        return True
+
+    def _maybe_backtrack_last_positional(self, param: BasePositional):
         """
         Similar to :meth:`._maybe_backtrack`, but allows backtracking even after starting to process a Positional.
+
+        By the time this method is called, it has already been discovered that `found` does not satisfy `param`'s
+        nargs requirements.
         """
         if not self.config.allow_backtrack:
-            # This method is called relatively rarely & it's cleaner to have this check here than in _finalize_consume
+            # This method is called extremely rarely & it's cleaner to have this check here than in _finalize_consume
             return
 
-        can_pop = self._last.action.get_maybe_poppable_counts()
-        # It is extremely unlikely for this point to be reached without this resulting in triggering a backtrack
-        if rollback_count := _to_pop((param, *self.positionals), can_pop, max(can_pop, default=0) + found, found):
+        parsed = self.ctx.get_parsed_value(param, ())
+        # It is extremely unlikely for this point to be reached without this resulting in triggering backtrack
+        if num := self._get_backtrack_count(self._last, parsed, (param, *self.positionals)):
+            # log.debug(f'Rolling back {num} parsed values from {self._last=} / {param=} and triggering Backtrack')
+            # Reset all of this param's parsed args because the previous param's roll back args need to be injected
+            # before them so they can be processed by this parameter.
             self.arg_deque.extendleft(reversed(self.ctx.pop_parsed_value(param)))
-            self.arg_deque.extendleft(reversed(self.ctx.roll_back_parsed_values(self._last, rollback_count)))
+            # Roll back a subset of the previous param's parsed args
+            self.arg_deque.extendleft(reversed(self.ctx.roll_back_parsed_values(self._last, num)))
             raise Backtrack
 
     # endregion
@@ -353,15 +385,13 @@ class CommandParser:
                 # log.debug(f'{value=} was rejected by {param=}', exc_info=True)
                 return self._finalize_consume(param, value, found, e)
 
-        # TODO: Positional(nargs='?') with no values will steal values intended for an Option(nargs='+')
-        #  (likely occurs with nargs='*' for the Positional as well)
-
         # log.debug(f'Ran out of values in deque while processing {param=}')
         if found >= 2 and self.config.allow_backtrack:
             found = self._maybe_backtrack(param, found)
         return self._finalize_consume(param, None, found)
 
-    def _finalize_consume(self, param: Parameter, value: OptStr, found: int, exc: Optional[Exception] = None) -> int:
+    def _finalize_consume(self, param: Parameter, value: OptStr, found: int, exc: Exception | None = None) -> int:
+        # log.debug(f'Finalizing arg consumption for {param=}, {value=}, {found=}, {exc=}')
         nargs = param.nargs
         if nargs.satisfied(found):
             # Even if an exception was passed to this method, if the found number of values is acceptable, then it
@@ -373,7 +403,7 @@ class CommandParser:
         elif exc:
             raise exc
         elif self._last and isinstance(param, BasePositional) and param.action.can_reset():
-            self._maybe_backtrack_last(param, found)
+            self._maybe_backtrack_last_positional(param)
 
         s = '' if nargs.min == 1 else 's'
         raise MissingArgument(param, f'expected {nargs.min} value{s}, but only found {found}')
@@ -382,22 +412,6 @@ class CommandParser:
 parse_args_and_get_next_cmd = CommandParser.parse_args_and_get_next_cmd
 
 
-def _to_pop(positionals: Iterable[BasePositional], can_pop: list[int], available: int, req_mod: int = 0) -> int:
-    if not can_pop:
-        return 0
-
-    required, acceptable = nargs_min_and_max_sums(p.nargs for p in positionals)
-    if available < required:
-        return 0
-
-    required -= req_mod
-    for n in can_pop:
-        if required <= n <= acceptable:
-            return n
-
-    return 0
-
-
 def get_opt_prefix(text: str) -> OptStr:
     if not text or text[0] != '-':
         return None

{cli_command_parser-2025.6.14 → cli_command_parser-2025.7.13/lib/cli_command_parser.egg-info}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: cli_command_parser
-Version: 2025.6.14
+Version: 2025.7.13
 Summary: CLI Command Parser
 Home-page: https://github.com/dskrypa/cli_command_parser
 Author: Doug Skrypa
@@ -58,11 +58,11 @@ CLI Command Parser is a class-based CLI argument parser that defines parameters
 tools to quickly and easily get started with basic CLIs, and it scales well to support even very large and complex
 CLIs while remaining readable and easy to maintain.
 
-The primary goals of this project:
-  - Make it easy to define subcommands and actions in an clean and organized manner
-  - Allow for inheritance so that common parameters don't need to be repeated
-  - Make it easy to handle common initialization tasks for all actions / subcommands once
-  - Reduce the amount of boilerplate code that is necessary for setting up parsing and handling argument values
+Some of the primary goals and key features of this project:
+  - Minimal boilerplate code is necessary to define CLI parameters and access their parsed values
+  - Easy to use type annotations for CLI parameters
+  - Subcommands can inherit common parameters so they don't need to be repeated
+  - Easy to handle common initialization tasks for all actions / subcommands once
 
 
 Example Program

{cli_command_parser-2025.6.14 → cli_command_parser-2025.7.13}/readme.rst

@@ -26,11 +26,11 @@ CLI Command Parser is a class-based CLI argument parser that defines parameters
 tools to quickly and easily get started with basic CLIs, and it scales well to support even very large and complex
 CLIs while remaining readable and easy to maintain.
 
-The primary goals of this project:
-  - Make it easy to define subcommands and actions in an clean and organized manner
-  - Allow for inheritance so that common parameters don't need to be repeated
-  - Make it easy to handle common initialization tasks for all actions / subcommands once
-  - Reduce the amount of boilerplate code that is necessary for setting up parsing and handling argument values
+Some of the primary goals and key features of this project:
+  - Minimal boilerplate code is necessary to define CLI parameters and access their parsed values
+  - Easy to use type annotations for CLI parameters
+  - Subcommands can inherit common parameters so they don't need to be repeated
+  - Easy to handle common initialization tasks for all actions / subcommands once
 
 
 Example Program