Add --on-var-failure flag to handle failure behaviors

docs/source/usage.rst

@@ -71,6 +71,10 @@ Please be aware that some arguments are required or optional based on how ``e3sm
                            (WARNING: NOT WORKING AS OF 1.8.2)
    -s, --serial          Run in serial mode (by default parallel). Useful for
                            debugging purposes.
+   --on-var-failure {ignore,fail,stop} Behavior when a variable fails:
+                           ignore - continue and exit 0 (default)
+                           fail   - process all variables, exit 1 if any failed
+                           stop   - exit immediately on first failure, useful for debugging
    optional arguments (run settings):
    --realm <realm>       The realm to process. Must be atm, lnd, mpaso or
                            mpassi. Default is atm.
@@ -162,8 +166,11 @@ when the output is intended for analysis, but is not suited for publication.
 
 Serial
 ^^^^^^
-For debugging purposes, or when running in a resource constrained environment, the "--serial" or "-s" boolean flag can be used to cause the conversion process
-to be run in serial, using the main process.
+For debugging purposes, or when running in a resource constrained environment, the "--serial" or "-s" boolean flag can be used to cause the conversion process to be run in serial, using the main process.
+
+On-var-failure
+^^^^^^^^^^^^^^^
+This optional flag controls the behavior of the tool when a variable fails to process. The default behavior is to ignore the failure and continue processing the remaining variables, exiting with a return code of 0. The "fail" option will cause the tool to continue processing all variables, but exit with a return code of 1 if any variable failed. The "stop" option will cause the tool to exit immediately on the first variable failure, which is useful for debugging.
 
 Optional arguments (run settings)
 ---------------------------------

e3sm_to_cmip/argparser.py

@@ -11,6 +11,7 @@ def setup_argparser() -> argparse.ArgumentParser:
         prog="e3sm_to_cmip",
         usage="%(prog)s [-h]",
         add_help=False,
+        formatter_class=argparse.RawTextHelpFormatter,
     )
 
     # Argument groups to organize the numerous arguments printed by --help.
@@ -38,19 +39,16 @@ def setup_argparser() -> argparse.ArgumentParser:
         "--info",
         action="store_true",
         help=(
-            "Produce information about the CMIP6 variables passed in the --var-list "
-            "argument and exit without doing any processing. There are three modes "
-            "for getting the info. (Mode 1) If you just pass the --info flag with the "
-            "--var-list then it will print out the handler information as yaml data for "
-            "the requested variable to your default output path (or to a file designated "
-            "by the --info-out path). (Mode 2) If the --freq <frequency> is passed "
-            "along with the --tables-path, then the variable handler information will "
-            "only be output if the requested variables are present in the CMIP6 table matching the freq. "
-            "NOTE: For MPAS data, one must also include --realm mpaso (or mpassi) and --map no_map. "
-            "(Mode 3) For non-MPAS data, if the --freq <freq> is passed with the --tables-path, and the "
-            "--input-path, and the input-path points to raw unprocessed E3SM files, "
-            "then an additional check will me made for if the required raw "
-            "variables are present in the E3SM native output. "
+            "Produce information about the CMIP6 variables passed in the "
+            "--var-list argument and exit without processing. Modes:\n"
+            "  1) Default: Print handler info as YAML for requested variables "
+            "to the default output path, or to a file specified by --info-out.\n"
+            "  2) With --freq <frequency> and --tables-path: Output handler info "
+            "only if variables are in the CMIP6 table matching the frequency. "
+            "For MPAS data, include --realm mpaso/mpassi and --map no_map.\n"
+            "  3) For non-MPAS data: With --freq <frequency>, --tables-path, "
+            "and --input-path pointing to raw E3SM files, check if required raw "
+            "variables are present in the E3SM native output."
         ),
     )
     optional_mode.add_argument(
@@ -68,6 +66,18 @@ def setup_argparser() -> argparse.ArgumentParser:
         action="store_true",
     )
 
+    optional_mode.add_argument(
+        "--on-var-failure",
+        choices=["ignore", "fail", "stop"],
+        default="ignore",
+        help=(
+            "Behavior when a variable fails:\n"
+            "  1) 'ignore' - continue and exit 0 (default)\n"
+            "  2) 'fail'   - process all variables, exit 1 if any failed\n"
+            "  3) 'stop'   - exit immediately on first failure, useful for debugging\n"
+        ),
+    )
+
     # ======================================================================
     # Run settings.
     # ======================================================================

e3sm_to_cmip/cmor_handlers/handler.py

@@ -26,6 +26,9 @@
 # handled appropriately.
 TIME_DIMS = ["time", "time1", "time2"]
 
+# Type alias for the dictionary representation of a VarHandler object.
+VarHandlerDict = dict[str, Any]
+
 
 class BaseVarHandler:
     def __init__(
@@ -155,7 +158,7 @@ def __eq__(self, other):
     def __str__(self):
         return yaml.dump(self.__dict__, default_flow_style=False, sort_keys=False)
 
-    def to_dict(self) -> dict[str, Any]:
+    def to_dict(self) -> VarHandlerDict:
         """
         Return __dict__ with additional entries to support existing e3sm_to_cmip
         functions.
@@ -166,7 +169,7 @@ def to_dict(self) -> dict[str, Any]:
 
         Returns
         -------
-        dict[str, Any]
+        VarHandlerDict
             __dict__ with additional entries.
         """
         # TODO: Remove this method e3sm_to_cmip functions parse VarHandler