cli-command-parser 2026.2.1__tar.gz → 2026.6.27__tar.gz

{cli_command_parser-2026.2.1 → cli_command_parser-2026.6.27}/MANIFEST.in

@@ -1,4 +1,5 @@
 include *.rst
 include *.txt
+include *.typed
 include LICENSE
 include MANIFEST.in

{cli_command_parser-2026.2.1 → cli_command_parser-2026.6.27}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: cli_command_parser
-Version: 2026.2.1
+Version: 2026.6.27
 Summary: CLI Command Parser
 Author-email: Doug Skrypa <dskrypa@gmail.com>
 Project-URL: Source, https://github.com/dskrypa/cli_command_parser
@@ -25,6 +25,12 @@ Description-Content-Type: text/x-rst
 License-File: LICENSE
 Provides-Extra: wcwidth
 Requires-Dist: wcwidth; extra == "wcwidth"
+Provides-Extra: dev
+Requires-Dist: ruff; extra == "dev"
+Requires-Dist: pytest; extra == "dev"
+Requires-Dist: pytest-cov; extra == "dev"
+Requires-Dist: coverage; extra == "dev"
+Requires-Dist: mypy>=2.1.0; extra == "dev"
 Dynamic: license-file
 
 CLI Command Parser
@@ -57,7 +63,7 @@ CLIs while remaining readable and easy to maintain.
 
 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
+  - Typing support for CLI parameters that can be validated via type checkers
   - Subcommands can inherit common parameters so they don't need to be repeated
   - Easy to handle common initialization tasks for all actions / subcommands once
 
@@ -69,9 +75,11 @@ Example Program
 
     from cli_command_parser import Command, Option, main
 
-    class Hello(Command, description='Simple greeting example'):
+    class Hello(Command):
+        """Simple greeting example"""
+
         name = Option('-n', default='World', help='The person to say hello to')
-        count: int = Option('-c', default=1, help='Number of times to repeat the message')
+        count = Option('-c', type=int, default=1, help='Number of times to repeat the message')
 
         def main(self):
             for _ in range(self.count):

{cli_command_parser-2026.2.1 → cli_command_parser-2026.6.27}/lib/cli_command_parser/__init__.py

@@ -42,6 +42,7 @@ from .parameters import (
     Counter,
     Flag,
     Option,
+    Param,
     Parameter,
     ParamGroup,
     PassThru,
@@ -52,4 +53,4 @@ from .parameters import (
     after_main,
     before_main,
 )
-from .typing import Param, ParamOrGroup
+from .typing import ParamOrGroup

{cli_command_parser-2026.2.1 → cli_command_parser-2026.6.27}/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__ = '2026.02.01'
+__version__ = '2026.06.27'
 __author__ = 'Doug Skrypa'
 __author_email__ = 'dskrypa@gmail.com'
 __license__ = 'Apache 2.0'

{cli_command_parser-2026.2.1 → cli_command_parser-2026.6.27}/lib/cli_command_parser/command_parameters.py

@@ -12,20 +12,25 @@ from __future__ import annotations
 
 from collections import defaultdict
 from functools import cached_property
-from typing import TYPE_CHECKING, Collection, Iterator
+from typing import TYPE_CHECKING, Any, Collection, Iterator, Type, TypeAlias
 
 from .config import AmbiguousComboMode, CommandConfig
 from .exceptions import AmbiguousCombo, AmbiguousShortForm, CommandDefinitionError, ParameterDefinitionError
-from .parameters import Action, ActionFlag, ParamGroup, PassThru, SubCommand, help_action
+from .parameters import ActionFlag, ParamGroup, PassThru, help_action
 from .parameters.base import BaseOption, BasePositional, ParamBase, Parameter
+from .parameters.choice_map import Action, SubCommand
 
 if TYPE_CHECKING:
+    from .commands import Command
     from .context import Context
+    from .core import CommandMeta
     from .formatting.commands import CommandHelpFormatter
-    from .typing import CommandCls, Strings
+    from .typing import Bool, Strings
 
+    CommandCls: TypeAlias = Type[Command] | CommandMeta
     OptionMap = dict[str, BaseOption]
     ActionFlags = list[ActionFlag]
+    Positionals = list[BasePositional] | tuple[()]
 
 __all__ = ['CommandParameters']
 
@@ -33,18 +38,14 @@ __all__ = ['CommandParameters']
 class CommandParameters:
     # fmt: off
     command: CommandCls                                  #: The Command associated with this CommandParameters object
-    formatter: CommandHelpFormatter                      #: The formatter used for this Command's help text
     parent: CommandParameters | None                     #: The parent Command's CommandParameters
-    action: Action | None = None                         #: An Action Parameter, if specified
-    _pass_thru: PassThru | None = None                   #: A PassThru Parameter, if specified
-    sub_command: SubCommand | None = None                #: A SubCommand Parameter, if specified
     action_flags: ActionFlags                            #: List of action flags
     split_action_flags: tuple[ActionFlags, ActionFlags]  #: Action flags split by before/after main
     options: list[BaseOption]                            #: List of optional Parameters
     combo_option_map: OptionMap                          #: Mapping of {short opt: Parameter} (no dash characters)
     groups: list[ParamGroup]                             #: List of ParamGroup objects
     positionals: list[BasePositional]                    #: List of positional Parameters
-    _deferred_positionals: list[BasePositional] = ()     #: Positional Parameters that are deferred to sub commands
+    _deferred_positionals: Positionals = ()              #: Positional Parameters that are deferred to sub commands
     option_map: OptionMap                                #: Mapping of {--opt / -opt: Parameter}
     # fmt: on
 
@@ -52,6 +53,12 @@ class CommandParameters:
         self.command = command
         self.parent = parent_params
         self.config = config
+        # fmt: off
+        # These are annotated here because mypy thinks they're invoked as descriptors when annotated at the class level
+        self.action: Action | None = None               #: An Action Parameter, if specified
+        self.sub_command: SubCommand | None = None      #: A SubCommand Parameter, if specified
+        self._pass_thru: PassThru | None = None         #: A PassThru Parameter, if specified
+        # fmt: on
         self._process_parameters()
 
     def __repr__(self) -> str:
@@ -77,11 +84,8 @@ class CommandParameters:
 
     @cached_property
     def all_positionals(self) -> list[BasePositional]:
-        try:
-            if not self.parent.sub_command:
-                return self.parent.all_positionals + self.positionals
-        except AttributeError:
-            pass
+        if self.parent and not self.parent.sub_command:
+            return self.parent.all_positionals + self.positionals
         return self.positionals
 
     def get_positionals_to_parse(self, ctx: Context) -> list[BasePositional]:
@@ -94,6 +98,7 @@ class CommandParameters:
 
     @cached_property
     def formatter(self) -> CommandHelpFormatter:
+        """The formatter used for this Command's help text."""
         from .formatting.commands import CommandHelpFormatter
 
         formatter_factory = self.config.command_formatter or CommandHelpFormatter
@@ -105,13 +110,13 @@ class CommandParameters:
         return formatter
 
     @cached_property
-    def _has_help(self) -> bool:
+    def _has_help(self) -> Bool:
         return help_action in self.action_flags or (self.parent and self.parent._has_help)
 
     # region Initialization
 
     def _iter_parameters(self) -> Iterator[ParamBase]:
-        name_param_map = {}  # Allow subclasses to override names, but not within a given command
+        name_param_map: dict[str, Any] = {}  # Allow subclasses to override names, but not within a given command
         for item in self.command.__dict__.items():
             attr, param = item
             if attr.startswith('__') or not isinstance(param, ParamBase):  # Name mangled Parameters are still processed
@@ -173,7 +178,9 @@ class CommandParameters:
             self.groups = sorted(groups) if groups else []
 
     def _process_positionals(self, params: list[BasePositional]):
-        unfollowable = action_or_sub_cmd = split_index = None
+        unfollowable: BasePositional | None = None
+        action_or_sub_cmd: SubCommand | Action | None = None
+        split_index: int = 0
         if self.parent and (deferred := self.parent._deferred_positionals):
             params = deferred + params
 
@@ -186,26 +193,28 @@ class CommandParameters:
                 raise CommandDefinitionError(
                     f'Additional Positional parameters cannot follow {unfollowable} {why} - {param=} is invalid'
                 )
-            elif isinstance(param, (SubCommand, Action)):
+
+            if isinstance(param, (SubCommand, Action)):
                 if action_or_sub_cmd:
                     raise CommandDefinitionError(
                         f'Only 1 Action xor SubCommand is allowed in a given Command - {self.command.__name__} cannot'
                         f' contain both {action_or_sub_cmd} and {param}'
                     )
-                elif isinstance(param, SubCommand):
+
+                if isinstance(param, SubCommand):
                     self.sub_command = action_or_sub_cmd = param
                     split_index = i + 1
                     if param.has_choices and 0 in param.nargs:  # It has local choices or is not required
                         unfollowable = param
                 else:  # It's an Action
-                    self.action = action_or_sub_cmd = param  # type: ignore
+                    self.action = action_or_sub_cmd = param
                     if not param.has_choices:
                         raise CommandDefinitionError(f'No choices were registered for {self.action}')
             elif 0 in param.nargs or (param.nargs.variable and not param.has_choices):
                 unfollowable = param
 
         if split_index:
-            if self.sub_command.has_local_choices:
+            if self.sub_command.has_local_choices:  # type: ignore[union-attr]
                 self._deferred_positionals = params[split_index:]
             else:
                 params, self._deferred_positionals = params[:split_index], params[split_index:]
@@ -252,19 +261,22 @@ class CommandParameters:
                     f'{opt_type} {option=} conflict for command={self.command!r} between {existing} and {param}'
                 )
 
-    def _process_action_flags(self):
-        action_flags = sorted(p for p in self.options if isinstance(p, ActionFlag))
-        grouped_ordered_flags = {True: defaultdict(list), False: defaultdict(list)}
+    def _process_action_flags(self) -> None:
+        action_flags: ActionFlags = sorted(p for p in self.options if isinstance(p, ActionFlag))  # type: ignore[misc]
+        grouped_ordered_flags: dict[bool, dict[int | float, ActionFlags]] = {
+            True: defaultdict(list),
+            False: defaultdict(list),
+        }
         for param in action_flags:
             if param.func is None:
                 raise ParameterDefinitionError(f'No function was registered for {param=}')
             grouped_ordered_flags[param.before_main][param.order].append(param)
 
         found_non_always = False
-        invalid = {}
+        invalid: dict[tuple[bool, int | float], ActionFlags | ActionFlag] = {}
         for before_main, prio_params in grouped_ordered_flags.items():
             for prio, params in prio_params.items():
-                param: ActionFlag = params[0]  # Don't pop and check `if params` - all are needed for the group check
+                param = params[0]  # Don't pop and check `if params` - all are needed for the group check
                 if found_non_always and param.always_available:
                     invalid[(before_main, prio)] = param
                 elif not param.always_available:
@@ -296,7 +308,7 @@ class CommandParameters:
     @cached_property
     def _classified_combo_options(self) -> tuple[OptionMap, OptionMap]:
         """Tuple of (single char short:Option map, multi-char short:Option map) for options available in this command"""
-        multi_char_combos = {}
+        multi_char_combos: OptionMap = {}
         items = self.combo_option_map.items()
         for combo, param in items:
             if len(combo) == 1:  # combo_option_map is sorted in reverse length order, so all following will be 1 char
@@ -368,7 +380,7 @@ class CommandParameters:
             # Note: if the option is not in this Command's option_map, the KeyError is handled by CommandParser
             return [(option, self.option_map[option], value)], True
         else:
-            value = None
+            value = None  # type: ignore[assignment]
 
         try:
             param = self.option_map[option]

{cli_command_parser-2026.2.1 → cli_command_parser-2026.6.27}/lib/cli_command_parser/commands.py

@@ -9,16 +9,16 @@ from __future__ import annotations
 import logging
 from abc import ABC
 from contextlib import ExitStack
-from typing import TYPE_CHECKING, Sequence, TextIO, Type, overload
+from typing import TYPE_CHECKING, Sequence, TextIO, Type
 
 from .context import ActionPhase, Context, get_or_create_context
-from .core import CommandMeta, get_params, get_top_level_commands
+from .core import CommandMeta, get_metadata, get_params, get_top_level_commands
 from .exceptions import ParamConflict, ParserExit
 from .parser import parse_args_and_get_next_cmd
 from .utils import maybe_await
 
 if TYPE_CHECKING:
-    from .typing import Bool, CommandObj
+    from .typing import Bool, Self
 
 __all__ = ['Command', 'AsyncCommand', 'main', 'print_help']
 log = logging.getLogger(__name__)
@@ -32,34 +32,25 @@ class Command(ABC, metaclass=CommandMeta):
     #: The parsing Context used for this Command. Provided here for convenience - this reference to it is not used by
     #: any CLI Command Parser internals, so it is safe for subclasses to redefine / overwrite it.
     ctx: Context
+    __ctx: Context
 
-    def __new__(cls):
+    def __new__(cls) -> Command:
         # By storing the Context here instead of __init__, every single subclass won't need to
         # call super().__init__(...) from their own __init__ for this step
         self = super().__new__(cls)
         self.__ctx = ctx = get_or_create_context(cls, command=self)
         if not hasattr(self, 'ctx'):
-            self.ctx: Context = ctx  # noqa  # PyCharm complains this is invalid, but doesn't understand it without it
+            self.ctx = ctx  # noqa  # PyCharm complains this is invalid, but doesn't understand it without it
         return self
 
     def __repr__(self) -> str:
         cls = self.__class__
-        return f'<{cls.__name__} in prog={cls.__class__.meta(cls).prog!r}>'
+        return f'<{cls.__name__} in prog={get_metadata(cls).prog!r}>'
 
     # region Parse & Run
 
     @classmethod
-    @overload
-    def parse_and_run(cls: Type[CommandObj], argv: Argv = None, **kwargs) -> CommandObj | None:
-        # These overloads indicate that an instance of the same type or another may be returned
-        ...
-
-    @classmethod
-    @overload
-    def parse_and_run(cls, argv: Argv = None, **kwargs) -> CommandObj | None: ...
-
-    @classmethod
-    def parse_and_run(cls, argv=None, **kwargs):
+    def parse_and_run(cls, argv: Argv | None = None, **kwargs) -> Self | None:
         """
         Primary entry point for parsing arguments, resolving subcommands, and running a command.
 
@@ -90,15 +81,7 @@ class Command(ABC, metaclass=CommandMeta):
     # region Parse
 
     @classmethod
-    @overload
-    def parse(cls: Type[CommandObj], argv: Argv = None) -> CommandObj: ...
-
-    @classmethod
-    @overload
-    def parse(cls, argv: Argv = None) -> CommandObj: ...
-
-    @classmethod
-    def parse(cls, argv=None):
+    def parse(cls, argv: Argv | None = None) -> Self:
         """
         Parses the specified arguments (or :data:`sys.argv`), and resolves the final subcommand class based on the
         parsed arguments, if necessary.  Initializes the Command, but does not call any of its other methods.
@@ -111,7 +94,7 @@ class Command(ABC, metaclass=CommandMeta):
         with ExitStack() as stack:
             stack.enter_context(ctx)
             while sub_cmd := parse_args_and_get_next_cmd(ctx):
-                cmd_cls = sub_cmd
+                cmd_cls = sub_cmd  # type: ignore[assignment]
                 ctx = stack.enter_context(ctx._sub_context(cmd_cls))
 
             return cmd_cls()
@@ -308,14 +291,14 @@ class AsyncCommand(Command, ABC):
             await maybe_await(self(**kwargs))
             return self
 
-    async def __call__(self, *args, **kwargs) -> int:
+    async def __call__(self, *args, **kwargs) -> int:  # type: ignore[override]
         """Asynchronous version of :meth:`Command.__call__`."""
-        with self._Command__ctx as ctx, ctx.get_error_handler():  # noqa
+        with self._Command__ctx as ctx, ctx.get_error_handler():  # type: ignore[attr-defined]
             await maybe_await(self._pre_init_actions_(*args, **kwargs))
             await maybe_await(self._init_command_(*args, **kwargs))
             await maybe_await(self._before_main_(*args, **kwargs))
             try:
-                await maybe_await(self.main(*args, **kwargs))
+                await maybe_await(self.main(*args, **kwargs))  # type: ignore[arg-type]
             except BaseException:
                 if ctx.config.always_run_after_main:
                     log.debug('Caught exception - running _after_main_ before propagating', exc_info=True)
@@ -328,7 +311,7 @@ class AsyncCommand(Command, ABC):
 
     async def _run_actions_(self, phase: ActionPhase, args: tuple, kwargs: dict):
         """Asynchronous version of :meth:`Command._run_actions_`."""
-        for param in self._Command__ctx.iter_action_flags(phase):  # noqa
+        for param in self._Command__ctx.iter_action_flags(phase):  # type: ignore[attr-defined]
             await maybe_await(param.func(self, *args, **kwargs))
 
     async def _pre_init_actions_(self, *args, **kwargs):
@@ -340,9 +323,9 @@ class AsyncCommand(Command, ABC):
         """Asynchronous version of :meth:`Command._before_main_`."""
         await self._run_actions_(ActionPhase.BEFORE_MAIN, args, kwargs)
 
-    async def main(self, *args, **kwargs) -> int | None:
+    async def main(self, *args, **kwargs) -> int | None:  # type: ignore[override]
         """Asynchronous version of :meth:`Command.main`."""
-        with self._Command__ctx as ctx:  # noqa
+        with self._Command__ctx as ctx:  # type: ignore[attr-defined]
             action = get_params(self).action
             if action is not None and (ctx.actions_taken == 0 or ctx.config.action_after_action_flags):
                 ctx.actions_taken += 1
@@ -355,7 +338,7 @@ class AsyncCommand(Command, ABC):
         await self._run_actions_(ActionPhase.AFTER_MAIN, args, kwargs)
 
 
-def main(argv: Argv = None, return_command: Bool = False, **kwargs) -> CommandObj | None:
+def main(argv: Argv | None = None, return_command: Bool = False, **kwargs) -> Command | None:
     """
     Convenience function that can be used as the main entry point for a program.
 

{cli_command_parser-2026.2.1 → cli_command_parser-2026.6.27}/lib/cli_command_parser/compat.py

@@ -39,7 +39,7 @@ class WCTextWrapper(TextWrapper):
             if len(indent) + len(self.placeholder.lstrip()) > self.width:
                 raise ValueError('placeholder too large for max width')
 
-        lines = []
+        lines: list[str] = []
         # Arrange in reverse order so items can be efficiently popped from a stack of chucks.
         chunks.reverse()
         while chunks: