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

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

@@ -1,6 +1,6 @@
 Metadata-Version: 2.1
 Name: cli_command_parser
-Version: 2024.9.7
+Version: 2024.12.15
 Summary: CLI Command Parser
 Home-page: https://github.com/dskrypa/cli_command_parser
 Author: Doug Skrypa
@@ -16,27 +16,25 @@ 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.8
 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.8
+Requires-Python: >=3.9
 Description-Content-Type: text/x-rst
 License-File: LICENSE
 Provides-Extra: wcwidth
 Requires-Dist: wcwidth; extra == "wcwidth"
-Provides-Extra: conversion
-Requires-Dist: astunparse; python_version < "3.9" and extra == "conversion"
 
 CLI Command Parser
 ##################
 
 |downloads| |py_version| |coverage_badge| |build_status| |Ruff|
 
-.. |py_version| image:: https://img.shields.io/badge/python-3.8%20%7C%203.9%20%7C%203.10%20%7C%203.11%20%7C%203.12%20-blue
+.. |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
@@ -118,18 +116,8 @@ with optional dependencies::
 Python Version Compatibility
 ============================
 
-Python versions 3.8 and above are currently supported.  The last release of CLI Command Parser that supported 3.7 was
-2023-04-30.  Support for Python 3.7 `officially ended on 2023-06-27 <https://devguide.python.org/versions/>`__.
-
-When using Python 3.8, some additional packages that backport functionality that was added in later Python versions
-are required for compatibility.
-
-To use the argparse to cli-command-parser conversion script with Python 3.8, there is a dependency on
-`astunparse <https://astunparse.readthedocs.io>`__.  If you are using Python 3.9 or above, then ``astunparse`` is not
-necessary because the relevant code was added to the stdlib ``ast`` module.  If you're unsure, you can install
-cli-command-parser with the following command to automatically handle whether that extra dependency is needed or not::
-
-    $ pip install -U cli-command-parser[conversion]
+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

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

{cli_command_parser-2024.9.7 → cli_command_parser-2024.12.15}/lib/cli_command_parser/annotations.py

@@ -7,7 +7,7 @@ Utilities for extracting types from annotations.
 from collections.abc import Collection, Iterable
 from functools import lru_cache
 from inspect import isclass
-from typing import Union, Optional, get_type_hints as _get_type_hints, get_origin, get_args as _get_args
+from typing import Optional, Union, get_args, get_origin, get_type_hints as _get_type_hints
 
 try:
     from types import NoneType
@@ -42,15 +42,6 @@ def get_annotation_value_type(annotation, from_union: bool = True, from_collecti
     return None
 
 
-def get_args(annotation) -> tuple:
-    """
-    Wrapper around :func:`python:typing.get_args` for 3.7~8 compatibility, to make it behave more like it does in 3.9+
-    """
-    if getattr(annotation, '_special', False):  # 3.7-3.8 generic collection alias with no content types
-        return ()
-    return _get_args(annotation)
-
-
 def _type_from_union(annotation) -> Optional[type]:
     args = get_args(annotation)
     # Note: Unions of a single argument return the argument; i.e., Union[T] returns T, so the len can never be 1

{cli_command_parser-2024.9.7 → cli_command_parser-2024.12.15}/lib/cli_command_parser/compat.py

@@ -1,9 +1,4 @@
 """
-Compatibility / Patch module - used to back-port features to Python 3.7 and to avoid breaking changes in Enum/Flag in
-3.11.
-
-Contains stdlib CPython functions / classes from Python 3.8 and 3.10.
-
 The :class:`WCTextWrapper` in this module extends the stdlib :class:`python:textwrap.TextWrapper` to support wide
 characters.
 """
@@ -16,8 +11,6 @@ from .utils import wcswidth
 
 __all__ = ['WCTextWrapper']
 
-# region textwrap
-
 
 class WCTextWrapper(TextWrapper):
     """
@@ -119,6 +112,3 @@ class WCTextWrapper(TextWrapper):
                     break
 
         return lines
-
-
-# endregion

{cli_command_parser-2024.9.7 → cli_command_parser-2024.12.15}/lib/cli_command_parser/conversion/utils.py

@@ -1,24 +1,7 @@
 from __future__ import annotations
 
-from ast import AST, expr, Call, Attribute, Name, Dict, List, Set, Tuple
-
-try:
-    from ast import unparse
-except ImportError:  # added in 3.9
-    try:
-        from astunparse import unparse as _unparse
-    except ImportError as e:
-        raise RuntimeError(
-            'Missing required dependency: astunparse (only required in Python 3.8 and below'
-            ' - upgrade to 3.9 or above to avoid this dependency)'
-        )
-    else:
-
-        def unparse(node):
-            return ''.join(_unparse(node).splitlines())
-
-
-from typing import Union, Iterator, List as _List
+from ast import AST, Attribute, Call, Dict, List, Name, Set, Tuple, expr, unparse
+from typing import Iterator, List as _List, Union
 
 __all__ = ['get_name_repr', 'iter_module_parents', 'collection_contents']
 

{cli_command_parser-2024.9.7 → cli_command_parser-2024.12.15}/lib/cli_command_parser/documentation.py

@@ -372,6 +372,6 @@ class RstWriter:
         path = target_dir.joinpath(name + self.ext)
         log.debug(f'{prefix} {path.as_posix()}')
         if not self.dry_run:
-            # Path.write_text on 3.8 does not support `newline`
+            # Path.write_text on 3.9 does not support `newline`
             with path.open('w', encoding=self.encoding, newline=self.newline) as f:
                 f.write(content)

{cli_command_parser-2024.9.7 → cli_command_parser-2024.12.15}/lib/cli_command_parser/exceptions.py

@@ -8,14 +8,14 @@ Exceptions for Command Parser
 from __future__ import annotations
 
 import sys
-from typing import TYPE_CHECKING, Any, Optional, Collection, Mapping
+from typing import TYPE_CHECKING, Any, Collection, Mapping, Optional
 
 from .utils import _parse_tree_target_repr
 
 if TYPE_CHECKING:
-    from .parameters import Parameter, BaseOption
+    from .parameters import BaseOption, Parameter
+    from .parse_tree import PosNode, Target, Word
     from .typing import ParamOrGroup
-    from .parse_tree import PosNode, Word, Target
 
 __all__ = [
     'CommandParserException',
@@ -211,13 +211,13 @@ class BadArgument(ParamUsageError):
 class InvalidChoice(BadArgument):
     """Error raised when a value that does not match one of the pre-defined choices was provided for a Parameter"""
 
-    def __init__(self, param: Optional[Parameter], invalid: Any, choices: Collection[Any]):
+    def __init__(self, param: Optional[Parameter], invalid: Any, choices: Collection[Any], env_var: str = None):
+        src = f' from env var={env_var!r}' if env_var else ''
         if isinstance(invalid, Collection) and not isinstance(invalid, str):
-            bad_str = f'choices: {", ".join(map(repr, invalid))}'
+            bad_str = f'choices{src}: {", ".join(map(repr, invalid))}'
         else:
-            bad_str = f'choice: {invalid!r}'
-        choices_str = ', '.join(map(repr, choices))
-        super().__init__(param, f'invalid {bad_str} (choose from: {choices_str})')
+            bad_str = f'choice{src}: {invalid!r}'
+        super().__init__(param, f'invalid {bad_str} (choose from: {", ".join(map(repr, choices))})')
 
 
 class MissingArgument(BadArgument):

{cli_command_parser-2024.9.7 → cli_command_parser-2024.12.15}/lib/cli_command_parser/formatting/commands.py

@@ -12,9 +12,10 @@ from typing import TYPE_CHECKING, Callable, Iterable, Iterator, Optional, Type,
 
 from ..context import NoActiveContext, ctx
 from ..core import get_metadata, get_params
+from ..parameters.choice_map import ChoiceMap
 from ..parameters.groups import ParamGroup
 from ..utils import _NotSet, camel_to_snake_case
-from .restructured_text import RstTable, spaced_rst_header
+from .restructured_text import spaced_rst_header
 from .utils import PartWrapper
 
 if TYPE_CHECKING:
@@ -47,6 +48,7 @@ class CommandHelpFormatter:
         for group in groups:
             if group.group:  # prevent duplicates
                 continue
+
             if group.contains_positional:
                 self.pos_group.add(group)
             else:
@@ -162,14 +164,17 @@ class CommandHelpFormatter:
             yield description
             yield ''
 
-        # TODO: The subcommand names in the group containing subcommand targets should link to their respective
-        #  subcommand sections
-        for group in self.groups:
+        if self.pos_group.show_in_help:
             # TODO: Nested subcommands' local choices should not repeat the `subcommands` positional arguments section
             #  that includes the nested subcommand choice being documented
+            if len(members := self.pos_group.members) == 1 and isinstance(members[0], ChoiceMap):
+                yield from members[0].formatter.rst_table().iter_build()  # noqa
+            else:
+                yield from self.pos_group.formatter.rst_table().iter_build()
+
+        for group in self.groups[1:]:
             if group.show_in_help:
-                table: RstTable = group.formatter.rst_table()  # noqa
-                yield from table.iter_build()
+                yield from group.formatter.rst_table().iter_build()
 
         if include_epilog and (epilog := self._meta.format_epilog(config.extended_epilog, allow_sys_argv)):
             yield epilog

{cli_command_parser-2024.9.7 → cli_command_parser-2024.12.15}/lib/cli_command_parser/formatting/params.py

@@ -16,7 +16,7 @@ from ..core import get_config
 from ..parameters import ParamGroup, PassThru, TriFlag
 from ..parameters.base import BaseOption, BasePositional
 from ..parameters.choice_map import Choice, ChoiceMap
-from .restructured_text import RstTable
+from .restructured_text import Cell, Row, RstTable
 from .utils import _should_add_default, format_help_entry
 
 if TYPE_CHECKING:
@@ -223,6 +223,8 @@ class TriFlagHelpFormatter(OptionHelpFormatter, param_cls=TriFlag):
 
 
 class ChoiceMapHelpFormatter(ParamHelpFormatter, param_cls=ChoiceMap):
+    """Formatter for :class:`SubCommand` and :class:`Action` parameters (and any other params that extend ChoiceMap)"""
+
     param: ChoiceMap
 
     @cached_property
@@ -269,6 +271,7 @@ class ChoiceMapHelpFormatter(ParamHelpFormatter, param_cls=ChoiceMap):
 
     def _format_rst_rows(self) -> Iterator[tuple[str, OptStr]]:
         mode = ctx.config.cmd_alias_mode or SubcommandAliasHelpMode.ALIAS
+        # TODO: The subcommand names should link to their respective subcommand sections
         for choice_group in self.choice_groups:
             for choice, usage, description in choice_group.prepare(mode):
                 yield f'``{usage}``', description
@@ -492,15 +495,19 @@ class GroupHelpFormatter(ParamHelpFormatter, param_cls=ParamGroup):  # noqa  # p
         table = RstTable(self.format_description())
         # TODO: non-nested when config.show_group_tree is False; maybe separate options for rst vs help
         for member in self.param.members:
-            if member.show_in_help:
-                formatter = member.formatter
-                try:
-                    sub_table: RstTable = formatter.rst_table()  # noqa
-                except AttributeError:
-                    table.add_rows(formatter.rst_rows())
-                else:
-                    sub_table.show_title = False
-                    table.add_row(sub_table.title, str(sub_table))
+            if not member.show_in_help:
+                continue
+
+            formatter = member.formatter
+            try:
+                sub_table: RstTable = formatter.rst_table()  # noqa
+            except AttributeError:
+                table.add_rows(formatter.rst_rows())
+            else:
+                table._add_row(Row([Cell(str(sub_table), ext_right=True), Cell()]))
+                # If a config option to switch to the old way is added later, the old approach:
+                # sub_table.show_title = False
+                # table.add_row(sub_table.title, str(sub_table))
 
         return table
 

{cli_command_parser-2024.9.7 → cli_command_parser-2024.12.15}/lib/cli_command_parser/formatting/restructured_text.py

@@ -6,11 +6,8 @@ Utilities for formatting data using RST markup
 
 from __future__ import annotations
 
-from itertools import starmap
 from typing import TYPE_CHECKING, Any, Iterable, Iterator, Mapping, Sequence, TypeVar, Union
 
-from .utils import line_iter
-
 if TYPE_CHECKING:
     from ..typing import Bool, OptStr, Strings
 
@@ -119,7 +116,7 @@ class RstTable:
       body of this table.
     """
 
-    __slots__ = ('title', 'subtitle', 'show_title', 'use_table_directive', 'rows', 'widths')
+    __slots__ = ('title', 'subtitle', 'show_title', 'use_table_directive', '_rows', '_widths', '_updated')
 
     def __init__(
         self,
@@ -134,8 +131,9 @@ class RstTable:
         self.subtitle = subtitle
         self.show_title = show_title
         self.use_table_directive = use_table_directive
-        self.rows = []
-        self.widths = []
+        self._rows = []
+        self._widths = ()
+        self._updated = False
         if headers:
             self.add_row(*headers, header=True)
 
@@ -163,6 +161,13 @@ class RstTable:
         table.add_kv_rows(data)
         return table
 
+    @property
+    def widths(self) -> tuple[int, ...]:
+        if self._updated:
+            self._widths = tuple(max(col) for col in zip(*(row.widths() for row in self._rows)))
+            self._updated = False
+        return self._widths
+
     def add_dict_rows(self, rows: RowMaps, columns: Sequence[T] = None, add_header: Bool = False):
         """Add a row for each dict in the given sequence of rows, where the keys represent the columns."""
         if not columns:
@@ -180,8 +185,11 @@ class RstTable:
         self.add_rows(data.items())
 
     def add_rows(self, rows: Iterable[Iterable[OptStr]]):
-        for row in rows:
-            self.add_row(*row)
+        self._add_rows(Row([Cell(c or '') for c in columns]) for columns in rows)
+
+    def _add_rows(self, rows: Iterable[Row]):
+        self._rows.extend(rows)
+        self._updated = True
 
     def add_row(self, *columns: OptStr, index: int = None, header: bool = False):
         """
@@ -192,34 +200,18 @@ class RstTable:
           the list of rows.
         :param header: If True, this row will be treated as a header row.  Does not affect insertion order.
         """
-        any_new_line, widths = _widths(columns)
-        if self.widths:
-            self.widths = tuple(starmap(max, zip(self.widths, widths)))
-        else:
-            self.widths = tuple(widths)
+        self._add_row(Row([Cell(c or '') for c in columns], header), index)
 
-        columns = tuple(c or '' for c in columns)
+    def _add_row(self, row: Row, index: int = None):
         if index is None:
-            self.rows.append((header, any_new_line, columns))
+            self._rows.append(row)
         else:
-            self.rows.insert(index, (header, any_new_line, columns))
-
-    def bar(self, char: str = '-') -> str:
-        """
-        :param char: The character to use for the bar.  Defaults to ``-`` (for normal rows).  Use ``=`` below a header
-          row.  See :du_rst:`Grid Tables<grid-tables>` for more info.
-        :return: The formatted bar string
-        """
-        pre = '    ' if self.use_table_directive else ''
-        return '+'.join([pre, *(char * (w + 2) for w in self.widths), ''])
-
-    def _get_row_format(self) -> str:
-        pre = '    ' if self.use_table_directive else ''
-        return '|'.join([pre, *(f' {{:<{w}s}} ' for w in self.widths), ''])
+            self._rows.insert(index, row)
+        self._updated = True
 
     def __repr__(self) -> str:
         return (
-            f'<RstTable[use_table_directive={self.use_table_directive}, rows={len(self.rows)},'
+            f'<RstTable[use_table_directive={self.use_table_directive}, rows={len(self._rows)},'
             f' title={self.title!r}, widths={self.widths}]>'
         )
 
@@ -230,38 +222,85 @@ class RstTable:
             yield ''
 
         if self.use_table_directive:
-            options = {'subtitle': self.subtitle, 'widths': 'auto'}
-            yield from _rst_directive('table', options=options, check=True)
+            yield from _rst_directive('table', options={'subtitle': self.subtitle, 'widths': 'auto'}, check=True)
             yield ''
-
-        bar, header_bar = self.bar(), self.bar('=')
-        format_row = self._get_row_format().format
-        yield bar
-        for header, any_new_line, row in self.rows:
-            if any_new_line:
-                for line in line_iter(*row):
-                    yield format_row(*line)
-            else:
-                yield format_row(*row)
-
-            yield header_bar if header else bar
+            for line in self._iter_render():
+                yield '    ' + line
+        else:
+            yield from self._iter_render()
 
         yield ''
 
+    def _iter_render(self) -> Iterator[str]:
+        col_widths = self.widths
+        yield self._rows[0].render_upper_bar(col_widths)
+        for row in self._rows:
+            yield from row.render_lines(col_widths)
+
     def __str__(self) -> str:
         return '\n'.join(self.iter_build())
 
 
-def _widths(columns: Iterable[OptStr]) -> tuple[bool, list[int]]:
-    widths = []
-    any_new_line = False
-    for column in columns:
-        if not column:
-            widths.append(0)
-        elif '\n' in column:
-            any_new_line = True
-            widths.append(max(map(len, column.splitlines())))
+class Cell:
+    __slots__ = ('text', 'lines', 'width', 'height', 'brd_bottom', 'brd_right')
+
+    def __init__(self, text: str = '', *, ext_right: bool = False, ext_below: bool = False):
+        self.text = text
+        if text:
+            self.lines = text.splitlines()
+            self.width = max(map(len, self.lines))
+            self.height = len(self.lines)
         else:
-            widths.append(len(column))
+            self.lines = ['']
+            self.width = 0
+            self.height = 1
+
+        self.brd_bottom = not ext_below
+        self.brd_right = not ext_right
+
+    def render_upper_bar(self, width: int) -> str:
+        return ('-' * (width + 2)) + ('+' if self.brd_bottom else '|')
+
+    def render_lower_bar(self, width: int, char: str = '-') -> str:
+        if not self.brd_bottom:
+            char = ' '
+        return (char * (width + 2)) + ('+' if self.brd_bottom or self.brd_right else ' ')
+
+    def render_lines(self, width: int, max_lines: int) -> Iterator[str]:
+        format_line = f' {{:<{width}s}} {"|" if self.brd_right else " "}'.format
+        for line in self.lines:
+            yield format_line(line)
+
+        for _ in range(self.height, max_lines):
+            yield format_line('')
+
+    def __repr__(self) -> str:
+        return f'<{self.__class__.__name__}[{self.text!r}, width={self.width}, height={self.height}]>'
+
+
+class Row:
+    __slots__ = ('cells', 'header')
+
+    def __init__(self, cells: list[Cell], header: bool = False):
+        self.cells = cells
+        self.header = header
+
+    def widths(self) -> Iterator[int]:
+        for cell in self.cells:
+            yield cell.width
+
+    def render_upper_bar(self, widths: Sequence[int]) -> str:
+        return '+' + ''.join(cell.render_upper_bar(w) for cell, w in zip(self.cells, widths))
+
+    def render_lower_bar(self, widths: Sequence[int]) -> str:
+        char = '=' if self.header else '-'
+        first = '+' if self.cells[0].brd_bottom else '|'
+        return first + ''.join(cell.render_lower_bar(w, char) for cell, w in zip(self.cells, widths))
+
+    def render_lines(self, widths: Sequence[int]) -> Iterator[str]:
+        max_lines = max(cell.height for cell in self.cells)
+        renderers = [cell.render_lines(w, max_lines) for cell, w in zip(self.cells, widths)]
+        for cell_strs in zip(*renderers):
+            yield '|' + ''.join(cell_strs)
 
-    return any_new_line, widths
+        yield self.render_lower_bar(widths)

{cli_command_parser-2024.9.7 → cli_command_parser-2024.12.15}/lib/cli_command_parser/inputs/base.py

@@ -7,7 +7,7 @@ Custom input handlers for Parameters
 from abc import ABC, abstractmethod
 from typing import Any, Generic, Optional
 
-from ..typing import T, Bool
+from ..typing import Bool, T
 
 __all__ = ['InputType']
 
@@ -25,11 +25,11 @@ class InputType(Generic[T], ABC):
 
     def is_valid_type(self, value: str) -> bool:  # pylint: disable=W0613
         """
-        Called during parsing when :meth:`.Parameter.would_accept` is called to determine if the value would be
+        Called during parsing when :meth:`.ParamAction.would_accept` is called to determine if the value would be
         accepted later for processing / conversion via :meth:`.__call__`.  May be overridden in subclasses to
         provide actual validation, if necessary.
 
-        Not called by :meth:`.Parameter.take_action` - value validation should happen in :meth:`.__call__`
+        Note: value validation should happen in :meth:`.__call__`, not in this method.
 
         :param value: A parsed argument
         :return: True if this input would accept it for processing later (where it may still be rejected), False if

{cli_command_parser-2024.9.7 → cli_command_parser-2024.12.15}/lib/cli_command_parser/inputs/numeric.py

@@ -26,7 +26,7 @@ class NumericInput(InputType[NT], ABC):
 
     def is_valid_type(self, value: str) -> bool:
         """
-        Called during parsing when :meth:`.Parameter.would_accept` is called to determine if the value would be
+        Called during parsing when :meth:`.ParamAction.would_accept` is called to determine if the value would be
         accepted later for processing / conversion when called.
 
         :param value: The parsed argument to validate