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

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

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: cli_command_parser
-Version: 2025.5.10
+Version: 2025.6.14
 Summary: CLI Command Parser
 Home-page: https://github.com/dskrypa/cli_command_parser
 Author: Doug Skrypa

{cli_command_parser-2025.5.10 → cli_command_parser-2025.6.14}/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.6.14}/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.06.14'
 __author__ = 'Doug Skrypa'
 __author_email__ = 'dskrypa@gmail.com'
 __license__ = 'Apache 2.0'

cli_command_parser-2025.6.14/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.6.14}/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.6.14}/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.6.14/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.6.14/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.6.14/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.6.14/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.6.14}/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.6.14}/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.6.14}/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.6.14}/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.6.14}/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.6.14}/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.6.14/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.6.14}/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.6.14}/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.6.14}/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.6.14/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.6.14
 Summary: CLI Command Parser
 Home-page: https://github.com/dskrypa/cli_command_parser
 Author: Doug Skrypa

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