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

{cli_command_parser-2024.11.2/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.11.2
+Version: 2024.12.15
 Summary: CLI Command Parser
 Home-page: https://github.com/dskrypa/cli_command_parser
 Author: Doug Skrypa

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

{cli_command_parser-2024.11.2 → 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.11.2 → 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.11.2 → 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

{cli_command_parser-2024.11.2 → cli_command_parser-2024.12.15}/lib/cli_command_parser/parameters/actions.py

@@ -72,41 +72,41 @@ class ParamAction(ABC):
     # region Add Parsed Value / Constant Methods
 
     @abstractmethod
-    def add_value(self, value: str, *, opt: str = None, combo: bool = False, joined: bool = False) -> Found:
+    def add_value(self, value: str, *, combo: bool = False, joined: bool = False, env_var: str = None) -> Found:
         """
         Execute this action for the given Parameter and value.
 
         :param value: The value that was provided, if any.
-        :param opt: The option string that preceded the given value in the case of optional params, or that
-          represents a flag so a constant value can be stored, if any.
         :param combo: Only True when a short option was provided, where the option string was combined with
           either a real value or a sequence of 1-char combinable versions of short option strings.
         :param joined: True if the value was provided as ``--option=value``, False otherwise.
+        :param env_var: The name of the environment variable that was used as the source of the given value, if
+          applicable.
         :return: The number of new values discovered
         """
         raise NotImplementedError
 
+    def add_env_value(self, value: str, env_var: str) -> Found:
+        return self.add_value(value, env_var=env_var)
+
     # Note: Not used yet
-    # def add_values(self, values: Sequence[str], *, opt: str = None, combo: bool = False) -> Found:
+    # def add_values(self, values: Sequence[str], *, combo: bool = False) -> Found:
     #     added = 0
     #     for value in values:
-    #         added += self.add_value(value, opt=opt, combo=combo)
+    #         added += self.add_value(value, combo=combo)
     #     return added
 
     def add_const(self, *, opt: str = None, combo: bool = False) -> Found:  # noqa
         ctx.record_action(self.param)
         raise MissingArgument(self.param)
 
-    def add_env_value(self, value: str, env_var: str):
-        return self.add_value(value)
-
     # endregion
 
     # region Parsing
 
     def would_accept(self, value: str, combo: bool = False) -> bool:
         try:
-            normalized = self.param.prepare_value(value, combo, True)
+            normalized = self.param.prepare_validation_value(value, combo)
         except BadArgument:
             return False
         return self.param.is_valid_arg(normalized)
@@ -225,7 +225,7 @@ class ConstMixin:
     #
     #     parsed.extend(consts)
 
-    def add_env_value(self, value: str, env_var: str):
+    def add_env_value(self, value: str, env_var: str) -> Found:
         const, use_value = self.param.get_env_const(value, env_var)
         # The const may only be _NotSet once StoreValueOrConst / AppendValueOrConst are put into use
         # if const is _NotSet:  # It does not support storing constants
@@ -250,15 +250,15 @@ class Store(ValueMixin, ParamAction, default=None, accepts_values=True):
 
     # region Add Parsed Value / Constant Methods
 
-    def add_value(self, value: str, *, opt: str = None, combo: bool = False, joined: Bool = False) -> Found:
+    def add_value(self, value: str, *, combo: bool = False, joined: Bool = False, env_var: str = None) -> Found:
         ctx.record_action(self.param)
-        value = self.param.prepare_value(value, combo)
+        value = self.param.prepare_value(value, combo, env_var)
         self.param.validate(value, joined)
         self.set_value(value)
         return 1
 
     # Note: Not used yet
-    # def add_values(self, values: Sequence[str], *, opt: str = None, combo: bool = False) -> Found:
+    # def add_values(self, values: Sequence[str], *, combo: bool = False) -> Found:
     #     ctx.record_action(self.param)
     #     if not values:
     #         raise MissingArgument(self.param)
@@ -286,15 +286,15 @@ class Append(ValueMixin, ParamAction, accepts_values=True):
 
     # region Add Parsed Value / Constant Methods
 
-    def add_value(self, value: str, *, opt: str = None, combo: bool = False, joined: Bool = False) -> Found:
+    def add_value(self, value: str, *, combo: bool = False, joined: Bool = False, env_var: str = None) -> Found:
         ctx.record_action(self.param)
-        value = self.param.prepare_value(value, combo)
+        value = self.param.prepare_value(value, combo, env_var)
         self.param.validate(value)
         self.append_value(value)
         return 1
 
     # Note: Not used yet
-    # def add_values(self, values: Sequence[str], *, opt: str = None, combo: bool = False) -> Found:
+    # def add_values(self, values: Sequence[str], *, combo: bool = False) -> Found:
     #     ctx.record_action(self.param)
     #     if not values:
     #         raise MissingArgument(self.param)
@@ -385,7 +385,7 @@ class BasicConstAction(ConstMixin, ParamAction, ABC, accepts_consts=True):
 
     # region Add Parsed Value / Constant Methods
 
-    def add_value(self, value: str, *, opt: str = None, combo: bool = False, joined: Bool = False) -> Found:  # noqa
+    def add_value(self, value: str, *, combo: bool = False, joined: Bool = False, env_var: str = None) -> Found:  # noqa
         ctx.record_action(self.param)
         raise BadArgument(self.param, f'does not accept values, but {value=} was provided')
 
@@ -471,9 +471,9 @@ class Count(ParamAction, accepts_values=True, accepts_consts=True):
         self._add(self.param.get_const(opt))
         return 1
 
-    def add_value(self, value: str, *, opt: str = None, combo: bool = False, joined: Bool = False) -> Found:
+    def add_value(self, value: str, *, combo: bool = False, joined: Bool = False, env_var: str = None) -> Found:
         ctx.record_action(self.param)
-        value = self.param.prepare_value(value, combo)
+        value = self.param.prepare_value(value, combo, env_var)
         self.param.validate(value, joined)
         self._add(value)
         return 1
@@ -486,7 +486,7 @@ class Concatenate(Append):
 
     # region Add Parsed Value / Constant Methods
 
-    def add_value(self, value: str, *, opt: str = None, combo: bool = False, joined: Bool = False) -> Found:
+    def add_value(self, value: str, *, combo: bool = False, joined: Bool = False, env_var: str = None) -> Found:
         param = self.param
         values = value.split()
         if not param.is_valid_arg(' '.join(values)):
@@ -525,7 +525,7 @@ class StoreAll(Store):
 
     # region Add Parsed Value / Constant Methods
 
-    def add_values(self, values: list[str], *, opt: str = None, combo: bool = False) -> Found:
+    def add_values(self, values: list[str], *, combo: bool = False) -> Found:
         param = self.param
         ctx.record_action(param)
 

{cli_command_parser-2024.11.2 → cli_command_parser-2024.12.15}/lib/cli_command_parser/parameters/base.py

@@ -325,20 +325,28 @@ class Parameter(ParamBase, Generic[T_co], ABC):
     def get_env_const(self, value: str, env_var: str) -> tuple[T_co, bool]:
         return _NotSet, False
 
-    def prepare_value(self, value: str, short_combo: Bool = False, pre_action: Bool = False) -> T_co:
-        type_func = self.type
-        if type_func is None or (pre_action and isinstance(type_func, InputType) and type_func.is_valid_type(value)):
+    def prepare_value(self, value: str, short_combo: Bool = False, env_var: str = None) -> T_co:
+        if self.type is None:
             return value
         try:
-            return type_func(value)
+            return self.type(value)
         except InvalidChoiceError as e:
-            raise InvalidChoice(self, e.invalid, e.choices) from e
+            raise InvalidChoice(self, e.invalid, e.choices, env_var) from e
         except InputValidationError as e:
-            raise BadArgument(self, str(e)) from e
+            suffix = f' from env var={env_var!r}' if env_var else ''
+            raise BadArgument(self, f'invalid input{suffix} - {e}') from e
         except (TypeError, ValueError) as e:
-            raise BadArgument(self, f'bad {value=} for type={type_func!r}: {e}') from e
+            suffix = f' from env var={env_var!r}' if env_var else ''
+            raise BadArgument(self, f'bad {value=} for type={self.type!r}{suffix}: {e}') from e
         except Exception as e:
-            raise BadArgument(self, f'unable to cast {value=} to type={type_func!r}') from e
+            suffix = f' from env var={env_var!r}' if env_var else ''
+            raise BadArgument(self, f'unable to cast {value=} to type={self.type!r}{suffix}') from e
+
+    def prepare_validation_value(self, value: str, short_combo: Bool = False) -> T_co:
+        if self.type is None or (isinstance(self.type, InputType) and self.type.is_valid_type(value)):
+            return value
+        else:
+            return self.prepare_value(value, short_combo)
 
     def validate(self, value: Union[T_co, None], joined: Bool = False):
         if not isinstance(value, str) or not value or not value[0] == '-':

{cli_command_parser-2024.11.2 → cli_command_parser-2024.12.15}/lib/cli_command_parser/parameters/options.py

@@ -192,9 +192,9 @@ class Flag(BaseOption[Union[TD, TC]], actions=(StoreConst, AppendConst)):
         try:
             parsed = self.type(value)
         except Exception as e:
-            raise ParamUsageError(self, f'unable to parse {value=} from {env_var=}: {e}') from e
+            raise ParamUsageError(self, f'unable to parse {value=} from env var={env_var!r}: {e}') from e
         if self.use_env_value and parsed != self.const and parsed != self.default:
-            raise BadArgument(self, f'invalid value={parsed!r} from {env_var=}')
+            raise BadArgument(self, f'invalid value={parsed!r} from env var={env_var!r}')
         return parsed, self.use_env_value
 
 
@@ -308,10 +308,10 @@ class TriFlag(BaseOption[Union[TD, TC, TA]], ABC, actions=(StoreConst, AppendCon
         try:
             parsed = self.type(value)
         except Exception as e:
-            raise ParamUsageError(self, f'unable to parse {value=} from {env_var=}: {e}') from e
+            raise ParamUsageError(self, f'unable to parse {value=} from env var={env_var!r}: {e}') from e
         if self.use_env_value:
             if parsed not in self.consts and parsed != self.default:
-                raise BadArgument(self, f'invalid value={parsed!r} from {env_var=}')
+                raise BadArgument(self, f'invalid value={parsed!r} from env var={env_var!r}')
             return parsed, True
         else:
             const = self.consts[0] if parsed else self.consts[1]
@@ -491,14 +491,17 @@ class Counter(BaseOption[int], actions=(Count,)):
             self.default_cb = None
         return super().register_default_cb(method)
 
-    def prepare_value(self, value: Optional[str], short_combo: bool = False, pre_action: bool = False) -> int:
+    def prepare_value(self, value: Optional[str], short_combo: bool = False, env_var: str = None) -> int:
         try:
             return self.type(value)
         except (ValueError, TypeError) as e:
             combinable = self.option_strs.combinable
             if short_combo and combinable and all(c in combinable for c in value):
                 return len(value) + 1  # +1 for the -short that preceded this value
-            raise BadArgument(self, f'bad counter {value=}') from e
+            suffix = f' from env var={env_var!r}' if env_var else ''
+            raise BadArgument(self, f'bad counter {value=}{suffix}') from e
+
+    prepare_validation_value = prepare_value
 
     def validate(self, value: Any, joined: Bool = False):
         if value is None or isinstance(value, self.type):

{cli_command_parser-2024.11.2 → cli_command_parser-2024.12.15}/lib/cli_command_parser/parser.py

@@ -36,6 +36,9 @@ log = logging.getLogger(__name__)
 
 _PRE_INIT = ActionPhase.PRE_INIT
 
+# TODO: When an invalid choice for a positional is provided with -h / --help, the invalid choice error is shown instead
+#  of help, but help should be shown instead
+
 
 class CommandParser:
     """Stateful parser used for a single pass of argument parsing"""
@@ -111,8 +114,6 @@ class CommandParser:
         self._parse_env_vars(ctx)
 
     def _parse_env_vars(self, ctx: Context):
-        # TODO: It would be helpful to store arg provenance for error messages, especially for a conflict between
-        #  mutually exclusive params when they were provided via env
         for param in ctx.missing_options_with_env_var():
             for env_var in param.env_vars():
                 try:
@@ -220,7 +221,7 @@ class CommandParser:
         self, opt: str, param: BaseOption, value: OptStr, combo: bool = False, joined: Bool = False
     ):
         if value is not None:
-            param.action.add_value(value, opt=opt, combo=combo, joined=joined)
+            param.action.add_value(value, combo=combo, joined=joined)
         elif param.action.accepts_consts and not param.action.accepts_values:
             param.action.add_const(opt=opt, combo=combo)
         elif not self.consume_values(param) and param.action.accepts_consts:

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

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