- ArgumentParser.error_handler is now deprecated and will be removed in v5.0.0.

- When parsing fails now argparse.ArgumentError is raised instead of ParserError.

Author: mauvilsa

CHANGELOG.rst

@@ -15,6 +15,11 @@ paths are considered internals and can change in minor and patch releases.
 v4.20.0 (2023-01-??)
 --------------------
 
+Changed
+^^^^^^^
+- When parsing fails now ``argparse.ArgumentError`` is raised instead of
+  ``ParserError``.
+
 Deprecated
 ^^^^^^^^^^
 - Path ``skip_check`` parameter is deprecated and will be removed in v5.0.0.
@@ -24,6 +29,8 @@ Deprecated
   absolute``.
 - ``ActionPathList`` is deprecated and will be removed in v5.0.0. Instead use as
   type ``List[<path_type>]`` with ``enable_path=True``.
+- ``ArgumentParser.error_handler`` is deprecated and will be removed in v5.0.0.
+  Instead use the new exit_on_error parameter from argparse.
 
 
 v4.19.0 (2022-12-27)

README.rst

@@ -318,7 +318,7 @@ shown above you would observe:
 
 If the parsing fails the standard behavior is that the usage is printed and the
 program is terminated. Alternatively you can initialize the parser with
-``error_handler=None`` in which case a :class:`.ParserError` is raised.
+``exit_on_error=False`` in which case an :class:`.ArgumentError` is raised.
 
 
 Override order

jsonargparse/__init__.py

@@ -1,4 +1,12 @@
-from argparse import ONE_OR_MORE, OPTIONAL, PARSER, REMAINDER, SUPPRESS, ZERO_OR_MORE
+from argparse import (
+    ONE_OR_MORE,
+    OPTIONAL,
+    PARSER,
+    REMAINDER,
+    SUPPRESS,
+    ZERO_OR_MORE,
+    ArgumentError,
+)
 
 from .actions import *
 from .cli import *
@@ -16,6 +24,7 @@
 from .util import *
 
 __all__ = [
+    'ArgumentError',
     'OPTIONAL',
     'REMAINDER',
     'SUPPRESS',

jsonargparse/actions.py

@@ -18,8 +18,8 @@
 from .util import (
     LoggerProperty,
     NoneType,
-    ParserError,
     Path,
+    argument_error,
     change_to_path_dir,
     default_config_option_help,
     get_typehint_origin,
@@ -246,7 +246,7 @@ def __call__(self, parser, namespace, value, option_string=None):
             flags = value[0].split(',')
             invalid_flags = [f for f in flags if f not in valid_flags]
             if len(invalid_flags) > 0:
-                raise ParserError(f'Invalid option "{invalid_flags[0]}" for {option_string}')
+                raise argument_error(f'Invalid option "{invalid_flags[0]}" for {option_string}')
             for flag in [f for f in flags if f != '']:
                 kwargs[valid_flags[flag]] = True
         while hasattr(parser, 'parent_parser'):
@@ -383,7 +383,7 @@ def print_help(self, call_args, baseclass, dest):
         args = self.get_args_after_opt(parser.args)
         if args:
             subparser.parse_args(args)
-            raise ParserError(f'Expected a nested --*.help option, got: {args}.')
+            raise argument_error(f'Expected a nested --*.help option, got: {args}.')
         else:
             subparser.print_help()
             parser.exit()
@@ -598,7 +598,8 @@ def add_subcommand(self, name, parser, **kwargs):
         parser.default_env = self.parent_parser.default_env
         parser.parent_parser = self.parent_parser
         parser.parser_mode = self.parent_parser.parser_mode
-        parser.error_handler = self.parent_parser.error_handler
+        parser._error_handler = self.parent_parser._error_handler
+        parser.exit_on_error = self.parent_parser.exit_on_error
         parser.logger = self.parent_parser.logger
         parser.subcommand = name
 

jsonargparse/core.py

@@ -39,6 +39,7 @@
     parent_parsers,
     previous_config,
 )
+from .deprecated import ParserDeprecations
 from .formatters import DefaultHelpFormatter, empty_help, get_env_var
 from .jsonnet import ActionJsonnet, ActionJsonnetExtVars
 from .jsonschema import ActionJsonSchema
@@ -74,14 +75,13 @@
 from .typehints import ActionTypeHint, is_subclass_spec
 from .typing import is_final_class
 from .util import (
-    ParserError,
     Path,
+    argument_error,
     change_to_path_dir,
     get_private_kwargs,
     identity,
     is_subclass,
     return_parser_if_captured,
-    usage_and_exit_error_handler,
 )
 
 __all__ = ['ActionsContainer', 'ArgumentParser']
@@ -183,7 +183,7 @@ class _ArgumentGroup(ActionsContainer, argparse._ArgumentGroup):
     parser: Optional['ArgumentParser'] = None
 
 
-class ArgumentParser(ActionsContainer, ArgumentLinking, argparse.ArgumentParser):
+class ArgumentParser(ParserDeprecations, ActionsContainer, ArgumentLinking, argparse.ArgumentParser):
     """Parser for command line, yaml/jsonnet files and environment variables."""
 
     formatter_class: Type[DefaultHelpFormatter]
@@ -195,8 +195,8 @@ def __init__(
         self,
         *args,
         env_prefix: Union[bool, str] = True,
-        error_handler: Optional[Callable[['ArgumentParser', str], None]] = usage_and_exit_error_handler,
         formatter_class: Type[DefaultHelpFormatter] = DefaultHelpFormatter,
+        exit_on_error: bool = True,
         logger: Union[bool, str, dict, logging.Logger] = False,
         version: Optional[str] = None,
         print_config: Optional[str] = '--print_config',
@@ -215,7 +215,6 @@ def __init__(
 
         Args:
             env_prefix: Prefix for environment variables. ``True`` to derive from ``prog``.
-            error_handler: Handler for parsing errors, if None raises :class:`.ParserError` exception.
             formatter_class: Class for printing help messages.
             logger: Configures the logger, see :class:`.LoggerProperty`.
             version: Program version which will be printed by the --version argument.
@@ -229,6 +228,7 @@ def __init__(
         super().__init__(*args, formatter_class=formatter_class, logger=logger, **kwargs)
         if self.groups is None:
             self.groups = {}
+        self.exit_on_error = exit_on_error
         self.required_args: Set[str] = set()
         self.save_path_content: Set[str] = set()
         self.default_config_files = default_config_files  # type: ignore
@@ -237,7 +237,6 @@ def __init__(
         self.env_prefix = env_prefix
         self.parser_mode = parser_mode
         self.dump_header = dump_header
-        self.error_handler = error_handler
         self._print_config = print_config
         if version is not None:
             self.add_argument('--version', action='version', version='%(prog)s '+version, help='Print version and exit.')
@@ -257,7 +256,7 @@ def parse_known_args(self, args=None, namespace=None):
         try:
             with patch_namespace(), parser_context(parent_parser=self, lenient_check=True), ActionTypeHint.subclass_arg_context(self):
                 namespace, args = self._parse_known_args(args, namespace)
-        except (argparse.ArgumentError, ParserError) as ex:
+        except argparse.ArgumentError as ex:
             self.error(str(ex), ex)
 
         return namespace, args
@@ -367,7 +366,7 @@ def parse_args(  # type: ignore[override]
             A config object with all parsed values.
 
         Raises:
-            ParserError: If there is a parsing error and error_handler=None.
+            ArgumentError: If the parsing fails error and exit_on_error=True.
         """
         skip_check = get_private_kwargs(kwargs, _skip_check=False)
         return_parser_if_captured(self)
@@ -427,7 +426,7 @@ def parse_object(
             A config object with all parsed values.
 
         Raises:
-            ParserError: If there is a parsing error and error_handler=None.
+            ArgumentError: If the parsing fails error and exit_on_error=True.
         """
         skip_check, skip_required = get_private_kwargs(kwargs, _skip_check=False, _skip_required=False)
 
@@ -506,7 +505,7 @@ def parse_env(
             A config object with all parsed values.
 
         Raises:
-            ParserError: If there is a parsing error and error_handler=None.
+            ArgumentError: If the parsing fails error and exit_on_error=True.
         """
         skip_check, skip_subcommands = get_private_kwargs(kwargs, _skip_check=False, _skip_subcommands=False)
 
@@ -551,7 +550,7 @@ def parse_path(
             A config object with all parsed values.
 
         Raises:
-            ParserError: If there is a parsing error and error_handler=None.
+            ArgumentError: If the parsing fails error and exit_on_error=True.
         """
         fpath = Path(cfg_path, mode=get_config_read_mode())
         with change_to_path_dir(fpath):
@@ -594,7 +593,7 @@ def parse_string(
             A config object with all parsed values.
 
         Raises:
-            ParserError: If there is a parsing error and error_handler=None.
+            ArgumentError: If the parsing fails error and exit_on_error=True.
         """
         skip_check, fail_no_subcommand = get_private_kwargs(kwargs, _skip_check=False, _fail_no_subcommand=True)
 
@@ -981,8 +980,8 @@ def get_defaults(self, skip_check: bool = False) -> Namespace:
                             skip_check=skip_check,
                             skip_required=True,
                         )
-                except (TypeError, KeyError, ParserError) as ex:
-                    raise ParserError(f'Problem in default config file "{default_config_file}" :: {ex.args[0]}') from ex
+                except (TypeError, KeyError, argparse.ArgumentError) as ex:
+                    raise argument_error(f'Problem in default config file "{default_config_file}": {ex.args[0]}') from ex
             meta = cfg.get('__default_config__')
             if isinstance(meta, list):
                 meta.append(default_config_file)
@@ -1000,14 +999,19 @@ def get_defaults(self, skip_check: bool = False) -> Namespace:
     ## Other methods ##
 
     def error(self, message: str, ex: Optional[Exception] = None) -> NoReturn:
-        """Logs error message if a logger is set, calls the error handler and raises a ParserError."""
+        """Logs error message if a logger is set and exits or raises an ArgumentError."""
         self._logger.error(message)
-        if self._error_handler is not None:
+        if callable(self._error_handler):
             self._error_handler(self, message)
-        if ex is None:
-            raise ParserError(message)
-        else:
-            raise ParserError(message) from ex
+        if not self.exit_on_error:
+            raise argument_error(message) from ex
+        elif 'JSONARGPARSE_DEBUG' in os.environ:
+            self._logger.debug('Debug enabled, thus raising exception instead of exit.')
+            raise argument_error(message) from ex
+        self.print_usage(sys.stderr)
+        args = {'prog': self.prog, 'message': message}
+        sys.stderr.write('%(prog)s: error: %(message)s\n' % args)
+        self.exit(2)
 
 
     def check_config(
@@ -1193,7 +1197,7 @@ def format_help(self) -> str:
                     if isinstance(config_files, list):
                         config_files = [str(x) for x in config_files]
                     note = f'default values below are the ones overridden by the contents of: {config_files}'
-            except ParserError as ex:
+            except argparse.ArgumentError as ex:
                 note = f'tried getting defaults considering default_config_files but failed due to: {ex}'
             group = self._default_config_files_group
             group.description = f'{self._default_config_files}, Note: {note}'
@@ -1327,27 +1331,6 @@ def _check_value_key(self, action: argparse.Action, value: Any, key: str, cfg: O
 
     ## Properties ##
 
-    @property
-    def error_handler(self) -> Optional[Callable[['ArgumentParser', str], None]]:
-        """Property for the error_handler function that is called when there are parsing errors.
-
-        :getter: Returns the current error_handler function.
-        :setter: Sets a new error_handler function (Callable[self, message:str] or None).
-
-        Raises:
-            ValueError: If an invalid value is given.
-        """
-        return self._error_handler
-
-
-    @error_handler.setter
-    def error_handler(self, error_handler: Optional[Callable[['ArgumentParser', str], None]]):
-        if callable(error_handler) or error_handler is None:
-            self._error_handler = error_handler
-        else:
-            raise ValueError('error_handler can be either a Callable or None.')
-
-
     @property
     def default_config_files(self) -> List[str]:
         """Default config file locations.

jsonargparse/deprecated.py

@@ -4,19 +4,22 @@
 import inspect
 import os
 import sys
-from argparse import Action
+from argparse import Action, ArgumentError
 from enum import Enum
-from typing import Any, Dict, Optional, Set
+from typing import Any, Callable, Dict, Optional, Set
 
 from .namespace import Namespace
 from .optionals import FilesCompleterMethod
+from .type_checking import ArgumentParser
 
 __all__ = [
     'ActionEnum',
     'ActionOperators',
     'ActionPath',
     'ActionPathList',
+    'ParserError',
     'set_url_support',
+    'usage_and_exit_error_handler',
 ]
 
 
@@ -380,7 +383,6 @@ def path_skip_check_deprecation():
     Please update your code to use the new property names and don't modify path
     attributes. The changes are: ``rel_path`` -> ``relative`` and ``abs_path``
     -> ``absolute``, ``cwd`` no name change, ``skip_check`` will be removed.
-
 """
 
 class PathDeprecations:
@@ -435,6 +437,69 @@ def skip_check(self, skip_check):
         self._skip_check = skip_check
 
 
+class DebugException(Exception):
+    pass
+
+
+@deprecated("""
+    usage_and_exit_error_handler was deprecated in v4.20.0 and will be removed
+    in v5.0.0. With the removal of error_handler, there is no longer a need for
+    this function.
+""")
+def usage_and_exit_error_handler(parser: 'ArgumentParser', message: str) -> None:
+    """Prints the usage and exits with error code 2 (same behavior as argparse).
+
+    Args:
+        parser: The parser object.
+        message: The message describing the error being handled.
+    """
+    parser.print_usage(sys.stderr)
+    args = {'prog': parser.prog, 'message': message}
+    sys.stderr.write('%(prog)s: error: %(message)s\n' % args)
+    parser.exit(2)
+
+
+error_handler_message = """
+    ArgumentParser's error_handler was deprecated in v4.20.0 and will be removed
+    in v5.0.0. Instead use the new exit_on_error parameter from argparse.
+"""
+
+
+def deprecation_warning_error_handler():
+    deprecation_warning('ArgumentParser.error_handler', error_handler_message)
+
+
+class ParserDeprecations:
+
+    def __init__(self, *args, error_handler=False, **kwargs):
+        super().__init__(*args, **kwargs)
+        self.error_handler = error_handler
+
+    @property
+    def error_handler(self) -> Optional[Callable[['ArgumentParser', str], None]]:
+        """Property for the error_handler function that is called when there are parsing errors.
+
+        :getter: Returns the current error_handler function.
+        :setter: Sets a new error_handler function (Callable[self, message:str] or None).
+
+        Raises:
+            ValueError: If an invalid value is given.
+        """
+        return self._error_handler
+
+    @error_handler.setter
+    def error_handler(self, error_handler):
+        if error_handler is not False:
+            deprecation_warning_error_handler()
+        if callable(error_handler) or error_handler in {None, False}:
+            self._error_handler = error_handler
+        else:
+            raise ValueError('error_handler can be either a Callable or None.')
+
+
+ParserError = ArgumentError
+
+
 import jsonargparse.optionals
 
 jsonargparse.optionals.import_docstring_parse = import_docstring_parse  # type: ignore