Added new ActionFail for arguments that should fail parsing with a given error message (#335).

Author: mauvilsa

CHANGELOG.rst

@@ -19,6 +19,8 @@ Added
 ^^^^^
 - Support for Python 3.14 (`#753
   <https://github.com/omni-us/jsonargparse/pull/753>`__).
+- New ``ActionFail`` for arguments that should fail parsing with a given error
+  message (`#759 <https://github.com/omni-us/jsonargparse/pull/759>`__).
 
 Fixed
 ^^^^^

DOCUMENTATION.rst

@@ -398,6 +398,37 @@ a function, it is recommended to implement a type, see :ref:`custom-types`.
     parser.add_argument("--int_or_off", type=int_or_off)
 
 
+Always fail arguments
+---------------------
+
+In scenarios where an argument should be included in the parser but should
+always fail parsing, there is the :class:`.ActionFail` action. This is
+particularly useful when a feature is optional and only accessible if a specific
+package is installed:
+
+.. testsetup:: always-fail
+
+    parser = ArgumentParser()
+    some_package_installed = False
+
+.. testcode:: always-fail
+
+    from jsonargparse import ActionFail
+
+    if some_package_installed:
+        parser.add_argument("--module", type=SomeClass)
+    else:
+        parser.add_argument(
+            "--module",
+            action=ActionFail(message="install 'package' to enable"),
+            help="Option unavailable due to missing 'package'",
+        )
+
+With this setup, if the argument is provided as ``--module=...`` or in a nested
+form like ``--module.child=...``, the parsing will fail and display the
+configured error message.
+
+
 .. _type-hints:
 
 Type hints

jsonargparse/_actions.py

@@ -29,8 +29,9 @@
 
 __all__ = [
     "ActionConfigFile",
-    "ActionYesNo",
+    "ActionFail",
     "ActionParser",
+    "ActionYesNo",
 ]
 
 
@@ -65,7 +66,7 @@ def _find_action_and_subcommand(
     fallback_action = None
     for action in actions:
         if action.dest == dest or f"--{dest}" in action.option_strings:
-            if isinstance(action, _ActionConfigLoad):
+            if isinstance(action, (_ActionConfigLoad, ActionFail)):
                 fallback_action = action
             else:
                 return action, None
@@ -435,6 +436,30 @@ def get_args_after_opt(self, args):
         return args[num + 1 :]
 
 
+class ActionFail(Action):
+    """Action that always fails parsing with a given error."""
+
+    def __init__(self, message: str = "option unavailable", **kwargs):
+        """Initializer for ActionFail instance.
+
+        Args:
+            message: Text for the error to show.
+        """
+        if len(kwargs) == 0:
+            self._message = message
+        else:
+            self._message = kwargs.pop("_message")
+            kwargs["default"] = SUPPRESS
+            super().__init__(**kwargs)
+
+    def __call__(self, *args, **kwargs):
+        """Always fails with given message."""
+        if len(args) == 0:
+            kwargs["_message"] = self._message
+            return ActionFail(**kwargs)
+        args[0].error(self._message)
+
+
 class ActionYesNo(Action):
     """Paired options --[yes_prefix]opt, --[no_prefix]opt to set True or False respectively."""
 

jsonargparse/_typehints.py

@@ -39,6 +39,7 @@
 from ._actions import (
     Action,
     ActionConfigFile,
+    ActionFail,
     _ActionHelpClassPath,
     _ActionPrintConfig,
     _find_action,
@@ -405,7 +406,7 @@ def parse_argv_item(arg_string):
                 action = _find_parent_action(parser, arg_base[2:])
 
         typehint = typehint_from_action(action)
-        if typehint:
+        if typehint or isinstance(action, ActionFail):
             if parse_optional_num_return == 4:
                 return action, arg_base, sep, explicit_arg
             elif parse_optional_num_return == 1:

jsonargparse_tests/test_actions.py

@@ -5,6 +5,7 @@
 import pytest
 
 from jsonargparse import (
+    ActionFail,
     ActionParser,
     ActionYesNo,
     ArgumentError,
@@ -60,6 +61,26 @@ def test_action_config_file_argument_errors(parser, tmp_cwd):
     pytest.raises(ArgumentError, lambda: parser.parse_args(["--cfg", '{"k":"v"}']))
 
 
+# ActionFail tests
+
+
+def test_action_fail(parser):
+    parser.add_argument(
+        "--unavailable",
+        action=ActionFail(message="needs package xyz"),
+        help="Option not available due to missing package xyz",
+    )
+    help_str = get_parser_help(parser)
+    assert "--unavailable" in help_str
+    assert "Option not available due to missing package xyz" in help_str
+    defaults = parser.get_defaults()
+    assert "unavailable" not in defaults
+    with pytest.raises(ArgumentError, match="needs package xyz"):
+        parser.parse_args(["--unavailable=x"])
+    with pytest.raises(ArgumentError, match="needs package xyz"):
+        parser.parse_args(["--unavailable.child=x"])
+
+
 # ActionYesNo tests