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

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

@@ -1,130 +1,134 @@
-Metadata-Version: 2.1
-Name: cli_command_parser
-Version: 2024.11.2
-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.5.10
+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.11.2 → cli_command_parser-2025.5.10}/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.11.02'
+__version__ = '2025.05.10'
 __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-2024.11.2 → cli_command_parser-2025.5.10}/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-2025.5.10}/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-2025.5.10}/lib/cli_command_parser/inputs/choices.py

@@ -147,6 +147,12 @@ class ChoiceMap(Choices[T]):
 
         return self._case_insensitive_map_choice(value)
 
+    def fix_default(self, value: Any) -> T:
+        if value in self.choices.values():
+            return value
+        else:
+            return self(value)
+
 
 class EnumChoices(_ChoicesBase[EnumT]):
     """

{cli_command_parser-2024.11.2 → cli_command_parser-2025.5.10}/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-2025.5.10}/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)
@@ -145,6 +145,8 @@ class ParamAction(ABC):
         return self.default
 
     def finalize_default(self, value):
+        if self.param.strict_default:
+            return value
         if (type_func := self.param.type) and isinstance(type_func, InputType):
             return type_func.fix_default(value)
         return value
@@ -225,7 +227,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 +252,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 +288,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 +387,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 +473,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 +488,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 +527,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-2025.5.10}/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-2025.5.10}/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-2025.5.10}/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-2025.5.10}/lib/cli_command_parser/testing.py

@@ -94,9 +94,6 @@ class ParserTest(TestCase):
     def assert_dict_equal(self, d1, d2, msg: str = None):
         self.assertIsInstance(d1, dict, 'First argument is not a dictionary')
         self.assertIsInstance(d2, dict, 'Second argument is not a dictionary')
-        self._assert_dict_equal(d1, d2, msg)
-
-    def _assert_dict_equal(self, d1, d2, msg: str = None):
         if d1 != d2:
             self.fail(self._formatMessage(msg, f'{d1} != {d2}\n{format_dict_diff(d1, d2)}'))
 
@@ -105,7 +102,9 @@ class ParserTest(TestCase):
 
     def assert_parse_results(self, cmd_cls: CommandCls, argv: Argv, expected: Expected, msg: str = None) -> Command:
         cmd = cmd_cls.parse(argv)
-        self._assert_dict_equal(expected, cmd.ctx.get_parsed(cmd, exclude=EXCLUDE_ACTIONS), msg)
+        parsed = cmd.ctx.get_parsed(cmd, exclude=EXCLUDE_ACTIONS)
+        if expected != parsed:
+            self.fail(msg or f'Expected results ({expected}) != {parsed=}\n{format_dict_diff(expected, parsed)}')
         return cmd
 
     def assert_parse_results_cases(self, cmd_cls: CommandCls, cases: Iterable[Case], msg: str = None):