cli-command-parser 2025.5.10__tar.gz → 2025.7.10__tar.gz

{cli_command_parser-2025.5.10/lib/cli_command_parser.egg-info → cli_command_parser-2025.7.10}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: cli_command_parser
-Version: 2025.5.10
+Version: 2025.7.10
 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.5.10 → cli_command_parser-2025.7.10}/lib/cli_command_parser/__init__.py

@@ -4,52 +4,52 @@ Command Parser
 :author: Doug Skrypa
 """
 
+from .commands import AsyncCommand, Command, main
 from .config import (
+    AllowLeadingDash,
+    AmbiguousComboMode,
     CommandConfig,
-    ShowDefaults,
     OptionNameMode,
+    ShowDefaults,
     SubcommandAliasHelpMode,
-    AmbiguousComboMode,
-    AllowLeadingDash,
 )
-from .commands import Command, AsyncCommand, main
-from .context import Context, get_current_context, ctx, get_parsed, get_context, get_raw_arg
+from .context import Context, ctx, get_context, get_current_context, get_parsed, get_raw_arg
+from .error_handling import ErrorHandler, error_handler, extended_error_handler, no_exit_handler
 from .exceptions import (
-    CommandParserException,
-    CommandDefinitionError,
-    ParameterDefinitionError,
-    UsageError,
-    ParamUsageError,
+    AmbiguousParseTree,
     BadArgument,
+    CommandDefinitionError,
+    CommandParserException,
     InvalidChoice,
     MissingArgument,
-    TooManyArguments,
+    NoActiveContext,
     NoSuchOption,
-    ParserExit,
     ParamConflict,
+    ParameterDefinitionError,
     ParamsMissing,
-    NoActiveContext,
-    AmbiguousParseTree,
+    ParamUsageError,
+    ParserExit,
+    TooManyArguments,
+    UsageError,
 )
-from .error_handling import ErrorHandler, error_handler, no_exit_handler, extended_error_handler
 from .formatting.commands import get_formatter
 from .nargs import REMAINDER
 from .parameters import (
+    Action,
+    ActionFlag,
+    BaseOption,
+    BasePositional,
+    Counter,
+    Flag,
+    Option,
     Parameter,
+    ParamGroup,
     PassThru,
-    BasePositional,
     Positional,
     SubCommand,
-    Action,
-    BaseOption,
-    Option,
-    Flag,
-    Counter,
-    ActionFlag,
+    TriFlag,
     action_flag,
-    before_main,
     after_main,
-    ParamGroup,
-    TriFlag,
+    before_main,
 )
 from .typing import Param, ParamOrGroup

{cli_command_parser-2025.5.10 → cli_command_parser-2025.7.10}/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.05.10'
+__version__ = '2025.07.10'
 __author__ = 'Doug Skrypa'
 __author_email__ = 'dskrypa@gmail.com'
 __license__ = 'Apache 2.0'

{cli_command_parser-2025.5.10 → cli_command_parser-2025.7.10}/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.7.10/lib/cli_command_parser/conversion/__init__.py

@@ -0,0 +1,12 @@
+from .argparse_ast import (
+    AddVisitedChild,
+    ArgCollection,
+    ArgGroup,
+    AstArgumentParser,
+    AstCallable,
+    MutuallyExclusiveGroup,
+    Script,
+    SubParser,
+    visit_func,
+)
+from .command_builder import Converter, convert_script

{cli_command_parser-2025.5.10 → cli_command_parser-2025.7.10}/lib/cli_command_parser/conversion/cli.py

@@ -4,7 +4,7 @@ import logging
 from functools import cached_property
 from pathlib import Path
 
-from cli_command_parser import Command, Counter, Positional, Flag, ParamGroup, SubCommand, main
+from cli_command_parser import Command, Counter, Flag, ParamGroup, Positional, SubCommand, main
 from cli_command_parser.inputs import Path as IPath
 
 log = logging.getLogger(__name__)

{cli_command_parser-2025.5.10 → cli_command_parser-2025.7.10}/lib/cli_command_parser/documentation.py

@@ -132,15 +132,17 @@ def top_level_commands(commands: Commands) -> Commands:
 def import_module(path: PathLike):
     """Import the module / package from the given path"""
     path = Path(path)
-    name = path.stem
+    name = _module_name(path)
     if path.is_dir():
         path /= '__init__.py'
+
     spec = spec_from_file_location(name, path)
     try:
         module = module_from_spec(spec)
     except AttributeError as e:
         path_str = path.as_posix()
         raise ImportError(f'Invalid path={path_str!r} - are you sure it is a Python module?', path=path_str) from e
+
     sys.modules[spec.name] = module  # This is required for the program metadata introspection
     try:
         spec.loader.exec_module(module)
@@ -150,6 +152,20 @@ def import_module(path: PathLike):
     return module
 
 
+def _module_name(path: Path) -> str:
+    if path.name == '__init__.py':
+        path = path.parent
+
+    parts = [path.stem]
+    while (path := path.parent).name:  # / has no name
+        if path.joinpath('__init__.py').exists():  # it is a package
+            parts.append(path.name)
+        else:
+            break
+
+    return '.'.join(parts[::-1])
+
+
 def _is_command(obj, include_abc: Bool = False) -> bool:
     if not (isinstance(obj, CommandMeta) and obj is not Command):
         return False

cli_command_parser-2025.7.10/lib/cli_command_parser/error_handling/__init__.py

@@ -0,0 +1,38 @@
+"""
+Error handling for expected / unexpected exceptions.
+
+The default handler will...
+
+- Call ``print()`` after catching a :class:`python:KeyboardInterrupt`, before exiting
+- Exit gracefully after catching a :class:`python:BrokenPipeError` (often caused by piping output to a tool like
+  ``tail``)
+
+.. note::
+    Parameters defined in a base Command will be processed in the context of that Command.  I.e., if a valid
+    subcommand argument was provided, but an Option defined in the parent Command has an invalid value, then the
+    exception that is raised about that invalid value will be raised before transferring control to the
+    subcommand's error handler.
+
+:author: Doug Skrypa
+"""
+
+from platform import system as _system
+
+from .base import (
+    ErrorHandler,
+    Handler,
+    HandlerFunc,
+    NullErrorHandler,
+    error_handler,
+    extended_error_handler,
+    no_exit_handler,
+)
+
+if _system().lower() == 'windows':
+    from .windows import handle_kb_interrupt
+else:
+    from .other import handle_kb_interrupt
+
+__all__ = ['ErrorHandler', 'Handler', 'error_handler', 'extended_error_handler', 'no_exit_handler', 'NullErrorHandler']
+
+error_handler.register(handle_kb_interrupt, KeyboardInterrupt)

cli_command_parser-2025.5.10/lib/cli_command_parser/error_handling.py → cli_command_parser-2025.7.10/lib/cli_command_parser/error_handling/base.py

@@ -1,34 +1,19 @@
 """
-Error handling for expected / unexpected exceptions.
-
-The default handler will...
-
-- Call ``print()`` after catching a :class:`python:KeyboardInterrupt`, before exiting
-- Exit gracefully after catching a :class:`python:BrokenPipeError` (often caused by piping output to a tool like
-  ``tail``)
-
-.. note::
-    Parameters defined in a base Command will be processed in the context of that Command.  I.e., if a valid
-    subcommand argument was provided, but an Option defined in the parent Command has an invalid value, then the
-    exception that is raised about that invalid value will be raised before transferring control to the
-    subcommand's error handler.
-
-:author: Doug Skrypa
+Platform-agnostic error handling framework / handlers.
 """
 
 from __future__ import annotations
 
-import platform
 import sys
 from collections import ChainMap
-from typing import Callable, Iterator, Optional, Type, Union
+from typing import Callable, Iterator, Type, TypeVar, Union
 
-from .exceptions import CommandParserException
+from ..exceptions import CommandParserException
 
 __all__ = ['ErrorHandler', 'error_handler', 'extended_error_handler', 'no_exit_handler', 'NullErrorHandler']
 
-WINDOWS = platform.system().lower() == 'windows'
-HandlerFunc = Callable[[BaseException], Optional[bool]]
+E = TypeVar('E', bound=BaseException)
+HandlerFunc = Callable[[E], Union[bool, int, None]]
 
 
 class ErrorHandler:
@@ -42,7 +27,7 @@ class ErrorHandler:
     def __repr__(self) -> str:
         return f'<{self.__class__.__name__}[handlers={len(self.exc_handler_map)}]>'
 
-    def register(self, handler: HandlerFunc, *exceptions: Type[BaseException]):
+    def register(self, handler: HandlerFunc, *exceptions: Type[E]):
         for exc in exceptions:
             self.exc_handler_map[exc] = Handler(exc, handler)
 
@@ -61,7 +46,7 @@ class ErrorHandler:
         return _handler
 
     @classmethod
-    def cls_handler(cls, *exceptions: Type[BaseException]):
+    def cls_handler(cls, *exceptions: Type[E]):
         def _cls_handler(handler: Union[HandlerFunc, staticmethod]):
             for exc in exceptions:
                 cls._exc_handler_map[exc] = Handler(exc, handler)
@@ -91,6 +76,7 @@ class ErrorHandler:
         for handler in self.iter_handlers(exc_type, exc_val):
             result = handler(exc_val)
             if result is True:
+                # This explicitly checks for True since 1 == True, but 1 is treated as an intended exit code
                 return True
             if result or (isinstance(result, int) and result is not False):
                 sys.exit(result)
@@ -130,62 +116,23 @@ class Handler:
         return issubclass(self.exc_cls, other.exc_cls)
 
 
-ErrorHandler.cls_handler(CommandParserException)(CommandParserException.exit)
+# By default, all error handlers should call :meth:`CommandParserException.exit` for CommandParserExceptions
+ErrorHandler.cls_handler(CommandParserException)(CommandParserException.exit)  # noqa
 
 #: Default base :class:`ErrorHandler`
 error_handler: ErrorHandler = ErrorHandler()
-error_handler.register(lambda e: True, BrokenPipeError)
 
 
-@error_handler(KeyboardInterrupt)
-def handle_kb_interrupt(exc: KeyboardInterrupt) -> int:
-    """
-    Handles :class:`python:KeyboardInterrupt` by calling :func:`python:print` to avoid ending the program in a way that
-    causes the next terminal prompt to be printed on the same line as the last (possibly incomplete) line of output.
-    """
-    try:
-        print(flush=True)  # Flush forces any potential closed/broken pipe-related error to be caught/handled here
-    except BrokenPipeError:
-        pass
-    except OSError as e:
-        # Handle the closed/broken pipe incorrect errno bug if triggered during the above print
-        if not WINDOWS or not handle_win_os_pipe_error(e):
-            raise
-    return 130
+@error_handler(BrokenPipeError)
+def _handle_broken_pipe(exc: BrokenPipeError):
+    # This can't be registered as a lambda function because it would break the ability to pickle the handler
+    return True
 
 
 #: An :class:`ErrorHandler` that does not call :func:`python:sys.exit` for
 #: :class:`CommandParserExceptions<.CommandParserException>`
 no_exit_handler: ErrorHandler = error_handler.copy()
-no_exit_handler(CommandParserException)(CommandParserException.show)
+no_exit_handler.register(CommandParserException.show, CommandParserException)  # noqa
 
 #: The default :class:`ErrorHandler` (extends :obj:`error_handler`)
 extended_error_handler: ErrorHandler = error_handler.copy()
-
-if WINDOWS:
-    import ctypes
-
-    RtlGetLastNtStatus = ctypes.WinDLL('ntdll').RtlGetLastNtStatus
-    RtlGetLastNtStatus.restype = ctypes.c_ulong
-    NT_STATUSES = {0xC000_00B1: 'STATUS_PIPE_CLOSING', 0xC000_014B: 'STATUS_PIPE_BROKEN'}
-
-    @extended_error_handler(OSError)
-    def handle_win_os_pipe_error(exc: OSError):
-        """
-        This is a workaround for `[Windows] I/O on a broken pipe may raise an EINVAL OSError instead of BrokenPipeError
-        <https://github.com/python/cpython/issues/79935>`_, which is a bug in the way that the
-        windows error code for a broken pipe is translated into an errno value.  It should be translated to
-        :data:`~errno.EPIPE`, but it uses :data:`~errno.EINVAL` (22) instead.
-
-        Prevents the following when piping output to utilities such as ``| head``::\n
-            Exception ignored in: <_io.TextIOWrapper name='<stdout>' mode='w' encoding='utf-8'>
-            OSError: [Errno 22] Invalid argument
-        """
-        if exc.errno == 22 and RtlGetLastNtStatus() in NT_STATUSES:
-            try:
-                sys.stdout.close()
-            except OSError:
-                pass
-            return True
-
-        return False

cli_command_parser-2025.7.10/lib/cli_command_parser/error_handling/other.py

@@ -0,0 +1,20 @@
+"""
+Error handling for expected / unexpected exceptions on non-Windows systems.
+"""
+
+from __future__ import annotations
+
+__all__ = ['handle_kb_interrupt']
+
+
+def handle_kb_interrupt(exc: KeyboardInterrupt) -> int:
+    """
+    Handles :class:`python:KeyboardInterrupt` by calling :func:`python:print` to avoid ending the program in a way that
+    causes the next terminal prompt to be printed on the same line as the last (possibly incomplete) line of output.
+    """
+    try:
+        print(flush=True)  # Flush forces any potential closed/broken pipe-related error to be caught/handled here
+    except BrokenPipeError:
+        pass
+    # 130 (= 128 + SIGINT (2)) is used/expected by Bash; see: https://tldp.org/LDP/abs/html/exitcodes.html
+    return 130

cli_command_parser-2025.7.10/lib/cli_command_parser/error_handling/windows.py

@@ -0,0 +1,55 @@
+"""
+Error handling for expected / unexpected exceptions on Windows systems.
+"""
+
+from __future__ import annotations
+
+import ctypes
+import sys
+
+from .base import extended_error_handler
+
+__all__ = ['handle_kb_interrupt']
+
+RtlGetLastNtStatus = ctypes.WinDLL('ntdll').RtlGetLastNtStatus
+RtlGetLastNtStatus.restype = ctypes.c_ulong
+NT_STATUSES = {0xC000_00B1: 'STATUS_PIPE_CLOSING', 0xC000_014B: 'STATUS_PIPE_BROKEN'}
+
+
+def handle_kb_interrupt(exc: KeyboardInterrupt) -> int:
+    """
+    Handles :class:`python:KeyboardInterrupt` by calling :func:`python:print` to avoid ending the program in a way that
+    causes the next terminal prompt to be printed on the same line as the last (possibly incomplete) line of output.
+    """
+    try:
+        print(flush=True)  # Flush forces any potential closed/broken pipe-related error to be caught/handled here
+    except BrokenPipeError:
+        pass
+    except OSError as e:
+        # Handle the closed/broken pipe incorrect errno bug if triggered during the above print
+        if not handle_win_os_pipe_error(e):
+            raise
+    return 130
+
+
+@extended_error_handler(OSError)
+def handle_win_os_pipe_error(exc: OSError):
+    """
+    This is a workaround for `[Windows] I/O on a broken pipe may raise an EINVAL OSError instead of BrokenPipeError
+    <https://github.com/python/cpython/issues/79935>`_, which is a bug in the way that the
+    Windows error code for a broken pipe is translated into an errno value.  It should be translated to
+    :data:`~errno.EPIPE`, but it uses :data:`~errno.EINVAL` (22) instead.
+
+    Prevents the following when piping output to utilities such as ``| head``::
+
+        Exception ignored in: <_io.TextIOWrapper name='<stdout>' mode='w' encoding='utf-8'>
+        OSError: [Errno 22] Invalid argument
+    """
+    if exc.errno == 22 and RtlGetLastNtStatus() in NT_STATUSES:
+        try:
+            sys.stdout.close()
+        except OSError:
+            pass
+        return True
+
+    return False

{cli_command_parser-2025.5.10 → cli_command_parser-2025.7.10}/lib/cli_command_parser/formatting/params.py

@@ -56,6 +56,9 @@ class ParamHelpFormatter:
     def __init__(self, param: ParamOrGroup):
         self.param = param
 
+    def __getnewargs__(self):
+        return (self.param,)
+
     def maybe_wrap_usage(self, text: str) -> str:
         """
         Wraps the provided text in parentheses / brackets / etc based on whether the associated Parameter is required,

{cli_command_parser-2025.5.10 → cli_command_parser-2025.7.10}/lib/cli_command_parser/inputs/__init__.py

@@ -10,17 +10,17 @@ import typing as _t
 from enum import Enum as _Enum
 
 from ..exceptions import ParameterDefinitionError as _ParameterDefinitionError
-from .exceptions import InputValidationError, InvalidChoiceError
-from .utils import StatMode, FileWrapper
 from .base import InputType
-from .choices import Choices, ChoiceMap, EnumChoices
-from .files import Path, File, Serialized, Json, Pickle
-from .numeric import Range, NumRange
-from .patterns import Regex, RegexMode, Glob
-from .time import Day, Month, TimeDelta, DateTime, Date, Time, DTFormatMode
+from .choices import ChoiceMap, Choices, EnumChoices
+from .exceptions import InputValidationError, InvalidChoiceError
+from .files import File, Json, Path, Pickle, Serialized
+from .numeric import NumRange, Range
+from .patterns import Glob, Regex, RegexMode
+from .time import Date, DateTime, Day, DTFormatMode, Month, Time, TimeDelta
+from .utils import FileWrapper, StatMode
 
 if _t.TYPE_CHECKING:
-    from ..typing import TypeFunc, InputTypeFunc, ChoicesType
+    from ..typing import ChoicesType, InputTypeFunc, TypeFunc
 
 # fmt: off
 __all__ = [

{cli_command_parser-2025.5.10 → cli_command_parser-2025.7.10}/lib/cli_command_parser/inputs/choices.py

@@ -8,9 +8,9 @@ from __future__ import annotations
 
 from abc import ABC, abstractmethod
 from enum import Enum
-from typing import TYPE_CHECKING, Any, Type, TypeVar, Collection, Iterator, Optional, Set, Mapping
+from typing import TYPE_CHECKING, Any, Collection, Iterator, Mapping, Optional, Set, Type, TypeVar
 
-from ..typing import TypeFunc, T
+from ..typing import T, TypeFunc
 from .base import InputType
 from .exceptions import InvalidChoiceError
 

{cli_command_parser-2025.5.10 → cli_command_parser-2025.7.10}/lib/cli_command_parser/inputs/exceptions.py

@@ -4,7 +4,7 @@ Exceptions for custom input types / validators.
 :author: Doug Skrypa
 """
 
-from typing import Collection, Any
+from typing import Any, Collection
 
 from ..exceptions import CommandParserException
 

{cli_command_parser-2025.5.10 → cli_command_parser-2025.7.10}/lib/cli_command_parser/inputs/time.py

@@ -112,6 +112,18 @@ class DTFormatMode(MissingMixin, Enum):
 
 
 class CalendarUnitInput(DTInput[Union[str, int]], ABC):
+    """
+    Input type representing a date/time unit.
+
+    :param full: Allow the full unit name to be provided
+    :param abbreviation: Allow abbreviations of unit names to be provided
+    :param numeric: Allow unit values to be specified as a decimal number
+    :param locale: An alternate locale to use when parsing input
+    :param out_format: A :class:`DTFormatMode` or str that matches a format mode.  Defaults to full weekday name.
+    :param out_locale: Alternate locale to use for output.  Defaults to the same value as ``locale``.
+    :param fix_default: Whether default values should be normalized using :meth:`~DTInput.fix_default`.
+    """
+
     __slots__ = ('full', 'abbreviation', 'numeric', 'out_format', 'out_locale')
     _formats: dict[DTFormatMode, Sequence[Union[str, int]]]
     _min_index: int = 0
@@ -131,17 +143,6 @@ class CalendarUnitInput(DTInput[Union[str, int]], ABC):
         out_locale: Locale = None,
         fix_default: Bool = True,
     ):
-        """
-        Input type representing a date/time unit.
-
-        :param full: Allow the full unit name to be provided
-        :param abbreviation: Allow abbreviations of unit names to be provided
-        :param numeric: Allow unit values to be specified as a decimal number
-        :param locale: An alternate locale to use when parsing input
-        :param out_format: A :class:`DTFormatMode` or str that matches a format mode.  Defaults to full weekday name.
-        :param out_locale: Alternate locale to use for output.  Defaults to the same value as ``locale``.
-        :param fix_default: Whether default values should be normalized using :meth:`~DTInput.fix_default`.
-        """
         if not (full or abbreviation or numeric):
             raise ValueError('At least one of full, abbreviation, or numeric must be True')
         super().__init__(locale=locale, fix_default=fix_default)
@@ -224,6 +225,20 @@ class CalendarUnitInput(DTInput[Union[str, int]], ABC):
 
 
 class Day(CalendarUnitInput, dt_type='day of the week'):
+    """
+    Input type representing a day of the week.
+
+    :param full: Allow the full day name to be provided
+    :param abbreviation: Allow abbreviations of day names to be provided
+    :param numeric: Allow weekdays to be specified as a decimal number
+    :param iso: Ignored if ``numeric`` is False.  If True, then numeric weekdays are treated as ISO 8601 weekdays,
+      where 1 is Monday and 7 is Sunday.  If False, then 0 is Monday and 6 is Sunday.
+    :param locale: An alternate locale to use when parsing input
+    :param out_format: A :class:`DTFormatMode` or str that matches a format mode.  Defaults to full weekday name.
+    :param out_locale: Alternate locale to use for output.  Defaults to the same value as ``locale``.
+    :param fix_default: Whether default values should be normalized using :meth:`~DTInput.fix_default`.
+    """
+
     __slots__ = ('iso',)
     _formats = {
         DTFormatMode.FULL: day_name,
@@ -244,21 +259,7 @@ class Day(CalendarUnitInput, dt_type='day of the week'):
         out_format: Union[str, DTFormatMode] = DTFormatMode.FULL,
         out_locale: Locale = None,
         fix_default: Bool = True,
-    ):
-        """
-        Input type representing a day of the week.
-
-        :param full: Allow the full day name to be provided
-        :param abbreviation: Allow abbreviations of day names to be provided
-        :param numeric: Allow weekdays to be specified as a decimal number
-        :param iso: Ignored if ``numeric`` is False.  If True, then numeric weekdays are treated as ISO 8601 weekdays,
-          where 1 is Monday and 7 is Sunday.  If False, then 0 is Monday and 6 is Sunday.
-        :param locale: An alternate locale to use when parsing input
-        :param out_format: A :class:`DTFormatMode` or str that matches a format mode.  Defaults to full weekday name.
-        :param out_locale: Alternate locale to use for output.  Defaults to the same value as ``locale``.
-        :param fix_default: Whether default values should be normalized using :meth:`~DTInput.fix_default`.
-        """
-        ...
+    ): ...
 
     def __init__(self, *, iso: Bool = False, **kwargs):
         super().__init__(**kwargs)
@@ -283,6 +284,18 @@ class Day(CalendarUnitInput, dt_type='day of the week'):
 
 
 class Month(CalendarUnitInput, dt_type='month', min_index=1):
+    """
+    Input type representing a month.
+
+    :param full: Allow the full month name to be provided
+    :param abbreviation: Allow abbreviations of month names to be provided
+    :param numeric: Allow months to be specified as a decimal number
+    :param locale: An alternate locale to use when parsing input
+    :param out_format: A :class:`DTFormatMode` or str that matches a format mode.  Defaults to full month name.
+    :param out_locale: Alternate locale to use for output.  Defaults to the same value as ``locale``.
+    :param fix_default: Whether default values should be normalized using :meth:`~DTInput.fix_default`.
+    """
+
     __slots__ = ()
     _formats = {
         DTFormatMode.FULL: month_name,
@@ -301,19 +314,7 @@ class Month(CalendarUnitInput, dt_type='month', min_index=1):
         out_format: Union[str, DTFormatMode] = DTFormatMode.FULL,
         out_locale: Locale = None,
         fix_default: Bool = True,
-    ):
-        """
-        Input type representing a month.
-
-        :param full: Allow the full month name to be provided
-        :param abbreviation: Allow abbreviations of month names to be provided
-        :param numeric: Allow months to be specified as a decimal number
-        :param locale: An alternate locale to use when parsing input
-        :param out_format: A :class:`DTFormatMode` or str that matches a format mode.  Defaults to full month name.
-        :param out_locale: Alternate locale to use for output.  Defaults to the same value as ``locale``.
-        :param fix_default: Whether default values should be normalized using :meth:`~DTInput.fix_default`.
-        """
-        ...
+    ): ...
 
     def __init__(self, *, numeric: Bool = True, **kwargs):
         super().__init__(numeric=numeric, **kwargs)
@@ -403,6 +404,7 @@ class DateTimeInput(DTInput[DT], ABC):
     _type: Type[DT]
     _earliest: TimeBound = None
     _latest: TimeBound = None
+    # TODO: Add usage examples to the more user-friendly docs
 
     def __init_subclass__(cls, type: Type[DT], **kwargs):  # noqa
         super().__init_subclass__(dt_type=type.__name__, **kwargs)
@@ -501,6 +503,18 @@ class DateTimeInput(DTInput[DT], ABC):
 
 
 class DateTime(DateTimeInput[datetime], type=datetime):
+    """
+    Input type that accepts any number of datetime format strings for parsing input.  Parsing results in returning
+    a :class:`python:datetime.datetime` object.
+
+    :param formats: One or more :ref:`datetime format strings <python:strftime-strptime-behavior>`.  Defaults to
+      :data:`DEFAULT_DT_FMT`.
+    :param locale: An alternate locale to use when parsing input
+    :param earliest: If specified, the parsed value must be later than or equal to this
+    :param latest: If specified, the parsed value must be earlier than or equal to this
+    :param fix_default: Whether default values should be normalized using :meth:`~DTInput.fix_default`.
+    """
+
     def __init__(
         self,
         *formats: str,
@@ -509,23 +523,24 @@ class DateTime(DateTimeInput[datetime], type=datetime):
         latest: TimeBound = None,
         fix_default: Bool = True,
     ):
-        """
-        Input type that accepts any number of datetime format strings for parsing input.  Parsing results in returning
-        a :class:`python:datetime.datetime` object.
-
-        :param formats: One or more :ref:`datetime format strings <python:strftime-strptime-behavior>`.  Defaults to
-          :data:`DEFAULT_DT_FMT`.
-        :param locale: An alternate locale to use when parsing input
-        :param earliest: If specified, the parsed value must be later than or equal to this
-        :param latest: If specified, the parsed value must be earlier than or equal to this
-        :param fix_default: Whether default values should be normalized using :meth:`~DTInput.fix_default`.
-        """
         super().__init__(
             formats or (DEFAULT_DT_FMT,), locale=locale, earliest=earliest, latest=latest, fix_default=fix_default
         )
 
 
 class Date(DateTimeInput[date], type=date):
+    """
+    Input type that accepts any number of datetime format strings for parsing input.  Parsing results in returning
+    a :class:`python:datetime.date` object.
+
+    :param formats: One or more :ref:`datetime format strings <python:strftime-strptime-behavior>`.  Defaults to
+      :data:`DEFAULT_DT_FMT`.
+    :param locale: An alternate locale to use when parsing input
+    :param earliest: If specified, the parsed value must be later than or equal to this
+    :param latest: If specified, the parsed value must be earlier than or equal to this
+    :param fix_default: Whether default values should be normalized using :meth:`~DTInput.fix_default`.
+    """
+
     def __init__(
         self,
         *formats: str,
@@ -534,23 +549,24 @@ class Date(DateTimeInput[date], type=date):
         latest: TimeBound = None,
         fix_default: Bool = True,
     ):
-        """
-        Input type that accepts any number of datetime format strings for parsing input.  Parsing results in returning
-        a :class:`python:datetime.date` object.
-
-        :param formats: One or more :ref:`datetime format strings <python:strftime-strptime-behavior>`.  Defaults to
-          :data:`DEFAULT_DT_FMT`.
-        :param locale: An alternate locale to use when parsing input
-        :param earliest: If specified, the parsed value must be later than or equal to this
-        :param latest: If specified, the parsed value must be earlier than or equal to this
-        :param fix_default: Whether default values should be normalized using :meth:`~DTInput.fix_default`.
-        """
         super().__init__(
             formats or (DEFAULT_DATE_FMT,), locale=locale, earliest=earliest, latest=latest, fix_default=fix_default
         )
 
 
 class Time(DateTimeInput[time], type=time):
+    """
+    Input type that accepts any number of datetime format strings for parsing input.  Parsing results in returning
+    a :class:`python:datetime.time` object.
+
+    :param formats: One or more :ref:`datetime format strings <python:strftime-strptime-behavior>`.  Defaults to
+      :data:`DEFAULT_DT_FMT`.
+    :param locale: An alternate locale to use when parsing input
+    :param earliest: If specified, the parsed value must be later than or equal to this
+    :param latest: If specified, the parsed value must be earlier than or equal to this
+    :param fix_default: Whether default values should be normalized using :meth:`~DTInput.fix_default`.
+    """
+
     def __init__(
         self,
         *formats: str,
@@ -559,17 +575,6 @@ class Time(DateTimeInput[time], type=time):
         latest: TimeBound = None,
         fix_default: Bool = True,
     ):
-        """
-        Input type that accepts any number of datetime format strings for parsing input.  Parsing results in returning
-        a :class:`python:datetime.time` object.
-
-        :param formats: One or more :ref:`datetime format strings <python:strftime-strptime-behavior>`.  Defaults to
-          :data:`DEFAULT_DT_FMT`.
-        :param locale: An alternate locale to use when parsing input
-        :param earliest: If specified, the parsed value must be later than or equal to this
-        :param latest: If specified, the parsed value must be earlier than or equal to this
-        :param fix_default: Whether default values should be normalized using :meth:`~DTInput.fix_default`.
-        """
         super().__init__(
             formats or (DEFAULT_TIME_FMT,), locale=locale, earliest=earliest, latest=latest, fix_default=fix_default
         )

{cli_command_parser-2025.5.10 → cli_command_parser-2025.7.10}/lib/cli_command_parser/inputs/utils.py

@@ -11,7 +11,7 @@ import warnings
 from contextlib import contextmanager
 from pathlib import Path
 from stat import S_IFBLK, S_IFCHR, S_IFDIR, S_IFIFO, S_IFLNK, S_IFMT, S_IFREG, S_IFSOCK
-from typing import TYPE_CHECKING, Any, BinaryIO, ContextManager, TextIO, Union
+from typing import TYPE_CHECKING, Any, BinaryIO, Iterator, TextIO, Union
 from weakref import finalize
 
 from ..utils import FixedFlag
@@ -169,7 +169,7 @@ class FileWrapper:
             self._close()
 
     @contextmanager
-    def _file(self) -> ContextManager[FP]:
+    def _file(self) -> Iterator[FP]:
         try:
             yield self._open()
         finally:

cli_command_parser-2025.7.10/lib/cli_command_parser/parameters/__init__.py

@@ -0,0 +1,6 @@
+from .base import BaseOption, BasePositional, Parameter
+from .choice_map import Action, SubCommand
+from .groups import ParamGroup
+from .options import ActionFlag, Counter, Flag, Option, TriFlag, action_flag, after_main, before_main, help_action
+from .pass_thru import PassThru
+from .positionals import Positional

{cli_command_parser-2025.5.10 → cli_command_parser-2025.7.10}/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.5.10 → cli_command_parser-2025.7.10}/lib/cli_command_parser/parameters/options.py

@@ -410,6 +410,15 @@ class ActionFlag(Flag, repr_attrs=('order', 'before_main')):
         # Note: If func is None, then CommandParameters._process_action_flags raises ParameterDefinitionError
         return partial(self.func, command)  # imitates a bound method
 
+    def __reduce__(self):
+        # When a string is returned, it is treated as the name of a global variable.  Since this class acts as a
+        # decorator that replaces the decorated method, this approach is necessary to prevent the following kind of
+        # PicklingError: Can't pickle <function help_action ...>: it's not the same object as ...options.help_action
+        if self._func is not None:
+            return self.__qualname__
+        else:  # This is not generally expected
+            return super().__reduce__()
+
 
 #: Alias for :class:`ActionFlag`
 action_flag = ActionFlag  # pylint: disable=C0103

{cli_command_parser-2025.5.10 → cli_command_parser-2025.7.10}/lib/cli_command_parser/parameters/positionals.py

@@ -12,11 +12,11 @@ from ..exceptions import ParameterDefinitionError
 from ..inputs import normalize_input_type
 from ..nargs import Nargs, NargsValue
 from ..utils import _NotSet
-from .actions import Store, Append
-from .base import BasePositional, AllowLeadingDashProperty
+from .actions import Append, Store
+from .base import AllowLeadingDashProperty, BasePositional
 
 if TYPE_CHECKING:
-    from ..typing import InputTypeFunc, ChoicesType, LeadingDash, DefaultFunc
+    from ..typing import ChoicesType, DefaultFunc, InputTypeFunc, LeadingDash
 
 __all__ = ['Positional']
 

{cli_command_parser-2025.5.10 → cli_command_parser-2025.7.10}/lib/cli_command_parser/testing.py

@@ -13,7 +13,7 @@ from difflib import unified_diff
 from io import BytesIO, StringIO
 from pathlib import Path
 from tempfile import TemporaryDirectory
-from typing import IO, TYPE_CHECKING, Any, Callable, ContextManager, Dict, Iterable, List, Tuple, Type, Union
+from typing import IO, TYPE_CHECKING, Any, Callable, Iterable, Iterator, Type, Union
 from unittest import TestCase
 from unittest.mock import Mock, patch, seal
 
@@ -39,16 +39,16 @@ __all__ = [
     'TemporaryDir',
 ]
 
-Argv = List[str]
-Expected = Dict[str, Any]
-Kwargs = Dict[str, Any]
-Env = Dict[str, str]
-Case = Tuple[Argv, Expected]
-EnvCase = Tuple[Argv, Env, Expected]
+Argv = list[str]
+Expected = dict[str, Any]
+Kwargs = dict[str, Any]
+Env = dict[str, str]
+Case = tuple[Argv, Expected]
+EnvCase = tuple[Argv, Env, Expected]
 ExcType = Type[Exception]
-ExceptionCase = Union[Argv, Tuple[Argv, ExcType], Tuple[Argv, ExcType, str]]
+ExceptionCase = Union[Argv, tuple[Argv, ExcType], tuple[Argv, ExcType, str]]
 ExcCases = Iterable[ExceptionCase]
-CallExceptionCase = Union[Tuple[Kwargs, ExcType], Tuple[Kwargs, ExcType, str]]
+CallExceptionCase = Union[tuple[Kwargs, ExcType], tuple[Kwargs, ExcType, str]]
 CallExceptionCases = Iterable[CallExceptionCase]
 
 OPT_ENV_MOD = 'cli_command_parser.parser.environ'
@@ -344,7 +344,7 @@ def sealed_mock(*args, **kwargs):
 
 
 @contextmanager
-def load_command(directory: Path, name: str, cmd_name: str, **kwargs) -> ContextManager[CommandCls]:
+def load_command(directory: Path, name: str, cmd_name: str, **kwargs) -> Iterator[CommandCls]:
     path = directory.joinpath(name)
     with Context.for_prog(path, **kwargs):
         yield load_commands(path)[cmd_name]

{cli_command_parser-2025.5.10 → cli_command_parser-2025.7.10/lib/cli_command_parser.egg-info}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: cli_command_parser
-Version: 2025.5.10
+Version: 2025.7.10
 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.5.10 → cli_command_parser-2025.7.10}/lib/cli_command_parser.egg-info/SOURCES.txt

@@ -16,7 +16,6 @@ lib/cli_command_parser/config.py
 lib/cli_command_parser/context.py
 lib/cli_command_parser/core.py
 lib/cli_command_parser/documentation.py
-lib/cli_command_parser/error_handling.py
 lib/cli_command_parser/exceptions.py
 lib/cli_command_parser/metadata.py
 lib/cli_command_parser/nargs.py
@@ -39,6 +38,10 @@ lib/cli_command_parser/conversion/cli.py
 lib/cli_command_parser/conversion/command_builder.py
 lib/cli_command_parser/conversion/utils.py
 lib/cli_command_parser/conversion/visitor.py
+lib/cli_command_parser/error_handling/__init__.py
+lib/cli_command_parser/error_handling/base.py
+lib/cli_command_parser/error_handling/other.py
+lib/cli_command_parser/error_handling/windows.py
 lib/cli_command_parser/formatting/__init__.py
 lib/cli_command_parser/formatting/commands.py
 lib/cli_command_parser/formatting/params.py

{cli_command_parser-2025.5.10 → cli_command_parser-2025.7.10}/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

cli_command_parser-2025.5.10/lib/cli_command_parser/conversion/__init__.py

@@ -1,3 +0,0 @@
-from .argparse_ast import Script, AstCallable, ArgCollection, AstArgumentParser, SubParser, AddVisitedChild, visit_func
-from .argparse_ast import ArgGroup, MutuallyExclusiveGroup
-from .command_builder import Converter, convert_script

cli_command_parser-2025.5.10/lib/cli_command_parser/parameters/__init__.py

@@ -1,6 +0,0 @@
-from .base import Parameter, BasePositional, BaseOption
-from .choice_map import SubCommand, Action
-from .groups import ParamGroup
-from .options import Option, Flag, Counter, ActionFlag, action_flag, before_main, after_main, TriFlag, help_action
-from .pass_thru import PassThru
-from .positionals import Positional