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

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

@@ -1,130 +1,134 @@
-Metadata-Version: 2.1
-Name: cli_command_parser
-Version: 2024.12.15
-Summary: CLI Command Parser
-Home-page: https://github.com/dskrypa/cli_command_parser
-Author: Doug Skrypa
-Author-email: dskrypa@gmail.com
-License: Apache 2.0
-Project-URL: Source, https://github.com/dskrypa/cli_command_parser
-Project-URL: Documentation, https://dskrypa.github.io/cli_command_parser
-Project-URL: Issues, https://github.com/dskrypa/cli_command_parser/issues
-Classifier: Development Status :: 5 - Production/Stable
-Classifier: Environment :: Console
-Classifier: Intended Audience :: Developers
-Classifier: License :: OSI Approved :: Apache Software License
-Classifier: Operating System :: OS Independent
-Classifier: Programming Language :: Python
-Classifier: Programming Language :: Python :: 3
-Classifier: Programming Language :: Python :: 3.9
-Classifier: Programming Language :: Python :: 3.10
-Classifier: Programming Language :: Python :: 3.11
-Classifier: Programming Language :: Python :: 3.12
-Classifier: Programming Language :: Python :: 3.13
-Classifier: Topic :: Software Development :: User Interfaces
-Classifier: Topic :: Text Processing
-Requires-Python: >=3.9
-Description-Content-Type: text/x-rst
-License-File: LICENSE
-Provides-Extra: wcwidth
-Requires-Dist: wcwidth; extra == "wcwidth"
-
-CLI Command Parser
-##################
-
-|downloads| |py_version| |coverage_badge| |build_status| |Ruff|
-
-.. |py_version| image:: https://img.shields.io/badge/python-3.9%20%7C%203.10%20%7C%203.11%20%7C%203.12%20%7C%203.13%20-blue
-    :target: https://pypi.org/project/cli-command-parser/
-
-.. |coverage_badge| image:: https://codecov.io/gh/dskrypa/cli_command_parser/branch/main/graph/badge.svg
-    :target: https://codecov.io/gh/dskrypa/cli_command_parser
-
-.. |build_status| image:: https://github.com/dskrypa/cli_command_parser/actions/workflows/run-tests.yml/badge.svg
-    :target: https://github.com/dskrypa/cli_command_parser/actions/workflows/run-tests.yml
-
-.. |Ruff| image:: https://img.shields.io/endpoint?url=https://raw.githubusercontent.com/astral-sh/ruff/main/assets/badge/v2.json
-    :target: https://docs.astral.sh/ruff/
-
-.. |downloads| image:: https://img.shields.io/pypi/dm/cli-command-parser
-    :target: https://pypistats.org/packages/cli-command-parser
-
-
-CLI Command Parser is a class-based CLI argument parser that defines parameters with descriptors.  It provides the
-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
-
-
-Example Program
-***************
-
-.. code-block:: python
-
-    from cli_command_parser import Command, Option, main
-
-    class Hello(Command, description='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')
-
-        def main(self):
-            for _ in range(self.count):
-                print(f'Hello {self.name}!')
-
-    if __name__ == '__main__':
-        main()
-
-
-.. code-block:: shell-session
-
-    $ hello_world.py --name Bob -c 3
-    Hello Bob!
-    Hello Bob!
-    Hello Bob!
-
-    $ hello_world.py -h
-    usage: hello_world.py [--name NAME] [--count COUNT] [--help]
-
-    Simple greeting example
-
-    Optional arguments:
-      --name NAME, -n NAME        The person to say hello to (default: 'World')
-      --count COUNT, -c COUNT     Number of times to repeat the message (default: 1)
-      --help, -h                  Show this help message and exit
-
-
-Installing CLI Command Parser
-*****************************
-
-CLI Command Parser can be installed and updated via `pip <https://pip.pypa.io/en/stable/getting-started/>`__::
-
-    $ pip install -U cli-command-parser
-
-
-There are no required dependencies.  Support for formatting wide characters correctly in help text descriptions can
-be included by adding `wcwidth <https://wcwidth.readthedocs.io>`__ to your project's requirements, and/or by installing
-with optional dependencies::
-
-    $ pip install -U cli-command-parser[wcwidth]
-
-
-Python Version Compatibility
-============================
-
-Python versions 3.9 and above are currently supported.  The last release of CLI Command Parser that supported 3.8 was
-2024-09-07.  Support for Python 3.8 `officially ended on 2024-10-07 <https://devguide.python.org/versions/>`__.
-
-
-Links
-*****
-
-- Documentation: https://dskrypa.github.io/cli_command_parser/
-- Example Scripts: https://github.com/dskrypa/cli_command_parser/tree/main/examples
-- PyPI Releases: https://pypi.org/project/cli-command-parser/
-- Source Code: https://github.com/dskrypa/cli_command_parser
-- Issue Tracker: https://github.com/dskrypa/cli_command_parser/issues
+Metadata-Version: 2.4
+Name: cli_command_parser
+Version: 2025.6.14
+Summary: CLI Command Parser
+Home-page: https://github.com/dskrypa/cli_command_parser
+Author: Doug Skrypa
+Author-email: dskrypa@gmail.com
+License: Apache 2.0
+Project-URL: Source, https://github.com/dskrypa/cli_command_parser
+Project-URL: Documentation, https://dskrypa.github.io/cli_command_parser
+Project-URL: Issues, https://github.com/dskrypa/cli_command_parser/issues
+Classifier: Development Status :: 5 - Production/Stable
+Classifier: Environment :: Console
+Classifier: Intended Audience :: Developers
+Classifier: License :: OSI Approved :: Apache Software License
+Classifier: Operating System :: OS Independent
+Classifier: Programming Language :: Python
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3.9
+Classifier: Programming Language :: Python :: 3.10
+Classifier: Programming Language :: Python :: 3.11
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Programming Language :: Python :: 3.13
+Classifier: Topic :: Software Development :: User Interfaces
+Classifier: Topic :: Text Processing
+Requires-Python: >=3.9
+Description-Content-Type: text/x-rst
+License-File: LICENSE
+Provides-Extra: wcwidth
+Requires-Dist: wcwidth; extra == "wcwidth"
+Dynamic: license-file
+
+CLI Command Parser
+##################
+
+|downloads| |py_version| |coverage_badge| |build_status| |Ruff| |OpenSSF Best Practices|
+
+.. |py_version| image:: https://img.shields.io/badge/python-3.9%20%7C%203.10%20%7C%203.11%20%7C%203.12%20%7C%203.13%20-blue
+    :target: https://pypi.org/project/cli-command-parser/
+
+.. |coverage_badge| image:: https://codecov.io/gh/dskrypa/cli_command_parser/branch/main/graph/badge.svg
+    :target: https://codecov.io/gh/dskrypa/cli_command_parser
+
+.. |build_status| image:: https://github.com/dskrypa/cli_command_parser/actions/workflows/run-tests.yml/badge.svg
+    :target: https://github.com/dskrypa/cli_command_parser/actions/workflows/run-tests.yml
+
+.. |Ruff| image:: https://img.shields.io/endpoint?url=https://raw.githubusercontent.com/astral-sh/ruff/main/assets/badge/v2.json
+    :target: https://docs.astral.sh/ruff/
+
+.. |downloads| image:: https://img.shields.io/pypi/dm/cli-command-parser
+    :target: https://pypistats.org/packages/cli-command-parser
+
+.. |OpenSSF Best Practices| image:: https://www.bestpractices.dev/projects/9845/badge
+    :target: https://www.bestpractices.dev/projects/9845
+
+
+CLI Command Parser is a class-based CLI argument parser that defines parameters with descriptors.  It provides the
+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
+
+
+Example Program
+***************
+
+.. code-block:: python
+
+    from cli_command_parser import Command, Option, main
+
+    class Hello(Command, description='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')
+
+        def main(self):
+            for _ in range(self.count):
+                print(f'Hello {self.name}!')
+
+    if __name__ == '__main__':
+        main()
+
+
+.. code-block:: shell-session
+
+    $ hello_world.py --name Bob -c 3
+    Hello Bob!
+    Hello Bob!
+    Hello Bob!
+
+    $ hello_world.py -h
+    usage: hello_world.py [--name NAME] [--count COUNT] [--help]
+
+    Simple greeting example
+
+    Optional arguments:
+      --name NAME, -n NAME        The person to say hello to (default: 'World')
+      --count COUNT, -c COUNT     Number of times to repeat the message (default: 1)
+      --help, -h                  Show this help message and exit
+
+
+Installing CLI Command Parser
+*****************************
+
+CLI Command Parser can be installed and updated via `pip <https://pip.pypa.io/en/stable/getting-started/>`__::
+
+    $ pip install -U cli-command-parser
+
+
+There are no required dependencies.  Support for formatting wide characters correctly in help text descriptions can
+be included by adding `wcwidth <https://wcwidth.readthedocs.io>`__ to your project's requirements, and/or by installing
+with optional dependencies::
+
+    $ pip install -U cli-command-parser[wcwidth]
+
+
+Python Version Compatibility
+============================
+
+Python versions 3.9 and above are currently supported.  The last release of CLI Command Parser that supported 3.8 was
+2024-09-07.  Support for Python 3.8 `officially ended on 2024-10-07 <https://devguide.python.org/versions/>`__.
+
+
+Links
+*****
+
+- Documentation: https://dskrypa.github.io/cli_command_parser/
+- Example Scripts: https://github.com/dskrypa/cli_command_parser/tree/main/examples
+- PyPI Releases: https://pypi.org/project/cli-command-parser/
+- Source Code: https://github.com/dskrypa/cli_command_parser
+- Issue Tracker: https://github.com/dskrypa/cli_command_parser/issues

{cli_command_parser-2024.12.15 → 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-2024.12.15 → cli_command_parser-2025.6.14}/lib/cli_command_parser/__version__.py

@@ -1,8 +1,8 @@
 __title__ = 'cli_command_parser'
 __description__ = 'CLI Command Parser'
 __url__ = 'https://github.com/dskrypa/cli_command_parser'
-__version__ = '2024.12.15'
+__version__ = '2025.06.14'
 __author__ = 'Doug Skrypa'
 __author_email__ = 'dskrypa@gmail.com'
 __license__ = 'Apache 2.0'
-__copyright__ = 'Copyright 2023 Doug Skrypa'
+__copyright__ = 'Copyright 2024 Doug Skrypa'

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-2024.12.15 → 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-2024.12.15 → 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-2024.12.15/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