cli-command-parser 2023.4.10__tar.gz → 2023.4.16__tar.gz

{cli_command_parser-2023.4.10 → cli_command_parser-2023.4.16}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.1
 Name: cli_command_parser
-Version: 2023.4.10
+Version: 2023.4.16
 Summary: CLI Command Parser
 Home-page: https://github.com/dskrypa/cli_command_parser
 Author: Doug Skrypa
@@ -111,6 +111,23 @@ with optional dependencies::
     $ pip install -U cli-command-parser[wcwidth]
 
 
+Python Version Compatibility
+============================
+
+Python versions 3.7 and above are currently supported.  CLI Command Parser will no longer support 3.7 after 2023-04-30,
+ahead of the `official end of support for 3.7 on 2023-06-27 <https://devguide.python.org/versions/>`__.
+
+When using 3.7 or 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.7 or 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]
+
+
 Links
 *****
 

{cli_command_parser-2023.4.10 → cli_command_parser-2023.4.16}/lib/cli_command_parser/__init__.py

@@ -4,7 +4,14 @@ Command Parser
 :author: Doug Skrypa
 """
 
-from .config import CommandConfig, ShowDefaults, OptionNameMode, SubcommandAliasHelpMode
+from .config import (
+    CommandConfig,
+    ShowDefaults,
+    OptionNameMode,
+    SubcommandAliasHelpMode,
+    AmbiguousComboMode,
+    AllowLeadingDash,
+)
 from .commands import Command, main
 from .context import Context, get_current_context, ctx, get_parsed, get_context, get_raw_arg
 from .exceptions import (

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

{cli_command_parser-2023.4.10 → cli_command_parser-2023.4.16}/lib/cli_command_parser/command_parameters.py

@@ -50,6 +50,7 @@ class CommandParameters:
     combo_option_map: OptionMap                          #: Mapping of {short opt: Parameter} (no dash characters)
     groups: List[ParamGroup]                             #: List of ParamGroup objects
     positionals: List[BasePositional]                    #: List of positional Parameters
+    _deferred_positionals: List[BasePositional] = ()     #: Positional Parameters that are deferred to sub commands
     option_map: OptionMap                                #: Mapping of {--opt / -opt: Parameter}
 
     def __init__(self, command: CommandCls, command_parent: Optional[CommandCls], config: CommandConfig):
@@ -75,6 +76,15 @@ class CommandParameters:
             return self.parent.pass_thru
         return None
 
+    @cached_property
+    def all_positionals(self) -> List[BasePositional]:
+        try:
+            if not self.parent.sub_command:
+                return self.parent.all_positionals + self.positionals
+        except AttributeError:
+            pass
+        return self.positionals
+
     @cached_property
     def always_available_action_flags(self) -> Tuple[ActionFlag, ...]:
         """
@@ -92,8 +102,8 @@ class CommandParameters:
         else:
             formatter_factory = self.config.command_formatter or CommandHelpFormatter
         formatter = formatter_factory(self.command, self)
+        formatter.maybe_add_positionals(self.all_positionals)
         formatter.maybe_add_option(self._pass_thru)
-        formatter.maybe_add_positionals(self.positionals)
         formatter.maybe_add_options(self.options)
         formatter.maybe_add_groups(self.groups)
         return formatter
@@ -129,36 +139,38 @@ class CommandParameters:
 
     # region Initialization
 
-    def _process_parameters(self):
-        """
-        Process all of the :class:`.Parameter` / :class:`.ParamGroup` members in the associated :class:`.Command` class.
-        """
+    def _iter_parameters(self) -> Iterator[ParamBase]:
         name_param_map = {}  # Allow subclasses to override names, but not within a given command
-        positionals = []
-        options = []
-        groups = set()
-
         for attr, param in self.command.__dict__.items():
             if attr.startswith('__') or not isinstance(param, ParamBase):  # Name mangled Parameters are still processed
                 continue
-
-            name = param.name
             try:
-                other_attr, other_param = name_param_map[name]
+                other_attr, other_param = name_param_map[param.name]
             except KeyError:
-                name_param_map[name] = (attr, param)
+                name_param_map[param.name] = (attr, param)
+                yield param
             else:
                 raise CommandDefinitionError(
                     'Name conflict - multiple parameters within a Command cannot have the same name - conflicting'
                     f' params: {other_attr}={other_param}, {attr}={param}'
                 )
 
+    def _process_parameters(self):
+        """
+        Process all of the :class:`.Parameter` / :class:`.ParamGroup` members in the associated :class:`.Command` class.
+        """
+        positionals = []
+        options = []
+        groups = set()
+
+        for param in self._iter_parameters():
             if isinstance(param, BasePositional):
                 positionals.append(param)
             elif isinstance(param, BaseOption):
                 options.append(param)
             elif isinstance(param, ParamGroup):
                 # Groups will only be discovered here when defined with `as` - ex: `with ParamGroup(...) as foo:`
+                # Group members will always be discovered at the top level since context managers share the outer scope
                 groups.add(param)
             elif isinstance(param, PassThru):
                 if self.pass_thru:
@@ -190,36 +202,37 @@ class CommandParameters:
         self.groups = sorted(groups)
 
     def _process_positionals(self, params: List[BasePositional]):
-        var_nargs_param = None
-        for param in params:
-            if self.sub_command:
-                raise CommandDefinitionError(
-                    f'Positional param={param!r} may not follow the sub command {self.sub_command} - re-order the'
-                    ' positionals, move it into the sub command(s), or convert it to an optional parameter'
-                )
-            elif var_nargs_param:
+        var_nargs_param = action_or_sub_cmd = split_index = None
+        for i, param in enumerate(params):
+            if var_nargs_param:
                 raise CommandDefinitionError(
                     f'Additional Positional parameters cannot follow {var_nargs_param} because it accepts'
                     f' a variable number of arguments with no specific choices defined - param={param!r} is invalid'
                 )
-
-            if isinstance(param, (SubCommand, Action)):
-                if self.action:  # self.sub_command being already defined is handled above
+            elif isinstance(param, (SubCommand, Action)):
+                if action_or_sub_cmd:
                     raise CommandDefinitionError(
                         f'Only 1 Action xor SubCommand is allowed in a given Command - {self.command.__name__} cannot'
-                        f' contain both {self.action} and {param}'
+                        f' contain both {action_or_sub_cmd} and {param}'
                     )
                 elif isinstance(param, SubCommand):
-                    self.sub_command = param
+                    self.sub_command = action_or_sub_cmd = param
+                    split_index = i + 1
                 else:
-                    self.action = param
+                    self.action = action_or_sub_cmd = param
                     if not param.has_choices:
                         raise CommandDefinitionError(f'No choices were registered for {self.action}')
-
-            if param.nargs.variable and not param.has_choices:
+            elif param.nargs.variable and not param.has_choices:
                 var_nargs_param = param
 
-        self.positionals = params
+        if split_index:
+            params, self._deferred_positionals = params[:split_index], params[split_index:]
+
+        parent = self.parent
+        if parent and parent._deferred_positionals:
+            self.positionals = parent._deferred_positionals + params
+        else:
+            self.positionals = params
 
     def _process_options(self, params: Collection[BaseOption]):
         parent = self.parent
@@ -277,7 +290,7 @@ class CommandParameters:
         for param in action_flags:
             if param.func is None:
                 raise ParameterDefinitionError(f'No function was registered for param={param!r}')
-            grouped_ordered_flags[param.before_main][param.order].append(param)
+            grouped_ordered_flags[param.before_main][param.order].append(param)  # noqa  # PyCharm infers the wrong type
 
         found_non_always = False
         invalid = {}
@@ -449,6 +462,7 @@ class CommandParameters:
             raise exc
 
     def try_env_params(self, ctx: Context) -> Iterator[Option]:
+        """Yields Option parameters that have an environment variable configured, and did not have any CLI values."""
         for param in self.options:
             try:
                 param.env_var  # noqa
@@ -460,7 +474,7 @@ class CommandParameters:
 
     def required_check_params(self) -> Iterator[Parameter]:
         ignore = SubCommand
-        yield from (p for p in self.positionals if p.required and not p.group and not isinstance(p, ignore))
+        yield from (p for p in self.all_positionals if p.required and not p.group and not isinstance(p, ignore))
         yield from (p for p in self.options if p.required and not p.group)
         pass_thru = self._pass_thru
         if pass_thru and pass_thru.required and not pass_thru.group:

{cli_command_parser-2023.4.10 → cli_command_parser-2023.4.16}/lib/cli_command_parser/commands.py

@@ -108,11 +108,11 @@ class Command(ABC, metaclass=CommandMeta):
         cmd_cls = cls
         with ExitStack() as stack:
             stack.enter_context(ctx)
-            sub_cmd = CommandParser.parse_args(ctx)
+            sub_cmd = CommandParser.parse_args_and_get_next_cmd(ctx)
             while sub_cmd:
                 cmd_cls = sub_cmd
                 ctx = stack.enter_context(ctx._sub_context(cmd_cls))
-                sub_cmd = CommandParser.parse_args(ctx)
+                sub_cmd = CommandParser.parse_args_and_get_next_cmd(ctx)
 
             return cmd_cls()
 

{cli_command_parser-2023.4.10 → cli_command_parser-2023.4.16}/lib/cli_command_parser/config.py

@@ -24,6 +24,7 @@ __all__ = [
     'OptionNameMode',
     'SubcommandAliasHelpMode',
     'AmbiguousComboMode',
+    'AllowLeadingDash',
     'DEFAULT_CONFIG',
 ]
 
@@ -178,6 +179,36 @@ class AmbiguousComboMode(MissingMixin, Enum):
     STRICT = 'strict'           # Reject multi-char short options that overlap with a single char one before parsing
 
 
+class AllowLeadingDash(Enum):
+    """
+    How a given Parameter should handle values with a leading dash (``-``).  Only configurable at the Parameter level,
+    not the Command level.
+
+    The behavior based on each supported option:
+
+    :NUMERIC: Allow numeric values like ``-5`` and ``-1.3``, but reject values like ``-d``.
+    :ALWAYS: Always allow values with a leading dash.
+    :NEVER: Never allow values with a leading dash.
+    """
+
+    NUMERIC = 'numeric'     # Allow a leading dash when the value is numeric
+    ALWAYS = 'always'       # Always allow a leading dash
+    NEVER = 'never'         # Never allow a leading dash
+
+    @classmethod
+    def _missing_(cls, value):
+        if isinstance(value, str):
+            try:
+                return cls._member_map_[value.upper()]  # noqa
+            except KeyError:
+                pass
+        elif value is True:
+            return cls.ALWAYS
+        elif value is False:
+            return cls.NEVER
+        return super()._missing_(value)  # noqa
+
+
 # endregion
 
 

{cli_command_parser-2023.4.10 → cli_command_parser-2023.4.16}/lib/cli_command_parser/context.py

@@ -32,31 +32,12 @@ if TYPE_CHECKING:
     from .parameters import Parameter, ActionFlag
     from .typing import Bool, ParamOrGroup, CommandType, AnyConfig, OptStr, PathLike
 
-__all__ = [
-    'Context',
-    'ctx',
-    'get_current_context',
-    'get_or_create_context',
-    'get_context',
-    'get_parsed',
-    'get_raw_arg',
-    'ParseState',
-]
+__all__ = ['Context', 'ctx', 'get_current_context', 'get_or_create_context', 'get_context', 'get_parsed', 'get_raw_arg']
 
 _context_stack = ContextVar('cli_command_parser.context.stack', default=[])
 _TERMINAL = Terminal()
 
 
-class ParseState(Enum):
-    INITIAL = 1
-    COMPLETE = 2
-    FAILED = 3
-
-    @property
-    def done(self) -> bool:
-        return self._value_ > 1
-
-
 class Context(AbstractContextManager):  # Extending AbstractContextManager to make PyCharm's type checker happy
     """
     The parsing context.
@@ -69,6 +50,7 @@ class Context(AbstractContextManager):  # Extending AbstractContextManager to ma
     prog: OptStr = None
     _terminal_width: Optional[int]
     allow_argv_prog: Bool = True
+    _provided: Dict[ParamOrGroup, int]
 
     def __init__(
         self,
@@ -82,7 +64,6 @@ class Context(AbstractContextManager):  # Extending AbstractContextManager to ma
     ):
         self.command = command
         self.parent = parent
-        self.state = ParseState.INITIAL
         self.config = _normalize_config(config, kwargs, parent, command)
         if parent is not None:
             self._set_argv(parent.prog, argv)
@@ -128,8 +109,7 @@ class Context(AbstractContextManager):  # Extending AbstractContextManager to ma
         return self.__class__(argv, command, parent=self, **kwargs)
 
     def __repr__(self) -> str:
-        cmd_name = getattr(self.command, '__name__', None)
-        return f'<{self.__class__.__name__}[state={self.state}, command={cmd_name}]>'
+        return f'<{self.__class__.__name__}[command={getattr(self.command, "__name__", None)}]>'
 
     def __enter__(self) -> Context:
         _context_stack.get().append(self)
@@ -182,7 +162,7 @@ class Context(AbstractContextManager):  # Extending AbstractContextManager to ma
 
             params = self.params
             if params:
-                for group in (params.positionals, params.options, (params.pass_thru,)):
+                for group in (params.all_positionals, params.options, (params.pass_thru,)):
                     for param in group:
                         if param and param not in exclude:
                             try:
@@ -220,7 +200,7 @@ class Context(AbstractContextManager):  # Extending AbstractContextManager to ma
         try:
             return self._parsed[param]
         except KeyError:
-            self._parsed[param] = value = param._init_value_factory(self.state)
+            self._parsed[param] = value = param._init_value_factory()
             return value
 
     def set_parsed_value(self, param: Parameter, value: Any):
@@ -237,6 +217,9 @@ class Context(AbstractContextManager):  # Extending AbstractContextManager to ma
         """Not intended to be called by users.  Used by Parameters during parsing to handle nargs."""
         return self._provided[param]
 
+    def get_missing(self) -> List[Parameter]:
+        return [p for p in self.params.required_check_params() if self._provided[p] == 0]
+
     # endregion
 
     # region Actions

{cli_command_parser-2023.4.10 → cli_command_parser-2023.4.16}/lib/cli_command_parser/conversion/command_builder.py

@@ -3,7 +3,7 @@ from __future__ import annotations
 import keyword
 import logging
 from abc import ABC, abstractmethod
-from ast import literal_eval, Attribute, Name, GeneratorExp, Subscript, DictComp, ListComp, SetComp
+from ast import literal_eval, Attribute, Name, GeneratorExp, Subscript, DictComp, ListComp, SetComp, Constant, Str
 from dataclasses import dataclass, fields
 from itertools import count
 from typing import TYPE_CHECKING, Union, Optional, Iterator, Iterable, Type, TypeVar, Generic, List, Tuple
@@ -31,13 +31,16 @@ def convert_script(script: Script, add_methods: bool = False) -> str:
 
 class Converter(Generic[AC], ABC):
     converts: Type[AC] = None
+    newline_between_members: bool = False
     _ac_converter_map = {}
 
-    def __init_subclass__(cls, converts: Type[AC] = None, **kwargs):
+    def __init_subclass__(cls, converts: Type[AC] = None, newline_between_members: bool = None, **kwargs):
         super().__init_subclass__(**kwargs)
         if converts:
             cls.converts = converts
             cls._ac_converter_map[converts] = cls
+        if newline_between_members is not None:
+            cls.newline_between_members = newline_between_members
 
     def __init__(self, ast_obj: Union[AC, Script], parent: Optional[Converter] = None):
         self.ast_obj = ast_obj
@@ -90,7 +93,10 @@ class ConverterGroup(Generic[C]):
         yield from self.members
 
     def format_all(self, indent: int = 0) -> Iterator[str]:
-        for member in self.members:
+        newline_between_members = self.member_type.newline_between_members
+        for i, member in enumerate(self.members):
+            if i and newline_between_members:
+                yield ''
             yield from member.format_lines(indent)
 
 
@@ -284,7 +290,7 @@ class ParserConverter(CollectionConverter[AstArgumentParser], converts=AstArgume
     # endregion
 
 
-class GroupConverter(CollectionConverter[ArgGroup], converts=ArgGroup):
+class GroupConverter(CollectionConverter[ArgGroup], converts=ArgGroup, newline_between_members=True):
     ast_obj: ArgGroup
 
     def format_lines(self, indent: int = 4) -> Iterator[str]:
@@ -364,6 +370,10 @@ class ParamConverter(Converter[ParserArg], converts=ParserArg):
         return next(name for name in self._attr_name_candidates() if name not in RESERVED)
 
     def _attr_name_candidates(self) -> Iterator[str]:
+        dest = self.ast_obj.init_func_raw_kwargs.get('dest')
+        if dest is not None and isinstance(dest, (Constant, Str)):  # Str is for 3.7 compatibility
+            yield getattr(dest, dest._fields[0])  # .value for Constant, .s for Str
+
         long, short, plain = self._grouped_opt_strs
         if self.is_positional or self.is_pass_thru:
             yield from plain
@@ -439,6 +449,7 @@ class ParamConverter(Converter[ParserArg], converts=ParserArg):
         nargs = self.ast_obj.init_func_kwargs.get('nargs')
         if not nargs:
             return False
+        # TODO: Refactor to take advantage of new nargs=REMAINDER support
         return nargs in self.ast_obj.get_tracked_refs('argparse', 'REMAINDER', ())
 
     @cached_property
@@ -637,9 +648,16 @@ class FlagArgs(OptionArgs):
                 action = None
         else:
             if default == opposite:
-                default = None
+                const = None
+                if action == 'store_true':
+                    default = None
+            elif not default and action == 'store_false':
+                default = 'True'
+                const = None
+            else:
+                const = value if default else None
+
             action = None
-            const = value if default else None
 
         kwargs['type'] = kwargs['nargs'] = None
         if action:

{cli_command_parser-2023.4.10 → cli_command_parser-2023.4.16}/lib/cli_command_parser/conversion/visitor.py

@@ -137,20 +137,22 @@ class ScriptVisitor(NodeVisitor):
     # endregion
 
     def resolve_ref(self, name: Union[str, AST, Attribute, Name, expr]):
-        if not isinstance(name, str):
-            name = get_name_repr(name)
-        try:
-            return self.scopes[name]
-        except KeyError:
-            pass
-        try:
-            obj_name, attr = name.rsplit('.', 1)
-        except ValueError:
-            return None
-        try:
-            obj = self.scopes[obj_name]
-        except KeyError:
-            return None
+        if isinstance(name, Attribute) and isinstance(name.value, Call):
+            obj = self.visit_Call(name.value)
+            attr = name.attr
+        else:
+            if not isinstance(name, str):
+                name = get_name_repr(name)
+            try:
+                return self.scopes[name]
+            except KeyError:
+                pass
+            try:
+                obj_name, attr = name.rsplit('.', 1)
+                obj = self.scopes[obj_name]
+            except (ValueError, KeyError):
+                return None
+
         try:
             can_call = attr in obj.visit_funcs
         except (AttributeError, TypeError):

{cli_command_parser-2023.4.10 → cli_command_parser-2023.4.16}/lib/cli_command_parser/core.py

@@ -162,12 +162,7 @@ class CommandMeta(ABCMeta, type):
         else:
             return first if include_abc else parent
 
-        try:
-            mro = type.mro(cls)[1:]
-        except TypeError:  # a Command object was provided instead of a Command class
-            cls = cls.__class__
-            mro = type.mro(cls)[1:]
-
+        cls, mro = _mro(cls)
         first = parent = None
         for parent_cls in mro:
             if isinstance(parent_cls, mcs):
@@ -200,6 +195,14 @@ class CommandMeta(ABCMeta, type):
         return meta
 
 
+def _mro(cmd_cls):
+    try:
+        return cmd_cls, type.mro(cmd_cls)[1:-1]  # 0 is always the class itself, -1 is always object
+    except TypeError:  # a Command object was provided instead of a Command class
+        cmd_cls = cmd_cls.__class__
+        return cmd_cls, type.mro(cmd_cls)[1:-1]
+
+
 def _choice_items(choice: OptStr, choices: Optional[Choices]) -> Sequence[Tuple[OptStr, OptStr]]:
     if not choices:
         return ((choice, None),)  # noqa

{cli_command_parser-2023.4.10 → cli_command_parser-2023.4.16}/lib/cli_command_parser/formatting/commands.py

@@ -57,7 +57,7 @@ class CommandHelpFormatter:
         if meta.usage:
             return meta.usage
 
-        params = self.params.positionals + self.params.options  # noqa
+        params = self.params.all_positionals + self.params.options  # noqa
         pass_thru = self.params.pass_thru
         if pass_thru is not None:
             params.append(pass_thru)
@@ -155,7 +155,7 @@ def get_formatter(command: CommandAny) -> CommandHelpFormatter:
 
 def get_usage_sub_cmds(command: CommandCls):
     cmd_mcs: Type[CommandMeta] = command.__class__  # Using metaclass to avoid potentially overwritten attrs
-    parent: CommandType = cmd_mcs.parent(command)
+    parent: CommandType = cmd_mcs.parent(command, False)
     if not parent:
         return []
 

{cli_command_parser-2023.4.10 → cli_command_parser-2023.4.16}/lib/cli_command_parser/formatting/params.py

@@ -405,7 +405,6 @@ class PassThruHelpFormatter(ParamHelpFormatter, param_cls=PassThru):
 
 class GroupHelpFormatter(ParamHelpFormatter, param_cls=ParamGroup):  # noqa  # pylint: disable=W0223
     required_formatter_map: BoolFormatterMap = {True: '{{{}}}'.format, False: '[{}]'.format}
-    # TODO: #18 Group order changes between invocations - should be sorted as declared or alphanumerically (config?)
 
     def _get_choice_delim(self) -> str:
         param: ParamGroup = self.param
@@ -425,16 +424,16 @@ class GroupHelpFormatter(ParamHelpFormatter, param_cls=ParamGroup):  # noqa  # p
         if description:
             return description
         group = self.param
-        if not group.description and not group._name:
-            if ctx.config.show_group_type and (group.mutually_exclusive or group.mutually_dependent):
-                return 'Mutually {} options'.format('exclusive' if group.mutually_exclusive else 'dependent')
-            else:
-                return 'Optional arguments'
-        else:
+        if group.description or group._name:
             description = group.description or f'{group.name} options'
             if ctx.config.show_group_type and (group.mutually_exclusive or group.mutually_dependent):
-                description += ' (mutually {})'.format('exclusive' if group.mutually_exclusive else 'dependent')
+                description += f' (mutually {"exclusive" if group.mutually_exclusive else "dependent"})'
             return description
+        elif ctx.config.show_group_type and (group.mutually_exclusive or group.mutually_dependent):
+            return f'Mutually {"exclusive" if group.mutually_exclusive else "dependent"} options'
+
+        adjective = 'Required' if group.required else 'Other' if group.contains_required else 'Optional'
+        return f'{adjective} arguments'
 
     def _get_spacer(self) -> str:
         group = self.param